Skip to content

armelhbobdad/bmad-module-ultracode-goal / skills/ultracode-goal

ultracode-goal

Flagged

Runs a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.

FileKindSize
SKILL.mdskill md15.9 KB
assets/module-help.csvother2.1 KB
assets/module-setup.mdmarkdown5.9 KB
assets/module.yamlconfig1.9 KB
assets/ucg-awareness/bmad-architecture.tomlconfig2.5 KB
assets/ucg-awareness/bmad-create-epics-and-stories.tomlconfig3.3 KB
assets/ucg-awareness/bmad-prd.tomlconfig2.1 KB
assets/ucg-awareness/bmad-testarch-nfr.tomlconfig1.8 KB
assets/ucg-awareness/bmad-testarch-test-design.tomlconfig3.1 KB
assets/ucg-awareness/shaping-decision.mdmarkdown6.8 KB
assets/ucg-awareness/ucg-create-story.tomlconfig3.3 KB
customize.tomlconfig9.8 KB
references/define-done.mdmarkdown15.4 KB
references/execute.mdmarkdown116.7 KB
references/finalize.mdmarkdown39.2 KB
references/gate.mdmarkdown134.5 KB
references/health-check.mdmarkdown27.0 KB
references/ingest-and-scope.mdmarkdown28.2 KB
references/preflight.mdmarkdown83.6 KB
scripts/carry_build_cache.pyscript18.6 KB
scripts/claim_check.pyscript36.3 KB
scripts/drive_epic.pyexecutablescript64.1 KB
scripts/formalize_check.pyscript83.7 KB
scripts/gate_eval.pyexecutablescript67.8 KB
scripts/gate_trail.pyexecutablescript52.6 KB
scripts/headless_envelope.pyscript12.6 KB
scripts/health_check_fp.pyscript66.5 KB
scripts/hooks/budget_stop.pyexecutablescript18.7 KB
scripts/hooks/guard_pretooluse.pyexecutablescript180.1 KB
scripts/lib/mem_common.pyscript64.6 KB
scripts/link_worktree_deps.pyscript7.1 KB
scripts/mem_observation.pyscript35.5 KB
scripts/mem_recall.pyscript19.9 KB
scripts/merge_config.pyexecutablescript13.8 KB
scripts/merge_customization.pyscript18.7 KB
scripts/merge_help_csv.pyscript9.5 KB
scripts/moved_ac_check.pyscript10.0 KB
scripts/mutate_check.pyscript64.4 KB
scripts/operator_owed.pyscript17.0 KB
scripts/preflight_check.pyscript115.2 KB
scripts/probe_servers.pyscript38.7 KB
scripts/red_ids.pyscript14.0 KB
scripts/status_render.pyscript26.0 KB
scripts/story_sizing.pyexecutablescript11.7 KB
scripts/tests/bench_ucg_formalize.mdmarkdown7.3 KB
scripts/tests/fixtures/claude_mem_real_payload.jsonconfig3.4 KB
scripts/tests/fixtures/engine-6.12/README.mdmarkdown957 B
scripts/tests/fixtures/engine-6.12/config_utils.pyscript4.1 KB
scripts/tests/fixtures/engine-6.12/resolve_customization.pyexecutablescript5.1 KB
scripts/tests/fixtures/engine/README.mdmarkdown1.0 KB
scripts/tests/fixtures/engine/resolve_customization.pyexecutablescript8.0 KB
scripts/tests/fixtures/execute_pre_verification_axes.mdmarkdown29.1 KB
scripts/tests/fixtures/execute_resume_clause_no_baseline.mdmarkdown215 B
scripts/tests/fixtures/execute_run_status_preedit.mdmarkdown1.2 KB
scripts/tests/fixtures/execute_spine_end_no_escalation_fire.mdmarkdown194 B
scripts/tests/fixtures/execute_step0_baseline_no_sha.mdmarkdown1.0 KB
scripts/tests/fixtures/execute_ticker_line.mdmarkdown332 B
scripts/tests/fixtures/finalize_epic_complete_hook_no_escalation.mdmarkdown579 B
scripts/tests/fixtures/finalize_headless_output_hand_composed.mdmarkdown1.2 KB
scripts/tests/fixtures/finalize_no_graphify_section.mdmarkdown19.4 KB
scripts/tests/fixtures/floor/all_clean/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/floor/all_clean/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/all_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/all_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/61-1-threshold.mdmarkdown644 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/test-design-9-1.mdmarkdown291 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/test-design-9-1.mdmarkdown296 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/10-1-orphan.mdmarkdown513 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-1-orphan.mdmarkdown508 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-2-helper.mdmarkdown479 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/sprint-status.yamlconfig120 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/61-1-threshold.mdmarkdown609 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/sourced_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/sourced_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/12-1-signal.mdmarkdown552 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/12-1-signal.mdmarkdown483 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/8-1-vacuous.mdmarkdown435 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/8-1-vacuous.mdmarkdown482 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-clean-control/LABEL.mdmarkdown751 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-judgment-seed/LABEL.mdmarkdown1.1 KB
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/6-1-experience.mdmarkdown1.3 KB
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/sprint-status.yamlconfig93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/architecture-fixture.mdmarkdown93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/prd-fixture.mdmarkdown84 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-1-kernel.mdmarkdown848 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-2-floor.mdmarkdown538 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/sprint-status.yamlconfig110 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/architecture-fixture.mdmarkdown218 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/prd-fixture.mdmarkdown207 B
scripts/tests/fixtures/formalize/ready_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/ready_epic/tea/traceability/e2e-trace-summary.jsonconfig49 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/2-1-thin.mdmarkdown202 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/architecture-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/prd-fixture.mdmarkdown85 B
scripts/tests/fixtures/formalize/remediable_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/remediable_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/4-1-signal.mdmarkdown546 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/architecture-fixture.mdmarkdown103 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/prd-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/3-1-broken.mdbinary28 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/config.yamlconfig85 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/traceability/.keepother14 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/5-1-place.mdmarkdown420 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/prd-fixture.mdmarkdown226 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/wrong_root_epic/planning-artifacts/architecture-fixture.mdmarkdown187 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/gate_run_the_gate_no_ticker.mdmarkdown5.7 KB
scripts/tests/fixtures/gate_trail/light/decision-log.mdmarkdown341 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-4other41 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-6other41 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-4.jsonconfig751 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-6.jsonconfig755 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-4.mdmarkdown1.4 KB
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-6.mdmarkdown1.3 KB
scripts/tests/fixtures/gate_trail/production/decision-log.mdmarkdown783 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-1other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-2other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-3other41 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-1.mdmarkdown509 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-2.mdmarkdown300 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-1.jsonconfig648 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-2.jsonconfig679 B

scripts/mutate_check.py

View on GitHub
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""Drive a table of mutations against a green baseline, and prove each one red.

The module's anti-vacuity discipline says a guard is non-vacuous only under
mutation. Every run used to hand-roll the harness for that into scratch space
(and delete it at story end, so the next story hand-rolled it again). This is
the tracked form: a table in, a ledger out, with the properties the hand-rolled
versions kept losing built in as refusals rather than reminders.

Table (JSON array; every key a string, all five required, ``note`` optional):

    [{"file": "src/guard.py",
      "anchor": "if depth > MAX_DEPTH:",
      "replacement": "if False:",
      "command": "npx turbo run test --force --filter=guard",
      "expect_red": "test_depth_guard_fires",
      "note": "AC-3 twin"}]

Every key but ``replacement`` must be non-blank: neither empty nor only
whitespace, since a blank ``command`` exits 0 and a blank ``expect_red`` names
no test. An empty ``replacement`` deletes the anchor, the plainest mutation of
a guard clause. Delete whole statements: a deletion that leaves a block with no
body breaks the module, and reads as any mutant that breaks a module does (see
the collection errors below).

Per row, in order: assert the anchor occurs EXACTLY once (0 occurrences is
reported distinctly as STALE - the formatter-reflow signature - and more than
one as NOT UNIQUE, because a duplicated anchor mutates a different site than it
reports); back the file up; apply; run the command; classify; restore from the
backup and verify the restore BYTE-IDENTICAL. Before any row: run every
distinct command once and refuse the whole table unless all are green, because
a mutation over a red baseline proves nothing. Each write, the mutation and
the restore alike, leaves the file's mtime in a later whole second than it
had: CPython reuses cached bytecode whose recorded source mtime (in whole
seconds) and size match, so a same-size mutation and its restore written
within one second would otherwise run each other's bytecode.

