gdmutant 0.1.0__tar.gz

gdmutant-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Secrets
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+# Python (engine + gdtoolkit adapter are Python-natural)
+__pycache__/
+*.pyc
+.venv/
+.venv-*/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.mutmut-cache
+# mutmut v3 writes a generated copy of the project + its result DB here while it runs
+mutants/
+mutmut-results.db
+mutmut-run.log
+# poodle (local mutation testing, see docs/decisions/0013) writes its temp copies here; the
+# trailing * also catches ad-hoc manual-testing dirs like .poodle-temp-manual/
+poodle-run.log
+.poodle-temp*/
+# Godot (test fixtures may include a small Godot project)
+.godot/
+# Godot self-test fixture (tests/test_selftest_live.py): the GdUnit4 addon is downloaded
+# (scripts/install_gdunit4.py), and reports + .uid import artifacts are regenerated by
+# `godot --import` — none of them are committed.
+corpus/addons/
+corpus/reports/
+*.uid
+# Live self-test with --basetemp=.live-tmp (CI reuses the Stryker JSON it writes there)
+.live-tmp/
+# OS/editor
+.DS_Store
+Thumbs.db
+.idea/
+*.swp
+
+# Agent scratch output — never commit ad-hoc dumps or agent-local config
+*_dump.txt
+.claude/
+
+# The private word list tests/test_public_readiness.py scans for (GDMUTANT_PRIVATE_TERMS).
+# It belongs outside this tree entirely, and committing it would publish the exact list of words
+# the guard exists to keep unpublished. This is the belt to that guard's braces: a copy dropped
+# in here by accident cannot be staged at all. tests/test_public_readiness.py pins that this
+# pattern is here and that git really does honour it.
+*private-terms*

gdmutant-0.1.0/AGENTS.md

@@ -0,0 +1,147 @@
+---
+type: how-to
+status: active
+created: 2026-07-11
+---
+
+# gdmutant: contributor & AI-assistant guide
+
+A language-agnostic mutation-testing tool for GDScript/Godot. It
+mutates a project's source (flip `>`↔`>=`, `and`↔`or`, bump a number, …), reruns the tests per
+mutant, and reports survivors: lines a bug could live on that no test catches. This is the
+fast-orientation guide for anyone (human or AI) *contributing to* gdmutant's own source. The
+product rationale is in [`README.md`](README.md), and the authoritative design is in
+[`docs/design/DESIGN.md`](docs/design/DESIGN.md). Driving gdmutant as a tool (invoking the CLI,
+not editing its code) is a different job: see
+[`docs/gdmutant-guide.md`](docs/gdmutant-guide.md) instead.
+
+## Setup
+
+gdmutant is a [uv](https://docs.astral.sh/uv/) project. Install uv, then:
+
+```sh
+uv sync --frozen      # fetches the pinned Python (via .python-version) + locked deps into .venv
+```
+
+Run commands with `uv run`.
+
+The live self-test suites below need a real Godot binary, which `uv sync` does not provide (`uv`
+owns only Python here). `mise.toml` pins the same Godot release CI runs against. Install
+[mise](https://mise.jdx.dev/), then `mise install` fetches it. `mise which godot` prints the path
+to pass as `GDMUTANT_GODOT`. Never add Python to `mise.toml`. That stays `uv`'s alone.
+
+## Build · test
+
+```sh
+uv run ruff check .            # lint
+uv run ruff format --check .   # format
+uv run mypy gdmutant           # type check (strict)
+uv run pytest                  # tests + coverage
+uv run pip-audit               # dependency audit
+```
+
+Two suites are env-gated and auto-skip in a plain `uv run pytest` (so `verify` stays
+Godot-free). Run them when touching the adapter, runners, or CLI file-handling:
+
+```sh
+# Live self-test: drive the shipped CLI against a real Godot on the corpus.
+GDMUTANT_GODOT=godot uv run pytest tests/test_selftest_live.py
+# Dogfood harness: run gdmutant against a real GdUnit4 checkout — parse coverage + the
+# whole-directory regression guard (Godot-free, ~5s). Point it at any GdUnit4 clone:
+GDMUTANT_GDUNIT4_CLONE=<path-to-a-gdUnit4-checkout> uv run pytest tests/test_dogfood_gdunit4.py
+```
+
+## Tech stack (decided)
+
+- Language: Python 3.12 (pinned via `.python-version`), managed with uv (hash-pinned
+  `uv.lock`, with uv itself floored in `pyproject.toml`'s `[tool.uv]`). Rationale for Python over GDScript:
+  [`docs/decisions/0001`](docs/decisions/0001-write-the-engine-in-python-not-gdscript.md).
+- Runtime dependency: [`gdtoolkit`](https://github.com/Scony/godot-gdscript-toolkit), the
+  GDScript parser the adapter mutates.
+- Test-runner adapters: GdUnit4 and GUT are peer JUnit-XML adapters over one runner contract
+  (both run via `godot --headless`, and neither is privileged in the engine), plus the framework-neutral
+  exit-code command runner for any harness without JUnit output. See
+  [`docs/decisions/0011`](docs/decisions/0011-runner-agnostic-adapter-seam.md).
+- Report format: the `mutation-testing-elements` JSON schema (renders in its HTML viewer).
+
+## Conventions
+
+- `main` is protected, and new behavior comes with tests: this is a testing tool, so we hold
+  ourselves to it.
+- CI gate: `ruff` + `mypy` + `pytest` + `pip-audit`, plus a gitleaks secret scan and zizmor
+  (workflow security). GitHub Actions are SHA-pinned (Dependabot bumps them).
+- Windows is a deployment target, not just a dev machine. gdmutant is a cross-platform Python
+  CLI people run on Windows, so test on Windows for real, not just Linux. Two concrete traps to
+  watch for: console output can crash under the legacy `cp1252` code page, and `python3` can resolve
+  to a *different* interpreter than `python` (see `.pre-commit-config.yaml`'s header for the guard).
+- `ci.yml` runs automatically on every pull request and push to `main` (restored 2026-08-04, ahead
+  of going public — why it was ever manual-only, and why it's back:
+  [ADR-0012](docs/decisions/0012-merge-time-local-ship-time-cloud.md)). The unbypassable gate is
+  still `publish.yml`'s release-time run of `verify` on both Linux and Windows, before every real
+  release. Run the same checks locally any time:
+
+  ```
+  uv run python scripts/verify_local.py
+  uv run python scripts/verify_local.py --job license-check   # or any other ci.yml job
+  uv run python scripts/verify_local.py --list                # show a job's commands without running them
+  ```
+
+  This script reads its commands out of `ci.yml` rather than restating them, so local, CI, and the
+  release gate can't drift apart.
+
+  If every tool fails with `uv trampoline failed to canonicalize script path`, the venv's
+  launcher shims are stale, usually after a `uv` version bump. Fix: `uv sync --frozen --reinstall`.
+- Keep the engine language-neutral: no GDScript-specific assumptions in `gdmutant/engine/`.
+  Language specifics live only in `gdmutant/adapters/<lang>/`.
+- The mutation-operator core is deterministic, the reproducible mode a CI check can trust. Any
+  future LLM-semantic mode stays out of it.
+- **Recurring bug one: a gate that passes without checking anything.** Seen five times. A test that
+  skipped when `git` was missing. A mutation hook that ran zero mutants. A license check over an
+  empty package list. A script that exited 0 after all its writes failed. A mutation run scored
+  against an already-broken baseline, where every mutant "died" so the 100% meant nothing.
+  This is a list of shapes, not a list of things already fixed. Assume at least one is live in the
+  tree right now, because that has been true every time anyone checked.
+  Ask of any gate: what happens when its input is missing, empty, or unreadable? Silence is the
+  wrong answer. Make it fail, or make it say out loud that it did not run.
+- **Recurring bug two: two paths that should agree, and one checks less.** A second entry point
+  running fewer checks than the first. A message fixed in one place but not its twin. Two things
+  writing to stdout at once. Coverage and mutation testing cannot catch these. Both ask "is this
+  path correct?", and the bug is "do these two paths match?". So when you change one of a pair, say
+  what every member of the pair does now, including the ones already right.
+- Sensitive paths (CI, scripts, toolchain, the mutation-operator catalog, and the GDScript
+  adapter) are listed in `CODEOWNERS` for documentation only. It enforces no review (a sole
+  maintainer can't approve their own PR). `main` requires a pull request and, alongside
+  `Workflow security (zizmor)` (which reads the workflow files and nothing else), the checks
+  `ci.yml`'s now-restored triggers make possible: `Verify` on both platforms, `Secret scan
+  (gitleaks)`, and both `Self-test` gates — see `scripts/harden_github.py`'s `REQUIRED_JOBS` for
+  the exact, current list. `.github/CODEOWNERS` carries the full list of what branch protection
+  enforces. Read changes to these paths carefully before merging. The GDScript adapter is the real
+  technical risk, since a wrong mutant means a silently wrong survivor report.
+
+## Design goals (keep these in mind)
+
+- Ship fast: a working v0.1 that mutates one real module and prints survivors beats a framework.
+- Standalone, no AI required: a normal CLI, usable from the README alone.
+- Generic engine, per-language adapters: build the loop once. A new language = one small adapter.
+
+## Docs: where things live
+
+- [`README.md`](README.md): what it is and why.
+- [`docs/design/DESIGN.md`](docs/design/DESIGN.md): authoritative design (goals, FG/NF requirements, architecture).
+- [`CHANGELOG.md`](CHANGELOG.md): what's landed and in progress (scope / non-goals live in `DESIGN.md`).
+- `docs/mutation-testing.md`: the suite is mutation-tested against itself.
+- `docs/decisions/NNNN-*.md`: append-only ADRs (`ls` is the index).
+- [`docs/releasing.md`](docs/releasing.md): the maintainer runbook for cutting a release to PyPI.
+- [`docs/credits.md`](docs/credits.md): third-party licenses.
+
+Live docs open with YAML frontmatter (`type` / `status` / `created`). Build only from
+`status: active`. Two files are deliberately exempt, because they are rendered somewhere that has
+no frontmatter support and would print it as a visible heading: `README.md` (it is the package's
+PyPI description) and `.github/PULL_REQUEST_TEMPLATE.md` (it is pasted verbatim into every new pull
+request's body). `tests/test_docs_frontmatter.py` pins both halves of that rule.
+
+## Non-goals (v0.1)
+
+Coverage-gated mutant selection, the optional LLM-semantic mutant mode, and any second-language
+adapter (TypeScript is out of scope for v0.1).
+Finishing the GDScript path on a real fixture beats breadth.

gdmutant-0.1.0/CHANGELOG.md

@@ -0,0 +1,251 @@
+---
+type: record
+status: active
+created: 2026-07-18
+---
+
+# Changelog
+
+All notable changes to gdmutant are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-08-04
+
+gdmutant mutates real GDScript and reports survivors end-to-end via the standalone `gdmutant run`
+CLI.
+
+### Added
+
+- AST-based mutation of GDScript via [gdtoolkit](https://github.com/Scony/godot-gdscript-toolkit),
+  with a re-parse validity guard so invalid mutants are never run.
+- Operators: comparison, boolean, arithmetic, constant, numeric-literal, compound assignment,
+  modulo, unary-not, and statement-deletion.
+- Generation-time exclusions for token positions the language itself rules out as meaningful
+  mutants, so they never reach the report as survivors: a `%` used for string formatting, a `+` that
+  is string concatenation (GDScript's `String` defines no `-`), a `+=` that appends to a string (same
+  reason), and a property declaration's initializer whose stored value no getter can read back.
+  These change the mutation score, and upward: an excluded mutant leaves the denominator instead
+  of counting as a survivor. That is deliberate and is the honest direction: the language already
+  settles all four, so none is a gap a test could ever have closed. The first three are invalid
+  GDScript, and the property initializer is valid GDScript whose mutant is inert, because the value
+  it stores can never be read back. It does mean, though, that a score is not comparable across a
+  version that added an exclusion. Each is recognised from the parse tree only
+  where the shape is certain (a `String`-typed *variable* is still mutated), because reporting noise
+  is a smaller failure than hiding a real gap. `docs/survivors/README.md` states the full list and
+  its effect on the score for users.
+- Framework-agnostic test runners over one shared runner contract (a runner-agnostic adapter seam):
+  GdUnit4 and GUT as first-class peer JUnit-XML adapters (`--runner gdunit4` / `--runner gut`,
+  neither privileged in the engine), plus an exit-code runner (`--runner command`) for any headless
+  harness without JUnit output, no addon required. Every runner upholds a crash-safety guarantee: a
+  load/compile crash surfaces as a kill or error, never a silent zero-test pass. A whole-run
+  `tests == 0` check catches the empty-report shape, but GUT needs more: it skips a suite that fails
+  to compile, runs the rest green, and exits 0, so the adapter also treats any run whose test count
+  drops below the healthy baseline's as an error, with a non-determinism canary that warns (never
+  errors) when a later run reports more tests than the baseline.
+- Multi-file and directory targets: mutate several files or a whole directory in one pass with a
+  per-file breakdown and one aggregate mutation score.
+- `--jobs N` runs N mutants in parallel, each on its own copy of the project so in-place mutation
+  can't collide: same verdicts as a serial run (process isolation, the per-mutant timeout is scaled
+  by N so contention can't cause a false timeout), just faster (measured ~3× at `--jobs 4` on a real
+  GdUnit4 module).
+- Test suites are skipped by default on directory targets (by `test/`/`tests/` folder, `test_*.gd` /
+  `*_test.gd` / `*Test.gd` name, or `extends GdUnitTestSuite` / `GutTest`), with an `--exclude` glob
+  (and a `.gdmutant.toml` `exclude` list) to skip anything else.
+- Reports: a console survivor summary that explains each gap (what's untested, why it matters, where
+  to start a test), the
+  [`mutation-testing-elements`](https://github.com/stryker-mutator/mutation-testing-elements) JSON
+  schema (`--json`), and a genuinely self-contained HTML report (`--html`): one file with every
+  style, script and image inlined, so it opens with no network at all and works as a CI artifact or
+  an email attachment. It marks the exact changed characters in your source, groups mutants into
+  findings (one spot, one operator, the unit of work a single test closes), and inlines the
+  per-operator survivor reference so an offline reader can still look up what an operator means. A
+  multi-file run opens on a file index ordered by survivors. Replaces an earlier page that inlined
+  the report JSON but loaded the generic viewer from a CDN, and so rendered blank offline.
+- Every finding in the HTML report has an address: `path:line:column:operator`, the tuple it
+  was grouped by, so it is the same string every time the report is regenerated from source that has
+  not moved. The selected finding lives in the URL, so a reload keeps your place and "look at this
+  survivor" is a link you can send. A link that no longer resolves falls back to the file it named,
+  or to the file index, and never to the wrong finding.
+- The HTML report shows each file by its project-relative path. A report is made to travel, and an
+  absolute path from the machine that produced it carries that machine's username and directory
+  layout into every row while telling a reader nothing they can act on. A file genuinely outside the
+  project keeps its absolute path, because there is no shorter honest name for it. This changes what
+  the page *displays*, and the displayed path is what a deep link is keyed on. Note the limit: the
+  `--json` report and the copy of it embedded in the HTML file are both unchanged, because their
+  keys are identifiers other tooling resolves. A report file still contains the absolute paths, it
+  just no longer shows them.
+- The embedded report is downloadable from the page, so the JSON in a report someone mailed you is
+  reachable without View Source. No request and no new data, the bytes are the page's own. The
+  toolbar button now says `JSON`, not just a bare down-arrow, and the download itself is indented
+  (`json.dumps(..., indent=2)`), matching what `--json <path>` writes to disk instead of one
+  unreadable line.
+- The file index sorts on any column (score, file, survived, caught, mutants), ascending or
+  descending. Most survivors first stays the default, because it is the only order that answers
+  "where do I start". Score would rank 1 survivor in 5 mutants level with 100 in 500.
+- The header's rare-status counts are clickable, and reach the mutants behind them through the
+  filter the file view already has. The three stay three things: a timeout is a kill and only a
+  performance signal, a compile error is the re-parse guard working, and a runtime error is the
+  actionable one, a valid mutant that ran and measured nothing because the harness fell over.
+- The browser's back button returns to the file index instead of leaving the report. Structural
+  moves (opening a file, going back to the index) get a history entry. Stepping between findings
+  still does not, so a long file cannot bury the reader under a back press per finding.
+- `.gdmutant.toml` for persisted per-project flags, and `--dry-run` to list mutants without running
+  Godot.
+- Live self-test against real Godot in CI, pinning both runner paths to exact per-mutant outcomes.
+- A GitHub Action, so a consumer's CI runs gdmutant from a few lines of `uses:` YAML instead of a
+  hand-rolled install step: it sets up Python and Godot, installs gdmutant, runs it against the
+  consumer's project, and writes the surviving mutants (with their explanations) to the job
+  summary, right where a reviewer already looks.
+- `gdmutant example` writes a small bundled GDScript file (`gdmutant-hello-world.gd`) to try
+  `--dry-run` on, so the Quickstart no longer asks a first-time reader to hand-copy a snippet into
+  a file themselves. Refuses to overwrite an existing file of the same name.
+
+### Changed
+
+- `--progress none` now silences the whole progress stream, not just the heartbeat: the plan
+  line, the heartbeat, the per-mutant lines, the closing wall-clock line, and the "preparing the
+  project" / "running the unmutated (baseline) suite" notices are all gone. `auto` and `plain`
+  still print all of it. The console summary, survivor blocks, and the reports themselves are
+  unaffected.
+- `--since <ref>` with no lines changed now writes a valid, empty report instead of leaving
+  stdout empty. The exit code and the stderr explanation are unchanged: still 0, still the same
+  "nothing to mutate" note, still no tests run and no Godot booted. New: the `--json` or `--html`
+  report is written (every given file listed, an empty `mutants` list, no score key), the job
+  summary is emitted if `--report step-summary` was asked for, `--project` and the report targets
+  are validated the same as on a real run, and a malformed `# gdmutant: ignore[...]` pragma warns.
+- The HTML report now opens in dark mode by default. The toggle to switch to light is unchanged.
+- The count badge on a mark with multiple findings sits further outside the mark's border, so it
+  no longer covers part of the character underneath.
+
+### Fixed
+
+- Six survivor explanations stated something that is not true. The text reaches every user on every
+  run, through the console block, the JSON report and the HTML report, and the docs page and the
+  shipped copy of it were pinned to each other, so all three said the same wrong thing in sync.
+  - Modulo blamed a clean multiple ("where `%`, `*`, and `/` can produce indistinguishable
+    results"). A clean multiple is where those three differ most: `6 % 3` is 0, `6 * 3` is 18,
+    `6 / 3` is 2. A reader was told the test that works cannot work. The reason is arithmetic's,
+    which is what the entry's own "assert the exact result" advice already implied: nothing pins
+    the result.
+  - Comparison said the swapped operators "differ on exactly one input", which is false for the
+    `==` ↔ `!=` pair the operator also produces, and which the entry names in its own example.
+    Those two are complements and differ on every input.
+  - The list of shapes that are never generated called all four "code GDScript rejects". Three
+    are, resting on `String` having no `-`. The fourth, a property initializer no getter can read
+    back, is valid GDScript that is merely inert, so an auditor was sent hunting a syntax error
+    that is not there.
+  - Numeric said "a numeric literal", but only bare decimal integers are mutated: `0.5`, `0xFF`
+    and `1_000` produce nothing, so a float bound was never covered.
+  - Enum member described only a `numeric` mutant on a member's value, though any mutant inside
+    an `enum` block is explained there, including an arithmetic one on `A = 1 + 0`.
+  - Compound assign said a string `+=` is "not mutated at all". It gets no compound-assign
+    mutant, but the line still gets a statement deletion.
+- `# gdmutant: ignore[statement-deletion]` no longer draws a warning that it "suppresses nothing".
+  The annotation always worked. The validator checked names against the token operator catalog
+  alone, and statement deletion is structural, so it lives in the GDScript adapter instead. The
+  tool was contradicting its own documented advice to scope an ignore with the `mutatorName` from
+  the report.
+- The "executable not found" message is mode-aware. Under `--runner command` the executable
+  comes from the `--command` string, not from `--godot`, so the message now says that, states that
+  `--godot` has no effect in that mode, and shows the user's own command back with the path slot
+  marked. It previously recommended `--godot`, which that mode does not read: setting it returned
+  the byte-identical error.
+- `--runner command` says up front when the project has no Godot import cache (`.godot/`). On a
+  fresh checkout Godot imports every asset before it will run anything, minutes of silence that
+  reads as a hang. The JUnit runners do that warm-up themselves (and the "preparing the project"
+  notice now says it can take minutes). The exit-code runner cannot, so it names the one command
+  that fixes it instead.
+- Survivors that are unkillable by where they sit explain themselves, instead of handing out
+  advice nobody can follow. Two places qualify:
+  - inside an `assert`: a failed assert aborts the Godot process, so no in-process test can
+    pass on the original and fail on the mutant. On defensive code these can be most of a file's
+    survivors.
+  - on an `enum` member's value: code that names the member moves with it, so nothing observes
+    the number. The generic numeric advice ("add a test at the boundary this number sets") is
+    meaningless for a tag that has no boundary.
+
+  Nothing is skipped and no score changes. Every one of these mutants is still generated, still
+  run, and still counted. Enum values are deliberately *not* suppressed: bitflag enums and any enum
+  that is serialised have values that really are read as numbers, and gdmutant reads one file at a
+  time, so it cannot see a numeric use in another file, a save format, or engine code. Suppressing
+  them would hide exactly the bugs that matter most. The reference explains what would make one
+  killable and leaves the call to you.
+
+  Every surface agrees: the console block, the JSON report, the HTML page and the job summary all
+  resolve their explanation and their link through one rule, so the page can never offer an
+  operator's reference beside a contradicting explanation. The `statement-deletion` reference also
+  now names the redundant initializer (`_cells = PackedByteArray()` where the declaration
+  already default-initialises it) as its commonest legitimate equivalent, with the check that
+  confirms one.
+- Progress is measured, not predicted. The up-front `estimated ≈ 24s` figure is gone. It was
+  wrong in both directions at once: 1.7–3.4× *under* on a real project (it counted neither
+  gdmutant's own per-mutant work nor timeouts, which were four minutes of one 6m24s run) and, since
+  it never took `--jobs` into account, roughly N× *over* under `--jobs N`. In its place, three
+  lines that `--progress {auto,plain,none}` controls together (`none` silences all three, `auto`
+  and `plain` print all three):
+  - before, the facts: `18 mutants to run. Baseline suite 1.4s; each mutant is capped at 30s.`
+    The cap is the part that paces the wait, and it says how long silence is normal.
+  - during, a heartbeat: `… 7/18 done in 1m 12s — 2 survived, 1 timed out.` Every 30s on a
+    terminal, every 60s or 10% of mutants (whichever is rarer) in a log or under `CI=true`, and
+    always once at the end of each file.
+  - after, the wall-clock every other test runner prints and gdmutant did not:
+    `Done in 6m 32s — 18 mutants, 8 timed out (4m 0s of that). Baseline suite 1.4s.` The timeout
+    cost is broken out because it is the cost nobody can see.
+
+  No finish time is forecast anywhere. One was built and measured against a real Godot project
+  first: on an even workload it tracked the true finish to within 5%, but on the shape that
+  actually matters (hanging mutants arriving after the rate has settled), it read 3.2s at 25%
+  done for a run that took 58.0s, so it was dropped.
+- `--json -` combined with `--html` no longer writes the `Wrote HTML report to ...`
+  confirmation into the JSON stream. It goes to stderr instead, so stdout stays valid JSON.
+- `--json -` combined with `--report step-summary` and no `$GITHUB_STEP_SUMMARY` set is now
+  refused up front with exit 2, naming both flags and how to fix it, instead of printing the
+  report to stdout and poisoning the JSON.
+- `--report-path` (or a cloned project's own `.gdmutant.toml`) could resolve outside `--project`
+  via an absolute override or `../` traversal. Every run deletes whatever sits at that path first,
+  so this was a delete-anything-on-disk primitive reachable with no flags at all. Now refused
+  unless the resolved path stays inside the project.
+- `.gdmutant.toml`'s `project` key now requires `--trust-config`, alongside the existing
+  `command`/`godot` gate: it roots every subprocess's cwd and, under `--jobs`, what gets copied
+  once per worker, the same "this file decides what happens on your machine" shape those two keys
+  already guarded against.
+- The HTML report's script-embedding escape only rewrote `</`, missing `<!--<script` (needs no
+  slash) which could push a browser's HTML parser into a state that swallows the report's own
+  closing tag, blanking the page past that point. Every `<` is escaped now.
+
+### Safety
+
+- Mutations are applied in place and restored after each mutant and on exit. gdmutant warns on
+  uncommitted changes, and `--require-clean` makes that a hard stop.
+- `--require-clean` refuses anything it could not confirm, not just changes it could see. A file
+  git ignores, a file outside any repository, a machine with no git, and a symlink whose target
+  is unbacked all used to pass the check silently (the ignored file and the symlink being the
+  worst of them, since git holds no copy of either). Without the flag, a file gdmutant cannot
+  judge still says nothing. A gitignored one now warns, which it did not before, because that is
+  the case gdmutant can positively tell has no copy anywhere.
+- A git command that fails for a reason other than "no repository here" (dubious ownership, a
+  corrupted repository) now reports what git actually said, including the fix it suggests,
+  instead of a generic "not inside a git working tree". When the source is a symlink, the message
+  names the file git was actually asked about, so a report about a target outside every repository
+  does not read as a report about the link.
+- A source file is never left half-written. Each rewrite is staged in a temporary file beside the
+  target and renamed over it, so the path always holds one whole version or the other, never
+  something truncated or cut off mid-token. If that cannot be done (no room for the temporary
+  file, a failed flush, a lock that will not clear, or a file marked read-only), gdmutant stops
+  and says so instead of attempting a write that could truncate the file. That promise is about
+  the write, not the run: the same write happens twice per mutant, once to apply it and once to
+  restore the original, and a failure on the restore leaves the mutant on disk, not your
+  original. Every message names which of the two is actually there and points at git to recover
+  it.
+- Under `--jobs N`, a worker only ever writes inside its own copy of the project. A source file
+  that is not under `--project` has no copy to mutate, so the run is refused with an explanation
+  instead of writing outside the copy, which used to report every mutant as a survivor because
+  the mutation never reached the project the tests ran against.
+- `.gdmutant.toml` cannot decide what gdmutant executes. Its `command` and `godot` keys name a
+  program to run, and the file is read from the project directory, so in a project you cloned,
+  somebody else wrote it. Either key makes gdmutant refuse the whole run, with an explanation, and
+  exit 2 without running anything, unless you add `--trust-config` or name the program on the
+  command line yourself, which always wins over the file. The refusal fires only where the file
+  would change what happens, so a key repeating a value you already passed, or the one gdmutant
+  would have used anyway, goes through in silence.

gdmutant-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,166 @@
+---
+type: how-to
+status: active
+created: 2026-07-31
+---
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and
+contributions of all individuals, regardless of characteristics including race, ethnicity, caste,
+color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or
+expression, sexual orientation, language, philosophy or religion, national or social origin,
+socio-economic position, level of education, or other status. The same privileges of participation
+are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations
+for positive behavior. We also understand that our words and actions may be interpreted differently
+than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways
+that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of
+these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal
+   attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a
+   community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone's personality or behavior on the basis
+   of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate
+   in the context or purpose of the community.
+5. **Violating confidentiality.** Sharing or acting on someone's personal or private information
+   without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person
+   or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone
+   else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials.** Sharing marketing or other commercial content in a way that is outside
+   the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or
+   describes any other restricted behaviors.
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate.
+Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces
+encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation,
+open a private report with
+**[GitHub's "Report a vulnerability" form](https://github.com/kphutt/gdmutant/security/advisories/new)**
+(repository → **Security** → **Advisories** → **Report a vulnerability**). That form is the same
+private channel
+[`SECURITY.md`](https://github.com/kphutt/gdmutant/blob/main/.github/SECURITY.md) names, and it is
+the project's only private
+inbox. It carries conduct reports as well as security ones, and a report sent there is visible only
+to the maintainers. Please do not open a public issue for a conduct problem.
+
+Where this Code of Conduct says **Community Moderators**, read *the maintainers of this project*.
+gdmutant is maintained by one person, so a report about that person's own conduct has nowhere
+neutral to go inside the project. Send those to
+[GitHub's abuse reporting](https://github.com/contact/report-abuse) instead, which is handled by
+GitHub rather than by anyone here.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a
+timely manner. They will investigate all reports of code of conduct violations, reviewing messages,
+logs, and recordings, or interviewing witnesses and other participants. Community Moderators will
+keep investigation and enforcement actions as transparent as possible while prioritizing safety and
+confidentiality. In order to honor these values, enforcement actions are carried out in private with
+the involved parties, but communicating to the whole community may be part of a mutually agreed upon
+resolution.
+
+## Addressing and Repairing Harm
+
+This project has no enforcement process of its own, so it uses the Contributor Covenant's suggested
+ladder as written, below.
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated,
+the following enforcement ladder may be used to determine how best to repair harm, based on the
+incident's impact on the individuals involved and the community as a whole. Depending on the
+severity of a violation, lower rungs on the ladder may be skipped.
+
+1. Warning
+   1. Event: A violation involving a single incident or series of incidents.
+   2. Consequence: A private, written warning from the Community Moderators.
+   3. Repair: Examples of repair include a private written apology, acknowledgement of
+      responsibility, and seeking clarification on expectations.
+2. Temporarily Limited Activities
+   1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first
+      incidence of a more serious violation.
+   2. Consequence: A private, written warning with a time-limited cooldown period designed to
+      underscore the seriousness of the situation and give the community members involved time to
+      process the incident. The cooldown period may be limited to particular communication channels
+      or interactions with particular community members.
+   3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect
+      on actions and impact, and being thoughtful about re-entering community spaces after the
+      period is over.
+3. Temporary Suspension
+   1. Event: A pattern of repeated violation which the Community Moderators have tried to address
+      with warnings, or a single serious violation.
+   2. Consequence: A private written warning with conditions for return from suspension. In general,
+      temporary suspensions give the person being suspended time to reflect upon their behavior and
+      possible corrective actions.
+   3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the
+      specified conditions for return, and being thoughtful about how to reintegrate with the
+      community when the suspension is lifted.
+4. Permanent Ban
+   1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have
+      failed to resolve, or a violation so serious that the Community Moderators determine there is
+      no way to keep the community safe with this person as a member.
+   2. Consequence: Access to all community spaces, tools, and communication channels is removed. In
+      general, permanent bans should be rarely used, should have strong reasoning behind them, and
+      should only be resorted to if working through other remedies has failed to change the
+      behavior.
+   3. Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community
+Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is
+officially representing the community in public or other spaces. Examples of representing our
+community include using an official email address, posting via an official social media account, or
+acting as an appointed representative at an online or offline event.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at
+[https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under
+CC BY-SA 4.0. To view a copy of this license, visit
+[https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at
+[https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations
+are provided at
+[https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
+Additional enforcement and community guideline resources can be found at
+[https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The
+enforcement ladder was inspired by the work of
+[Mozilla's code of conduct team](https://github.com/mozilla/inclusion).