Classification, per row:

  - GREEN            the command stayed green: the mutation SURVIVED. This is
                     the output that matters - a guard that cannot fail - so
                     the ledger leads with these.
  - KILLED           red, the expected case named in the output, and exactly
                     one failure counted.
  - KILLED+others    red and named, but more than one case failed (or the
                     count could not be parsed): the kill stands, the extra
                     reds are surfaced rather than silently absorbed.
  - MISATTRIBUTED    red, but the output's own count says 0 failed (checked
                     first: a collection or harness error, so no test the row
                     names went red), or no test ran (the runner counted none
                     and named none, and reported that it could not start its
                     web server: Playwright's `config.webServer` errors, a
                     port already used among them), or the expected case
                     never appears beside a failure token: something failed,
                     and it was not the observer this row claims to test. The
                     name must sit on a line that speaks of failure, because
                     verbose reporters echo PASSING names.
  - STALE / NOT UNIQUE / UNDECODABLE  the anchor (or the file) did not hold;
                     nothing was mutated for the row.

Node's test runner is read in its two default reporters. The spec reporter
(the default even when the output is captured, since Node 23) marks a failed
test with U+2716 and a passed one with U+2714, and ends with a summary line
`fail N` behind U+2139. The TAP reporter (the default for captured output
before Node 23) writes `not ok`, `ok N` for a pass and `# fail N`. jest names
a failed test on the line U+25CF heads, the only such line under its default
reporter (several test files, no --verbose) and its agent reporter (which
jest picks under Claude Code); --verbose adds U+2715 (U+00D7 on Windows).
vitest marks a failed test with U+00D7.

The failure count is read from each run's summary line: Node's `fail N`, the
`Tests` line of jest and vitest, and pytest's last line, where a test's setup
or teardown `error` counts as a failure too. jest's `Test Suites` line and
vitest's `Test Files` line count files, a test file that failed to load among
them, so once a `Tests` line was read neither is: a test file jest or vitest
cannot load runs no test. Node's test runner reports a test file whose process
failed as a failed test of its own, named after the file and located at the
file's line 1, column 1. Node prints all of one file's lines together, the
files in the order of their paths, and that test last, so each such test is
read only from the lines its run printed after the previous file test or run
summary: its own file's, and those of any passing file listed before it. A
task runner that runs several packages at once (turbo outside CI, pnpm without
`--aggregate-output`) prints their lines as they come, one package's among
another's, each behind its package's prefix, so a run's lines are the ones
that carry its prefix. That test does not count when the file could not load,
which Node shows by printing, as the last thing above that test, the error
that stopped it (whose last line names Node's version) or a warning that the
file's top-level await never settled, or by giving that test the error the
file threw in place of its own `test failed`, as it does under
`--test-isolation=none`, which imports every file in the runner's own
process. Node 22, whose only name for that option is
`--experimental-test-isolation`, gives that test no location, and a test a
file declares always has one, so a failed test with none whose error is not
Node's own is that file's too. A file that threw `undefined` (a value that is
not truthy) gets no error at all, below its entry in the spec reporter's list
of failing tests, which Node writes whole. Nor does it count when those lines
report a test whose name holds the row's `expect_red` passed or skipped,
since that test then ran to its end, or report that a test generated
asynchronous activity after it ended (an error a timer the test started threw
then, or a promise it rejected), whatever test that names: Node lists that
test as passed, and the error fails only the file's process. The test's name
and the row's `expect_red` are each read as written and with
TAP's `\\#` and `\\\\` read back as `#` and `\\`, so a row can name the test as
the spec reporter prints it or as TAP writes it (the form a TAP kill is read
by), under either reporter. So a file whose process exits non-zero after the
row's test passes or is skipped reads 0 failed, a harness error, and so does
each file whose lines report such asynchronous activity. A process that exits
or crashes during a test (a `process.exit` the mutant reaches, a heap the
test fills) reports neither that test nor such an error, so the file's test
counts, and the row reads as a kill, as a pytest test whose process dies
does. Under `--test-isolation=none` a module that calls `process.exit` ends
the runner's own process, so Node prints no file's test and no summary:
output that holds neither, and reports no failed test but a pass or a skip of
a test whose name holds the row's `expect_red`, reads 0 failed, as a file
whose process exits after that pass does, and output that reports no such
pass reads as a process that dies during a test does. Node prints a file
whose tests all pass and whose process then exits non-zero (a
`process.exitCode` the mutant sets) just as it prints one whose process dies
during a test, so such a file whose lines report no pass of the row's test
counts, and the row reads as a kill though no test went red, as a mutant in a
module several test files import can make it: run such a row with a command
that runs only the row's test file. A module that calls
`process.exit` as the file loads, or kills its process then by filling the
heap or by a signal (`process.abort`), stops the file loading, but Node
reports it as it reports a process that exits or crashes during the file's
first test: the file's own output, then the file's test, with no `Node.js v`
line. So it reads as that kill does. No line marks which file a passing test
or an error is from, so two such kills still read 0 failed: one beside a test
whose name holds the row's `expect_red` and that passes or is skipped above
the dying file's test, in that file or in one listed before it, with no
failed file test between them, and one for which the last thing Node prints
is an uncaught error that a child process printed. Nor does a line mark that
a process which reported such asynchronous activity then died during a test,
so a kill whose file reports it before the process dies reads 0 failed too.
Two runs whose lines interleave with no prefix to tell them apart can still
read a file that cannot load, or one whose process exits after the row's test
passes, as a kill. A file Node interrupts, as a `timeout` around the command
does, is counted as cancelled, not failed, so nothing is taken off for it.
Node's test runner that fails as it starts, as it does when the module
`--test-global-setup` names throws, prints only that error, thrown from its
harness, with no test and no summary: no test ran, so that reads 0 failed
too, unless another summary in the output counted a failure. An error
collecting a test module or a test class does not count either: pytest names
it with an `ERROR collecting <path>` header and a short summary line `ERROR
<path>` with no `::` test id (a directory's path when a conftest.py in it
fails to import)
or `ERROR <path>::<Class>`, an id whose last part starts with a capital letter
and that holds no parameters' `[...]`, and no test there ran. The path can
hold a space. Nor does a conftest.py that pytest loads before it collects and
cannot import: it writes `ImportError while loading conftest '<path>'.` and
stops, with no summary, before any test runs. So a mutant that breaks a module
such a file imports (a dropped colon, say) reads 0 failed rather than a kill.
When the output holds several summaries, as a command that runs two suites or
two runners does, their counts are added, and the collection errors of each
pytest run are taken off its own stats line only.

A count in another shape (mocha's `N failing`, cargo's `N failed`) is read
only when no summary counted a failure and no `-qq` run listed a failed test,
and never from a line inside pytest's report, from the first rule of its own
sections (ERRORS, FAILURES, PASSES, the warnings, the short summary and the
rest, or a `!` rule) to its stats line: a test's traceback, message or
captured output there can quote any count, such as a `0 failed` a test prints.
Any other `=` rule, such as a banner a script prints before cargo runs, opens
no report.

A failure word inside the expected name never counts: a test named "fails
when ..." supplies its own. A line never counts as a failure line when it
reports a pass or only names a test: one that starts with a pass mark
(U+2714, U+2713 as jest and vitest print it, U+221A as jest prints it on
Windows, or TAP's `ok N`) or with U+25B6 (spec) or `# Subtest:` (TAP), a
pytest line that reports `PASSED` or holds only a test id, a source line
quoted in a jest or vitest code frame, or a line of pytest's PASSES section.
Colour codes and a task runner's line prefix (turbo's `<package>:<task>: `,
pnpm's `<package dir> <script>: `) are removed before any line is read. pnpm's
package dir can be `.` or hold no `/` (`guard test: `), the shape of a line
such as `Uncaught Error: boom`, so such a prefix is removed only when pnpm
announced it, as it does each script it starts, with a line `<package dir>
<script>$ <command>`.

Exit code: 0 when every row KILLED (with or without +others); 1 when any row
is GREEN, MISATTRIBUTED, STALE, NOT UNIQUE or UNDECODABLE (each is a finding
about the suite or the table); 2 on a refusal - invalid table, red baseline, or a
restore that did not verify byte-identical (the one failure mode that leaves
the tree dirty, so it aborts the run rather than annotating it).

The task-runner cache rule binds the table's ``command`` verbatim: an
unchanged task hash replays the pre-mutation green, so every mutation
"survives" with zero failing cases. Defeat the cache in the command itself
(``--force`` and friends); this runner cannot do it for you.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import signal
import subprocess
import sys
from pathlib import Path

REQUIRED_KEYS = ("file", "anchor", "replacement", "command", "expect_red")


def _refuse(message: str) -> "SystemExit":
    """Exit 2, the refusal lane. `raise SystemExit(str)` would exit 1 and be
    indistinguishable from a findings run; the docstring promises 2."""
    print(f"REFUSED: {message}", file=sys.stderr)
    return SystemExit(2)


def _terminated(signum, _frame):
    raise SystemExit(128 + signum)


def _install_signal_unwind() -> None:
    """Convert termination signals into SystemExit so `finally` restores run.

    SIGTERM's default disposition kills the interpreter WITHOUT unwinding, so
    the finally block that restores a mutated file never executes - and TERM
    is the exact kill a harness timeout delivers mid-command. SIGKILL cannot
    be caught: after any abnormal end, `git status` before trusting the tree.
    """
    for name in ("SIGTERM", "SIGHUP", "SIGBREAK"):
        sig = getattr(signal, name, None)
        if sig is None:
            continue
        try:
            signal.signal(sig, _terminated)
        except (ValueError, OSError):
            continue

# The summary lines that count one run's failed tests, each a whole line of
# its own, so a "3 failed" quoted inside an assertion message cannot win:
# Node's `fail N` behind U+2139 (spec reporter) or `#` (TAP), the `Tests:`
# line of jest and the `Tests` line of vitest (which reads `no tests` when no
# test file loaded), and pytest's last line, with or without its `=` rule. A
# run prints one, `fail 0` included for Node, so the counts of every summary
# are added: a command that runs a passing suite first, or one runner and then
# another, does not read 0 failed.
_NODE_FAIL_SUMMARY_RE = re.compile(r"^[ \t]*(?:ℹ|#)[ \t]*fail[ \t]+(\d+)[ \t]*$", re.IGNORECASE)
_TESTS_SUMMARY_RE = re.compile(r"^\s*Tests:?\s+(.*?(?:\b\d+ total|\(\d+\))|no tests)\s*$")
# jest's `Test Suites:` line and vitest's `Test Files` line, above their
# `Tests` line, count test files, and a file that failed to load counts as a
# failed one: `Test Suites: 1 failed, 1 passed` beside `Tests: 1 passed`. Once
# a `Tests` line was read, the count the fallback shapes below would take from
# that line is no test's failure, so neither line is read for one.
_FILES_SUMMARY_RE = re.compile(r"^\s*Test (?:Suites:|Files\s)")
# pytest 9 counts passed subtests apart, `2 subtests passed`, in the same line
# (a failed subtest counts in `failed`).
_PYTEST_SUMMARY_RE = re.compile(r"^=*\s*((?:\d+ (?:subtests )?\w+, )*\d+ (?:subtests )?\w+) in [\d.]+s\b.*$")
_SUMMARY_FAILED_RE = re.compile(r"\b(\d+) failed\b")
# pytest counts a test whose fixture raised as an `error`, not a failure, and
# never prints "0 failed": without these, every setup error read 0 failed.
_PYTEST_ERRORS_RE = re.compile(r"\b(\d+) errors?\b")
# An error collecting a module is counted in the same `error` total, but no
# test in that module ran, so it is no failure. pytest heads it `ERROR
# collecting <path>` in its ERRORS section and lists it in the short summary as
# `ERROR <path>`, a path with no `::` test id after it (a setup error's line
# carries one). The path is a module's, or a directory's when a conftest.py in
# it, which pytest loads while it collects, fails to import, and it can hold a
# space. A class pytest cannot collect (a parametrize `ids` function that
# raised, say) is listed as `ERROR <path>::<Class>`, and no test in it ran
# either: an id whose last part starts with a capital letter names a class, as
# pytest's default `Test*` and PEP 8 name one, while a test's id ends at a
# function, which they name in lower case. That line is read only from the short
# summary's own header to its end (the stats line, or the next `=` or `!`
# rule): a failing fixture's captured output, printed above it, can hold a line
# such as `ERROR bound-not-enforced`, and read anywhere it took the row's own
# setup-error kill off the count. An entry can run over several lines (pytest
# prints each one's whole message under `-vv` or when `CI` is set, and under
# xdist a collection error's message is its traceback), so the section does
# not end at the first line that opens no entry, and inside it only a token
# shaped like a path pytest collected counts: one ending in `.py`, one with a
# path separator, or a name that exists under the project root (`ERROR sub`,
# a top-level directory whose conftest.py failed). A skip reason or a kill's
# message that runs over lines can hold `ERROR connection-refused`. Without
# xdist the run also stops with `Interrupted: N error(s) during collection`;
# under xdist it does not, and the other modules still run. Under `-qq` with
# xdist pytest prints neither that line nor a stats line, so a short summary
# that lists collection errors and no test (no `FAILED` entry, no `ERROR` entry
# with a test's `::` id) means no test failed. Only a test's id carries its
# parameters' `[...]`, whose text can hold `::` and a capital letter of its own
# (`test_x[App::Models::User]`), so an id that holds one never names a class.
_PYTEST_COLLECTING_RE = re.compile(r"^_+ ERROR collecting (.+?) _+$")
_PYTEST_SHORT_HEADER_RE = re.compile(r"^=+ short test summary info =+$")
_PYTEST_SECTION_END_RE = re.compile(r"^(?:=+ .+ =+|!+ .+ !+)$")
# pytest's report opens at the first of its own sections, each a rule that
# names it: those that quote a test's traceback, message or captured output
# (ERRORS, FAILURES and XFAILURES, PASSES and XPASSES, the warnings), the
# durations and the short summary. pytest alone prints a `!` rule (`Interrupted:
# N errors during collection`, `stopping after N failures`). Any other `=` rule
# opens nothing: a task runner's banner, or `=== fixtures seeded ===` that a
# passing Node test prints, is no sign that pytest ran.
_PYTEST_REPORT_OPEN_RE = re.compile(
    r"^(?:=+ (?:ERRORS|X?FAILURES|X?PASSES|warnings summary(?: \(final\))?|slowest (?:\d+ )?durations"
    r"|short test summary info) =+|!+ .+ !+)$"
)
# A short summary entry: its outcome, its path up to a `::` id or the ` - `
# before its message, and the id.
_PYTEST_SHORT_ENTRY_RE = re.compile(r"^(FAILED|ERROR) ((?:(?!::| - ).)+)((?:::(?:(?! - ).)+)?)(?: - .*)?$")
# One command can run pytest twice. A run ends at its stats line, and a `-qq`
# run, which prints none, where the next run opens: at `test session starts`,
# at an ERRORS, FAILURES or short summary rule after its own short summary,
# since pytest prints each of those before its short summary, or at a progress
# line (`..F  [100%]`), which a `-q` run prints before its report.
_PYTEST_REPORT_RE = re.compile(r"^=+ (?:ERRORS|FAILURES|short test summary info) =+$")
_PYTEST_SESSION_RE = re.compile(r"^=+ test session starts =+$")
_PYTEST_PROGRESS_RE = re.compile(r"^[.,FEsxXuy-]+\s*\[\s*(?:\d+%|\d+/\d+)\]\s*$")
_PYTEST_INTERRUPTED_RE = re.compile(r"Interrupted: (\d+) errors? during collection")
# A conftest.py pytest loads before it collects (the rootdir's, say) that fails
# to import, whatever it raised, stops pytest before any test runs, under xdist
# too: it writes this line and the error, and exits 4 with no summary and no
# `ERROR collecting` line.
_PYTEST_CONFTEST_RE = re.compile(r"^ImportError while loading conftest '.+'\.$")
# A module the root conftest names in `pytest_plugins`, or a plugin pytest loads
# at startup, that fails to import is not wrapped as a conftest error: pytest
# dies with a bare traceback through its config setup and exit 1, before any
# test runs.
_PYTEST_STARTUP_CRASH_RE = re.compile(
    r'^\s*File ".*[/\\]_pytest[/\\]config[/\\]__init__\.py", line \d+, in _prepareconfig$'
)

# Node's test runner runs each test file in a process of its own, unless
# `--test-isolation=none` makes it import them all in its own. When that
# process fails (the file cannot load, its process exits non-zero after its
# tests ran, or it dies during a test), Node reports a failed test of its own,
# counted in `fail N`, and names it after the file: U+2716 and the path in the
# spec reporter, `not ok N - <path>` in TAP, the path relative to the directory
# node ran in (absolute on Node 20). A test of the file's own is located
# wherever it is declared, so only the runner's test is located at the file's
# line 1, column 1: `test at <path>:1:1` directly above it in the spec
# reporter's list of failing tests, where it is named a second time, and
# `location: '<path>:1:1'` in its TAP block, the path absolute. Node holds each
# file's lines, its tests' reports and what its process writes, until the files
# before it are reported, takes the files in the order of their paths, and
# reports the runner's test after the rest of the file's lines. It reports no
# such test for a file one of whose own tests failed, so a failed test among
# the lines above one is another file's. The error it gives that test is its
# own `test failed`, written `'test failed'` on the line below the second
# naming in the spec reporter, and an `error: 'test failed'` that a
# `failureType` names in TAP. Under `--test-isolation=none`, a file that throws
# as Node imports it, before it declares a test, gets a test of the same name
# and location whose error is the one the file threw, which no `failureType`
# names: no test in that file ran. So does a file whose process Node could not
# start. Node 22, whose only name for the option is
# `--experimental-test-isolation`, gives that test no location: no `test at`
# line above it in the list, no `location:` in its TAP block. Every test a file
# declares has one, and so does the test of a file whose process failed, so a
# failed test with none, whose error is not Node's own, is that file's. The
# spec reporter writes its whole list at once, below the summary, and prints no
# line below a test whose error is not truthy (a file that threw `undefined`),
# so an entry that ends the output under the list's header is a whole one.
_NODE_FAILED_TEST_RE = re.compile(r"^\s*(?:✖|not ok \d+ -) (.+?)(?: \([\d.]+m?s\))?\s*$")
_NODE_PASSED_TEST_RE = re.compile(r"^\s*ok \d+\b")
_NODE_SPEC_AT_RE = re.compile(r"^\s*test at (.+):1:1\s*$")
_NODE_SPEC_ANY_AT_RE = re.compile(r"^\s*test at .+:\d+:\d+\s*$")
_NODE_SPEC_LIST_RE = re.compile(r"^✖ failing tests:\s*$")
_NODE_TEST_FAILED = "'test failed'"
_NODE_TAP_FAILURE_TYPE_RE = re.compile(r"^\s*failureType: ")
_NODE_TAP_ANY_LOCATION_RE = re.compile(r"^\s*location: ")
_NODE_TAP_TYPE_RE = re.compile(r"^\s*type: 'test'\s*$")
_NODE_TAP_BLOCK_END_RE = re.compile(r"^\s*\.\.\.\s*$")
# TAP quotes the location as JavaScript quotes a string: in `"` when the path
# holds a `'`, in backticks when it holds both, and in `'` with each `'` written
# as `\'` when it holds all three.
_NODE_TAP_LOCATION_RE = re.compile(r"^\s*location: (['\"`])(.+):1:1\1\s*$")
# A test Node reports passed or skipped as it ends: U+2714 or U+FE63 and the
# test's duration in the spec reporter, `ok N -` in TAP. A test's own output can
# print a pass mark, as a CLI's checklist does, but not the duration, and TAP
# prints that output behind `#`. A process that dies during a test reports
# neither that test nor, unless they ended well before it, the file's other
# tests.
_NODE_PASSED_REPORT_RE = re.compile(r"^\s*(?:(?:✔|﹣) (.+?) \([\d.]+m?s\)|ok \d+ - (.+?))(?: # .*)?\s*$")
# The TAP reporter writes a backslash in a name, a file's included, as two, and
# `#` as `\#`, so that a `#` it leaves alone opens a directive (`# SKIP`). A
# tab, a line break or another control character it writes as a backslash and
# a letter, and then doubles that backslash too. The location it gives a file
# test keeps its `#`.
_TAP_ESCAPED_RE = re.compile(r"\\([\\#])")
_TAP_CONTROL = str.maketrans({"\b": "\\b", "\t": "\\t", "\n": "\\n", "\v": "\\v", "\f": "\\f", "\r": "\\r"})
# A test file that cannot load (a syntax error, a module it cannot find, a
# throw or a failed assert at its top level) dies of an uncaught error, which
# Node prints ending with a line that names its own version (behind `#` in
# TAP). One whose top-level await never settles, in the file or in a module it
# imports, exits with code 13 and prints a warning in its place, then the line
# that awaits and a caret under it. Either is the last thing the file's process
# prints, directly above the runner's test (and its `# Subtest:` line in TAP).
# A test whose child process dies of an uncaught error prints that error too,
# among its file's lines, and a process that exits or crashes during a test
# prints neither.
_NODE_LOAD_ERROR_RE = re.compile(r"^\s*(?:#\s*)?Node\.js v\d+\.\d+\.\d+\s*$")
_NODE_UNSETTLED_AWAIT_RE = re.compile(r"^\s*(?:#\s*)?Warning: Detected unsettled top-level await at \S")
_NODE_CARET_RE = re.compile(r"^\s*(?:#\s*)?\^\s*$")
_NODE_SUBTEST_RE = re.compile(r"^\s*# Subtest: ")
# Node's report, as a line of its own (behind U+2139 in the spec reporter, `#`
# in TAP), that a test, a test hook or a resource no test owns did something
# after the test ended that threw, such as a timer or a rejection: `Error: Test
# "<name>" at <path>:<line>:<column> generated asynchronous activity after the
# test ended. This activity created the error "<error>" and would have caused
# the test to fail, but instead triggered an uncaughtException event.` Node
# lists that test as passed, and the error only sets the process's exit code,
# so the file's process fails with no test failed in it, whatever test the
# line names. It names a test, so it is no line that reports its failure.
_NODE_ASYNC_AFTER_END_RE = re.compile(
    r"^\s*(?:ℹ|#)\s*Error: .*\bgenerated asynchronous activity after the test ended\. "
    r"This activity created the error "
)
# Node's test runner that fails as it starts, before any test, as it does when
# the module `--test-global-setup` names throws, rethrows the error from its
# harness and dies of it: it prints the uncaught error, headed by the harness's
# line that threw (`node:internal/test_runner/harness:124`, `throw err;` and a
# caret under it) and ending with the line that names Node's version, and no
# test and no summary. It rethrows a reporter's error the same way, and a run
# whose reporter died prints no summary either, so no failure of it is read.
_NODE_HARNESS_THREW_RE = re.compile(r"^\s*node:internal/test_runner/harness:\d+\s*$")
# A test file Node interrupted, as a `timeout` around the command makes it:
# listed under `Interrupted while running:` as `⚠ <path> (<path>:1:1)`, and
# counted under `cancelled`, not in `fail N`, though its runner's test is also
# reported failed. Its path can hold ` (` itself.
_NODE_INTERRUPTED_RE = re.compile(r"^\s*⚠ (.+):1:1\)\s*$")
# A line that opens with the report of a failed test, in the shape a common
# runner gives it: Node's U+2716, jest's U+2715 and U+25CF, vitest's U+00D7,
# the crosses other runners print, TAP's `not ok` and mocha's `1) <name>`.
_FAILED_TEST_LINE_RE = re.compile(r"^\s*(?:✖|✕|×|✗|✘|●|not ok\b|\d+\) \S)")

# Failure-count shapes across the other common runners (mocha, cargo, and any
# runner whose summary is not one of the above). First match wins; no match
# means the count is unparseable and the kill is reported without the
# exactly-one claim. `[ \t]` keeps a digit that ends one line from pairing
# with a FAILED that opens the next. None is read inside pytest's report.
_FAIL_COUNT_RES = (
    re.compile(r"(\d+)[ \t]+failed", re.IGNORECASE),
    re.compile(r"failures[:=][ \t]*(\d+)", re.IGNORECASE),
    re.compile(r"(\d+)[ \t]+failing", re.IGNORECASE),
)


def _load_table(path: Path) -> list[dict]:
    try:
        raw = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise _refuse(f"table {path} unreadable or not JSON: {exc}")
    if not isinstance(raw, list) or not raw:
        raise _refuse(f"table {path} must be a non-empty JSON array of rows")
    for index, row in enumerate(raw):
        if not isinstance(row, dict):
            raise _refuse(f"row {index} is not an object")
        for key in REQUIRED_KEYS:
            if not isinstance(row.get(key), str):
                raise _refuse(f"row {index} is missing required string key {key!r}")
            # An empty replacement is a deletion of the anchor, and the anchor
            # is never blank, so the mutation always changes the file; a blank
            # replacement is an ordinary mutation. Any other key left empty or
            # only whitespace would run a row that proves nothing: a blank file
            # names no source, a blank anchor occurs everywhere or mutates
            # whitespace rather than code, a blank command exits 0 and reports
            # a false GREEN survivor, and a blank expect_red names no test (one
            # space reads KILLED, since attribution is a substring match that
            # any failure line holding a space satisfies).
            if not row[key].strip() and key != "replacement":
                raise _refuse(
                    f"row {index} has an empty or blank {key!r} - only 'replacement' "
                    "may be empty, which deletes the anchor"
                )
        if row["anchor"] == row["replacement"]:
            raise _refuse(
                f"row {index} anchor and replacement are identical - "
                "that mutation mutates nothing"
            )
    return raw


_NS = 1_000_000_000


def _write_later(path: Path, data: bytes) -> None:
    """Write data, leaving the file's mtime in a later whole second than before.

    CPython (and pytest's assertion rewriting) reuses cached bytecode whose
    recorded source mtime, in whole seconds, and size match the file, so two
    same-size versions of one module written within one second run each
    other's bytecode. The mtime only ever moves forward, never back to the
    original's: tools that rebuild what is newer than its output (make,
    cargo) would keep a build of the mutation otherwise.
    """
    try:
        before = path.stat().st_mtime_ns // _NS
    except OSError:
        # Gone (the command deleted it): the write below recreates it.
        before = None
    path.write_bytes(data)
    try:
        stat = path.stat()
        if before is not None and stat.st_mtime_ns // _NS <= before:
            os.utime(path, ns=(stat.st_atime_ns, (before + 1) * _NS))
    except OSError:
        # The content is written; only the cache protection is lost.
        pass


def _run(command: str, cwd: Path) -> tuple[int, str]:
    proc = subprocess.run(
        command,
        shell=True,
        cwd=cwd,
        capture_output=True,
        # utf-8 + replace, never the strict locale codec: a failing assertion
        # that dumps raw bytes must classify as a red, not crash the run - and
        # on Windows the locale default (cp1252) also mojibakes the very names
        # attribution matches on.
        encoding="utf-8",
        errors="replace",
        check=False,
    )
    stdout, stderr = proc.stdout or "", proc.stderr or ""
    # The two streams' lines are read apart: Node's spec reporter ends its
    # output with no line break, and its last entry is no line of stderr's.
    if stdout and stderr and not stdout.endswith(("\n", "\r")):
        stdout += "\n"
    return proc.returncode, stdout + stderr


def _exists(path: Path) -> bool:
    try:
        return path.exists()
    except (OSError, ValueError):
        return False


def _collected_path(token: str, root: Path | None) -> bool:
    """Whether a short summary entry's path names what pytest collected. A
    path that holds a space counts only when it is there: a line of a message
    that runs over lines can open with `ERROR` and words."""
    if " " in token:
        return root is not None and _exists(root / token)
    if token.endswith(".py") or "/" in token or "\\" in token:
        return True
    return root is not None and _exists(root / token)


def _names_a_class(test_id: str) -> bool:
    """Whether a short summary entry's `::` id ends at a class: its last part
    starts with a capital letter, and it holds no parameters' `[...]`, which
    only a test's id carries and whose text can hold `::` itself
    (`test_x[App::Models::User]`)."""
    if "[" in test_id:
        return False
    last = test_id.rsplit("::", 1)[-1]
    return bool(last) and last[0].isupper()


def _collection_errors(lines: list[str], root: Path | None = None) -> tuple[int, bool, bool, bool]:
    """How many of one pytest run's counted errors were errors collecting a
    module, a directory or a class, whether no test failed (pytest stopped at
    them, or at a conftest.py or a startup plugin it could not load, before
    running any test, or its short summary lists collection errors and no
    test), whether the lines hold pytest's output at all, and whether its
    short summary lists a test that failed or errored."""
    headers = sum(1 for line in lines if _PYTEST_COLLECTING_RE.match(line))
    short = 0
    interrupted = 0
    stopped = False
    seen = headers > 0
    in_summary = False
    tests_listed = False
    for line in lines:
        if _PYTEST_SHORT_HEADER_RE.match(line):
            in_summary = seen = True
            continue
        if _PYTEST_SUMMARY_RE.match(line) or _PYTEST_REPORT_RE.match(line):
            seen = True
        if in_summary and (_PYTEST_SUMMARY_RE.match(line) or _PYTEST_SECTION_END_RE.match(line)):
            in_summary = False
        if in_summary:
            entry = _PYTEST_SHORT_ENTRY_RE.match(line)
            if entry and _collected_path(entry.group(2), root):
                outcome, test_id = entry.group(1), entry.group(3)
                if outcome == "ERROR" and (not test_id or _names_a_class(test_id)):
                    short += 1
                elif test_id:
                    tests_listed = True
        halt = _PYTEST_INTERRUPTED_RE.search(line)
        if halt:
            interrupted += int(halt.group(1))
            stopped = seen = True
        if _PYTEST_CONFTEST_RE.match(line) or _PYTEST_STARTUP_CRASH_RE.match(line):
            stopped = seen = True
    if short and not tests_listed:
        stopped = True
    return max(headers, short, interrupted), stopped, seen, tests_listed


def _same_file(name: str, location: str) -> bool:
    """Whether a test's name and a location's path name one file: equal, or
    one ends with the other after a separator (Node 20 names a file by its
    absolute path, and TAP doubles each backslash in both). TAP names a file
    outside the folder node runs in from that folder (`../shared/a.test.mjs`)
    and locates it by its absolute path, so the name is read without its
    leading `../` and `./` parts against such a location."""
    name, location = (re.sub(r"[\\/]+", "/", path) for path in (name, location))
    inside = re.sub(r"^(?:\.\.?/)+", "", name)
    return (
        name == location
        or name.endswith("/" + location)
        or (bool(inside) and location.endswith("/" + inside))
    )


def _tap_unescaped(name: str) -> str:
    """A name as the TAP reporter wrote it, with its `\\\\` and `\\#` read
    back as the backslash and the `#` they stand for."""
    return _TAP_ESCAPED_RE.sub(r"\1", name)


def _failed_test_name(line: str) -> str | None:
    """The name a line reports a failed test under, read back from TAP's
    escaping, or None when it reports none."""
    failed = _NODE_FAILED_TEST_RE.match(line)
    if failed is None:
        return None
    return failed.group(1) if line.lstrip().startswith("✖") else _tap_unescaped(failed.group(1))


def _reports_a_pass_of(line: str, expect_red: str) -> bool:
    """Whether a line reports, as Node does when a test ends, a passed or
    skipped test whose name holds the row's `expect_red` (a row can leave out
    the `[P0]` tag TEA puts in front of a name). The row can name the test as
    the spec reporter prints it or as TAP writes it, since a TAP kill is read
    by the second form, and either reporter can run a row written against the
    other, so the name is read both as the line prints it and with TAP's
    escapes read back, the row's own included."""
    passed = _NODE_PASSED_REPORT_RE.match(line)
    if passed is None:
        return False
    if passed.group(1) is not None:
        printed = passed.group(1)
        read_back = printed.translate(_TAP_CONTROL)
    else:
        printed = passed.group(2)
        read_back = _tap_unescaped(printed)
    return (
        expect_red in printed
        or expect_red.translate(_TAP_CONTROL) in read_back
        or _tap_unescaped(expect_red) in read_back
    )


def _interrupted_file(listed: str) -> str | None:
    """The file a `⚠ <path> (<path>:1:1)` line names, given the line up to its
    `:1:1)`. The path is split from its location at the ` (` where both name
    one file, since either can hold ` (` itself."""
    at = listed.find(" (")
    while at != -1:
        if _same_file(listed[:at], listed[at + 2 :]):
            return listed[:at]
        at = listed.find(" (", at + 1)
    return None


def _ends_in_a_load_error(own: list[str]) -> bool:
    """Whether a file's own lines end, directly above its runner's test, in what
    Node prints for a file that cannot load: an uncaught error's last line, which
    names Node's version, or the warning that a top-level await never settled,
    then the line that awaits and a caret under it."""
    tail = [line for line in own if line.strip()][-4:]
    if tail and _NODE_SUBTEST_RE.match(tail[-1]):
        tail.pop()
    if not tail:
        return False
    if _NODE_LOAD_ERROR_RE.match(tail[-1]) or _NODE_UNSETTLED_AWAIT_RE.match(tail[-1]):
        return True
    return len(tail) >= 3 and bool(_NODE_CARET_RE.match(tail[-1]) and _NODE_UNSETTLED_AWAIT_RE.match(tail[-3]))


def _tap_block(lines: list[str], start: int) -> list[str] | None:
    """The lines of the YAML block TAP writes, indented, below a file's test,
    up to the `...` that ends it, or None when a line that is not indented
    comes first, or the output ends, so the block was cut short."""
    block: list[str] = []
    for line in lines[start + 1 :]:
        if _NODE_TAP_BLOCK_END_RE.match(line):
            return block
        if line and not line[0].isspace():
            return None
        block.append(line)
    return None


def _node_file_tests(lines: list[str]) -> dict[int, bool]:
    """The line on which a run reports each runner's test for a file whose
    process failed, as the run goes on: the TAP line whose block locates it at
    the file's line 1, column 1, or, in the spec reporter, the latest line
    above the list of failing tests that reads as that list's entry does (the
    same name and duration), since the list names it again below its location.
    Each is found on its own, so two runs that each fail a file of one name
    (two workspaces' `test/index.test.mjs`) give two. Each maps to whether
    its error is other than Node's own `test failed`: the error a file threw
    as Node imported it in its own process (`--test-isolation=none`), before
    it declared a test, or one that kept Node from starting the file's
    process, so that no test in the file ran. Node 22 gives the test of a
    file that threw so no location, so a failed test at the top level with
    none whose error is not Node's own is found too: in TAP, one whose
    block, of the shape Node writes (`type: 'test'`), holds neither a
    `location` nor a `failureType`, and in the spec reporter, an entry of the
    list with no `test at` line above it and an error other than Node's
    below it, read as the latest line above the list that reads as it does."""
    found: dict[int, bool] = {}
    reported: list[int] = []
    spec_at = None
    any_at = in_list = False
    tap_failed = None
    for index, line in enumerate(lines):
        header = bool(_NODE_SPEC_LIST_RE.match(line))
        name = None if header else _failed_test_name(line)
        if name is not None and line.lstrip().startswith("✖"):
            if spec_at is not None and _same_file(name, spec_at):
                same = [at for at in reported if _failed_test_name(lines[at]) == name]
                exact = [at for at in same if lines[at].strip() == line.strip()]
                if exact or same:
                    claimed = (exact or same)[-1]
                    found[claimed] = _spec_error(lines, index, in_list) != _NODE_TEST_FAILED
                    reported.remove(claimed)
            elif (
                in_list
                and not any_at
                and not line[0].isspace()
                and _spec_error(lines, index, in_list) != _NODE_TEST_FAILED
                and any(lines[at].rstrip() == line.rstrip() for at in reported)
            ):
                claimed = [at for at in reported if lines[at].rstrip() == line.rstrip()][-1]
                found[claimed] = True
                reported.remove(claimed)
            else:
                reported.append(index)
            tap_failed = None
        elif name is not None:
            tap_failed = (index, name)
            # Node 22's test of a file that threw in the runner's own process.
            block = None if line[0].isspace() else _tap_block(lines, index)
            if (
                block is not None
                and any(_NODE_TAP_TYPE_RE.match(each) for each in block)
                and not any(_NODE_TAP_ANY_LOCATION_RE.match(each) for each in block)
                and not any(_NODE_TAP_FAILURE_TYPE_RE.match(each) for each in block)
            ):
                found[index] = True
        elif _NODE_PASSED_TEST_RE.match(line):
            tap_failed = None
        # The list of failing tests runs from its header to the first line at
        # the top level that is neither an entry, a location nor a blank line.
        if header:
            in_list = True
        elif in_list and line[:1].strip() and name is None and not _NODE_SPEC_ANY_AT_RE.match(line):
            in_list = False
        location = _NODE_TAP_LOCATION_RE.match(line)
        if location:
            quote, path = location.groups()
            if tap_failed is not None and _same_file(tap_failed[1], path.replace("\\" + quote, quote)):
                # A block cut short says nothing of its error: read as Node's own.
                block = _tap_block(lines, tap_failed[0])
                found[tap_failed[0]] = block is not None and not any(
                    _NODE_TAP_FAILURE_TYPE_RE.match(each) for each in block
                )
            tap_failed = None
        # The spec reporter's location line sits directly above its test.
        at = _NODE_SPEC_AT_RE.match(line)
        spec_at = at.group(1) if at else None
        any_at = bool(_NODE_SPEC_ANY_AT_RE.match(line))
    return dict(sorted(found.items()))


def _spec_error(lines: list[str], index: int, in_list: bool) -> str:
    """The error the spec reporter's list of failing tests gives the entry on
    `index`, on the line below it. Node writes that list whole, so an entry
    that ends the output under the list's header has none (a test whose error
    is not truthy, as of a file that threw `undefined`); one that ends output
    with no such header was cut short, and reads as Node's own `test failed`."""
    if index + 1 < len(lines):
        return lines[index + 1].strip()
    return "" if in_list else _NODE_TEST_FAILED


def _node_file_failures(lines: list[str], expect_red: str | None = None) -> int:
    """How many of the failed tests Node's `fail N` counts are the runner's own
    and no test's failure, in the lines one task printed (all of them, when no
    task runner put its prefix on them). The runner's test for a file whose
    process failed is named after the file and located at its line 1, column
    1, and it is read only from the lines Node printed after the previous such
    test or run summary: that file's own, and those of any passing file listed
    before it. It is no test's failure when its error is not Node's own `test
    failed` (the file threw as Node imported it in its own process, or its
    process never started), or when those lines end in what Node prints for a
    file that cannot load, report a test whose name holds the row's, passed or
    skipped (that test ran to its end, so the process failed outside it, as
    one that exits non-zero after its tests pass does), or report that a test
    generated asynchronous activity after it ended, whatever test they name
    (Node lists that test passed, and the error only fails the process).
    Otherwise a process died during a test, before Node reported the row's
    test, and its runner's test is that test's failure. Node prints a process
    that exits non-zero after all its file's tests pass, the row's not among
    them, just so, and nothing tells the two apart. A file Node interrupted is
    counted as cancelled, not in `fail N`, so it is never taken off."""
    file_tests = _node_file_tests(lines)
    interrupted: list[str] = []
    taken_off = 0
    start = 0
    for index, line in enumerate(lines):
        if _NODE_FAIL_SUMMARY_RE.match(line):
            start = index + 1
            continue
        stopped = _NODE_INTERRUPTED_RE.match(line)
        path = _interrupted_file(stopped.group(1)) if stopped else None
        if path is not None:
            # Listed under `Interrupted while running:` above the file's test.
            interrupted.append(path)
        if index not in file_tests:
            continue
        name = _failed_test_name(line)
        own, start = lines[start:index], index + 1
        if name in interrupted:
            interrupted.remove(name)
            continue
        if (
            file_tests[index]
            or _ends_in_a_load_error(own)
            or any(_NODE_ASYNC_AFTER_END_RE.match(each) for each in own)
            or (expect_red is not None and any(_reports_a_pass_of(test, expect_red) for test in own))
        ):
            taken_off += 1
    return taken_off


def _fail_count(
    lines: list[str],
    root: Path | None = None,
    expect_red: str | None = None,
    tasks: list[list[str]] | None = None,
) -> int | None:
    """The output's failure count, or None when it holds none. `tasks` holds
    the same lines grouped by the task runner's prefix each carried, in which
    Node's runner's tests are read; without it they are read in `lines`."""
    summed: int | None = None
    others: list[str] = []
    tests_read = False
    # Inside pytest's report, from its first section rule to its stats line,
    # every line is a test's traceback, message or captured output, which can
    # quote any count, so none is read for another runner's count.
    in_report = False
    # Taken off Node's summaries, once in all.
    node_files = sum(_node_file_failures(task, expect_red) for task in (tasks if tasks is not None else [lines]))
    # The current pytest run's lines. Its collection errors are taken off its
    # own stats line only: a command that runs pytest twice, with flags that
    # print different signs of them, does not pool the two runs' counts.
    run: list[str] = []
    run_reported = False
    unsummarised: list[tuple[bool, bool]] = []

    def close_run() -> None:
        _, stopped, seen, listed = _collection_errors(run, root)
        if seen:
            unsummarised.append((stopped, listed))

    for line in lines:
        session = _PYTEST_SESSION_RE.match(line)
        if session or (run_reported and (_PYTEST_REPORT_RE.match(line) or _PYTEST_PROGRESS_RE.match(line))):
            # A run that printed no stats line (`-qq`) ends where the next opens.
            close_run()
            run, run_reported = [], False
            in_report = False
        run.append(line)
        run_reported = run_reported or bool(_PYTEST_SHORT_HEADER_RE.match(line))
        node = _NODE_FAIL_SUMMARY_RE.match(line)
        tests = _TESTS_SUMMARY_RE.match(line)
        pytest_summary = None if tests else _PYTEST_SUMMARY_RE.match(line)
        summary = tests or pytest_summary
        if not pytest_summary and _PYTEST_REPORT_OPEN_RE.match(line):
            in_report = True
        if node:
            count = int(node.group(1))
            uncounted = min(count, node_files)
            node_files -= uncounted
            count -= uncounted
        elif summary:
            failed = _SUMMARY_FAILED_RE.search(summary.group(1))
            count = int(failed.group(1)) if failed else 0
            tests_read = tests_read or bool(tests)
            if pytest_summary:
                in_report = False
                collection = _collection_errors(run, root)[0]
                errors = sum(int(n) for n in _PYTEST_ERRORS_RE.findall(summary.group(1)))
                count += errors - min(errors, collection)
                run, run_reported = [], False
        else:
            if not in_report:
                others.append(line)
            continue
        summed = (summed or 0) + count
    close_run()
    if summed:
        return summed
    # A pytest run that printed no stats line (`-qq` prints none, and a
    # conftest's or a startup plugin's failure none at all) counted none of
    # the tests its short summary lists as failed, so the count is not known,
    # whatever count another runner printed beside it (`0 failed` included).
    if any(listed for _, listed in unsummarised):
        return None
    # No summary counted a failure: another runner in the same command may
    # have printed its count in a shape not listed above. A `Tests` line has
    # counted the tests jest or vitest ran, so the files line beside it counts
    # none of them.
    if tests_read:
        others = [line for line in others if not _FILES_SUMMARY_RE.match(line)]
    for pattern in _FAIL_COUNT_RES:
        for line in others:
            match = pattern.search(line)
            if match:
                return int(match.group(1))
    # Every such run stopped at a collection error, or at a conftest.py or a
    # startup plugin it could not load, before any test ran, or listed only
    # collection errors, and Node's test runner, when its harness threw as it
    # started (a global setup that failed), ran none: no test failed.
    stops = [stopped for stopped, _ in unsummarised]
    if any(_NODE_HARNESS_THREW_RE.match(line) for line in lines):
        stops.append(True)
    if summed is None and stops and all(stops):
        return 0
    # Node's test runner whose own process a module ended, by a
    # `process.exit` under `--test-isolation=none`, printed no file's test and
    # no summary. When it reported a test whose name holds the row's passed or
    # skipped, and no runner reported a failed test, the process ended outside
    # that test, as a test file's that exits after it does: no test went red.
    if (
        summed is None
        and expect_red is not None
        and not unsummarised
        and not any(_FAILED_TEST_LINE_RE.match(line) for line in lines)
        and any(_reports_a_pass_of(line, expect_red) for line in lines)
    ):
        return 0
    return summed


# U+2716 is the failure mark of Node's spec reporter, U+2715 jest's, and
# U+00D7 vitest's (and jest's on Windows); U+2717 and U+2718 are the crosses
# other runners print. U+25CF heads each failed test's block in jest's
# output, the only line that names it under jest's default reporter (several
# test files, no --verbose) and its agent reporter.
_FAIL_TOKEN_RE = re.compile(r"fail|error|not ok|assert|✖|✕|×|✗|✘|●", re.IGNORECASE)

# Lines that name a test without reporting its failure. U+2714 (Node's spec
# reporter), U+2713 (jest, vitest), U+221A (jest on Windows) and TAP's `ok N`
# lead a line for a PASSING test, and U+25B6 (spec) and `# Subtest:` (TAP)
# only open a suite or a test.
_PASS_LINE_RE = re.compile(r"^\s*(?:✔|✓|√|▶|ok\s+\d+\b|#\s*Subtest:)")

# pytest's PASSED lines: `-v` puts the outcome after the test id, with an
# optional progress percentage, xdist's `-v` puts it after the worker and the
# percentage, and `-rA` leads its summary line with it.
_PYTEST_PASSED_RE = re.compile(
    r"^\s*(?:\[gw\d+\]\s*(?:\[\s*\d+%\]\s*)?)?PASSED\s|\sPASSED(?:\s+\[\s*\d+%\])?\s*$"
)

# A bare pytest test id: xdist's `-v` prints one when a test starts, before
# any outcome.
_PYTEST_STARTED_RE = re.compile(r"^\s*\S+\.py::\S+\s*$")

# A source line quoted in a code frame, which jest (`  5 | ...`, `> 5 | ...`)
# and vitest (`  5| ...`) print around each failed assertion: it quotes the
# neighbouring tests' declarations, whatever their outcome.
_CODE_FRAME_RE = re.compile(r"^\s*>?\s*\d+\s*\|")

# A pytest section rule, such as `=== PASSES ===`. The PASSES section, which
# `-rA` prints for each passing test that wrote output, holds only passing
# tests, each under a header that names it.
_PYTEST_SECTION_RE = re.compile(r"^=+ (.+?) =+$")

# A task runner's prefix on each line of a task's output: turbo writes
# `<package>:<task>: ` and pnpm's recursive run `<package dir> <script>: `.
# Removed, a pass mark behind it leads the line again and a summary behind it
# is a whole line again. Both print each task's lines as they come when they
# run several at once (turbo outside CI, pnpm without `--aggregate-output`), so
# one package's lines land among another's, and the prefix tells them apart.
_TASK_PREFIX_RE = re.compile(
    r"^(?:[\w@.-]+(?:/[\w@.-]+)*:[\w.:-]+|[\w@.-]*(?:/[\w@.-]+)+ [\w.:-]+): "
)
# pnpm's package dir is the package's folder relative to the folder pnpm runs
# in, so a package whose folder sits directly in that folder has a prefix with
# no `/` (`guard test: `), and that folder itself is `.` (`. test: `). The
# pattern above wants a `/` in pnpm's, since without one a line such as
# `Uncaught Error: boom` would read as a prefix. pnpm prints `<package dir>
# <script>$ <command>` as each script starts, so a prefix that line announces
# is removed too.
_PNPM_SCRIPT_RE = re.compile(r"^([\w@.-]+(?:/[\w@.-]+)* [\w.:-]+)\$ \S")

# Colour codes a runner emits when FORCE_COLOR is set or it thinks it has a
# terminal. Left in, they sit between a line's start and its mark.
_ANSI_SGR_RE = re.compile(r"\x1b\[[0-9;]*m")


def _output_tasks(output: str) -> tuple[list[str], list[list[str]]]:
    """The output's lines without colour codes or a task runner's prefix, and
    the same lines grouped by the prefix each carried (the lines that carried
    none are one group), each group in the order it was printed."""
    printed = _ANSI_SGR_RE.sub("", output).splitlines()
    announced = {found.group(1) + ": " for found in map(_PNPM_SCRIPT_RE.match, printed) if found}
    lines: list[str] = []
    tasks: dict[str, list[str]] = {}
    for line in printed:
        prefix = _TASK_PREFIX_RE.match(line)
        key = max((each for each in announced if line.startswith(each)), key=len, default="")
        key = key or (prefix.group(0) if prefix else "")
        line = line[len(key) :]
        lines.append(line)
        tasks.setdefault(key, []).append(line)
    return lines, list(tasks.values())


def _named_in_failure_context(lines: list[str], expect_red: str) -> bool:
    """True when the expected case is named on a line that speaks of failure.

    A whole-output substring match is defeated by any verbose reporter that
    echoes PASSING names (`pytest -v` prints every test), which made a wrongly
    attributed kill read as a clean one. So the name only counts on a line
    that also carries a failure token outside the name itself (a test named
    "fails when ..." supplies its own), and never on a line a reporter marks
    passed, a bare test id, a code-frame line, a line of pytest's PASSES
    section, or Node's report that a test it lists as passed generated
    asynchronous activity after it ended, which holds `Error` and `fail` and
    names a test that did not fail. Heuristic, and documented as one: a
    runner whose failure lines carry none of the tokens reads MISATTRIBUTED,
    which fails toward the honest side - a human looks.
    """
    in_passes = False
    for line in lines:
        section = _PYTEST_SECTION_RE.match(line)
        if section:
            in_passes = section.group(1) == "PASSES"
            continue
        if (
            in_passes
            or expect_red not in line
            or _PASS_LINE_RE.match(line)
            or _PYTEST_PASSED_RE.search(line)
            or _PYTEST_STARTED_RE.match(line)
            or _CODE_FRAME_RE.match(line)
            or _NODE_ASYNC_AFTER_END_RE.match(line)
        ):
            continue
        if _FAIL_TOKEN_RE.search(line.replace(expect_red, " ")):
            return True
    return False


# Playwright's report that it could not start a `config.webServer` entry, and
# so ran no test: its port is already used (`<url> is already used, make sure
# that nothing is running on the port/url ...`, which a server an earlier run
# left up causes when reuse is off), its start command exited (`Process from
# config.webServer was not able to start. Exit code: N`, or `... exited
# early.`) or it never answered (`Timed out waiting <N>ms from
# config.webServer.`). It prints no test and no count.
_WEB_SERVER_FAILED_RE = re.compile(r"^\s*Error: .*\bconfig\.webServer\b")


def _classify_red(output: str, expect_red: str, root: Path | None = None) -> tuple[str, str, bool]:
    """(status, detail, is_finding) for a red run. `root` is the directory the
    command ran in, so a bare name in pytest's short summary can be checked."""
    lines, tasks = _output_tasks(output)
    count = _fail_count(lines, root, expect_red, tasks)
    if count == 0:
        # A red exit whose own summary counts zero failures is a collection or
        # harness error wearing a red exit code, not the observer firing. It
        # is read before the name: a collection error never names the test, and
        # read as a missing name it looked like some other test's kill.
        return (
            "MISATTRIBUTED",
            "red, but the output's own count says 0 failed - a collection or "
            "harness error, not the observer",
            True,
        )
    named = _named_in_failure_context(lines, expect_red)
    if not named and count is None and any(_WEB_SERVER_FAILED_RE.match(line) for line in lines):
        # A runner that stopped before any test, because it could not start
        # its web server, counted none and named none: read as a missing name,
        # it looked like some other test's kill.
        return (
            "MISATTRIBUTED",
            "red, but no test ran - the runner could not start its web server, "
            "a harness error, not the observer",
            True,
        )
    if not named:
        return (
            "MISATTRIBUTED",
            f"red, but {expect_red!r} never appears beside a failure token - "
            "whatever failed, it was not the observer this row claims",
            True,
        )
    if count == 1:
        return "KILLED", f"exactly {expect_red!r} went red", False
    if count is None:
        return "KILLED+others", f"{expect_red!r} went red; failure count unparseable", False
    return "KILLED+others", f"{expect_red!r} went red among {count} failures", False


def run_table(table: list[dict], project_root: Path) -> tuple[list[dict], int]:
    """Execute the table; return (ledger rows, exit code)."""
    # Baseline first, each distinct command once, in first-appearance order.
    seen: list[str] = []
    for row in table:
        if row["command"] not in seen:
            seen.append(row["command"])
    for command in seen:
        code, output = _run(command, project_root)
        if code != 0:
            raise _refuse(
                "baseline is not green for command "
                f"{command!r} (exit {code}) - a mutation over a red baseline "
                f"proves nothing. Last lines:\n{output[-2000:]}"
            )

    rows: list[dict] = []
    findings = False
    for index, row in enumerate(table):
        target = project_root / row["file"]
        entry = {
            "index": index,
            "file": row["file"],
            "expect_red": row["expect_red"],
            "note": row.get("note", ""),
            "restore": "n/a",
        }
        try:
            original = target.read_bytes()
        except OSError as exc:
            entry.update(status="STALE", detail=f"file unreadable: {exc}")
            rows.append(entry)
            findings = True
            continue
        try:
            text = original.decode("utf-8")
        except UnicodeDecodeError as exc:
            entry.update(status="UNDECODABLE", detail=f"file is not UTF-8: {exc}")
            rows.append(entry)
            findings = True
            continue
        occurrences = text.count(row["anchor"])
        if occurrences != 1:
            entry.update(
                status="STALE" if occurrences == 0 else "NOT UNIQUE",
                detail=(
                    f"anchor occurs {occurrences} times - "
                    + (
                        "0 is the formatter-reflow signature; re-derive the anchor"
                        if occurrences == 0
                        else "a duplicated anchor mutates a different site than it reports"
                    )
                ),
            )
            rows.append(entry)
            findings = True
            continue

        _write_later(target, text.replace(row["anchor"], row["replacement"], 1).encode("utf-8"))
        try:
            code, output = _run(row["command"], project_root)
        finally:
            # Restore is unconditional and verified, never assumed: an earlier
            # hand-rolled run in the field lost a file to its own cleanup. A
            # restore WRITE that fails is the tree-dirty case and must land in
            # the exit-2 refusal lane, not propagate as a traceback into the
            # findings exit code.
            try:
                _write_later(target, original)
            except OSError as exc:
                raise _refuse(
                    f"restore of {row['file']} FAILED ({exc}) - the tree still "
                    "carries the mutation; fix the tree before trusting "
                    "anything else this run printed"
                ) from exc
        if target.read_bytes() != original:
            raise _refuse(
                f"restore of {row['file']} did not verify byte-identical - "
                "the tree is dirty; fix that before trusting anything else this run printed"
            )
        entry["restore"] = "verified"

        if code == 0:
            entry.update(
                status="GREEN",
                detail="the mutation SURVIVED: nothing in the suite can tell - this is a finding",
            )
            findings = True
        else:
            status, detail, is_finding = _classify_red(output, row["expect_red"], project_root)
            entry.update(status=status, detail=detail)
            findings = findings or is_finding
        rows.append(entry)

    return rows, 1 if findings else 0


_LEDGER_ORDER = {"GREEN": 0, "MISATTRIBUTED": 1, "STALE": 2, "NOT UNIQUE": 2, "UNDECODABLE": 2}


def render_ledger(rows: list[dict]) -> str:
    """The generated markdown ledger, GREEN survivors first."""
    ordered = sorted(rows, key=lambda r: (_LEDGER_ORDER.get(r["status"], 9), r["index"]))
    greens = sum(1 for r in rows if r["status"] == "GREEN")
    killed = sum(1 for r in rows if r["status"].startswith("KILLED"))
    lines = [
        "# Mutation ledger",
        "",
        f"{len(rows)} rows: {greens} GREEN (survived), {killed} killed, "
        f"{len(rows) - greens - killed} not applied.",
        "",
        "| # | status | file | expected red | detail | restore | note |",
        "|---|--------|------|--------------|--------|---------|------|",
    ]
    for r in ordered:
        lines.append(
            f"| {r['index']} | {r['status']} | `{r['file']}` | `{r['expect_red']}` "
            f"| {r['detail']} | {r['restore']} | {r['note']} |"
        )
    lines.append("")
    return "\n".join(lines)


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Run a mutation table against a green baseline; ledger out, greens first."
    )
    parser.add_argument("--table", required=True, help="PATH to the JSON mutation table.")
    parser.add_argument(
        "--project-root",
        default=".",
        help="Directory row file paths resolve against and commands run in (default: cwd).",
    )
    parser.add_argument(
        "--output",
        help="Also write the markdown ledger to this PATH (it always prints to stdout).",
    )
    args = parser.parse_args(argv)

    _install_signal_unwind()
    table = _load_table(Path(args.table))
    project_root = Path(args.project_root).resolve()
    if not project_root.is_dir():
        raise _refuse(f"project root {project_root} is not a directory")

    rows, exit_code = run_table(table, project_root)
    ledger = render_ledger(rows)
    print(ledger)
    if args.output:
        Path(args.output).write_text(ledger, encoding="utf-8")
    return exit_code


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall