be0ea187

Make a mutation-disable annotation that disables nothing an error

A mutation-disable annotation that disables nothing is now a compile error.

Only one such mistake was caught before: a `DisableMutationsFor <name>` whose
target names no local binding. Every other way for a disable to be inert was
silent, so an annotation could keep claiming to suppress a mutation long after
the code stopped producing one.

## The rule

Removing the annotation would not change the manifest.

It is decided by measuring rather than by asking each operator whether it
matches: the annotated scope is walked a second time with only that
annotation's disables lifted, and the operators that fire in that walk are
exactly the ones it suppresses. That is what keeps the answer from drifting
away from the manifest, because the `ignore` list, per-operator
`skip-calls-to` keys, splice filtering and the dropping of mutants that do not
desugar all happen inside the walk, and each of them can be the reason an
operator produces nothing.

Everything except the annotation being judged stays in force while measuring:
the configuration's disables, an enclosing annotation's, and the binding's own
per-target entries. So an annotation that only repeats a disable already in
effect is inert too, and reported.

## What is now an error

* `DisableMutation: <Operator>` on a binding that operator does not mutate.
* `DisableMutations` on a binding nothing would mutate.
* `DisableMutationsFor <name>[: <Operator>]` where the target exists but is
  not mutated by what the annotation disables. (The target-does-not-exist case
  was already an error and still is.)
* A module-level `{-# ANN module ("DisableMutations" ...) #-}` on a module
  nothing would mutate, and a module-level `DisableMutation: <Operator>` the
  module does not produce.
* An annotation naming something that is not a mutation operator, reported as
  such with the operator names rather than as a disable that fires nowhere.
* A string that announces itself as a mutation disable but parses as none of
  the recognised forms -- a keyword typo that keeps the `DisableMutation`
  prefix, a missing colon, an empty operator list, and
  `DisableMutationFor <name>` with no operator after it, which was accepted as
  a no-op until now.

A string that does not begin with `DisableMutation` is still left alone:
`{-# ANN #-}` payloads are a shared mechanism and dekking's coverage marks
functions with `"nocover"` through the same one. A typo bad enough to lose
that prefix is indistinguishable from an annotation meant for something else,
so it stays unrelated -- there is a test resource module pinning that.

## How to tell it works

* `stack test sydtest-mutation-plugin --pedantic` -- 80 tests.
  `deadDisables`, `deadInScope`, `deadModuleDisables`, `parseDisableAnn` and
  both renderers are pure and unit-tested, the way `deadDisableTargets` was.
  Every scope (module, binding, local binding) crossed with every kind of
  disable (all operators, a named one, an unknown name, a malformed string)
  has a case.
* `nix build .#checks.x86_64-linux.mutation-dead-disable` -- new. Compiles
  each module in `sydtest-mutation-plugin/test_resources/dead-disable` through
  the plugin, one derivation per module. A module with a companion `.expected`
  file must fail to compile with that text in the output; a module without one
  must compile. I falsified it both ways before trusting it: a wrong
  `.expected` fails that module, and turning a live annotation dead fails the
  module that must compile.
* `nix build .#checks.x86_64-linux.mutation-manifest-example` -- the goldens
  come out **unchanged**, which is the invariant: this adds errors, it must
  not change which mutations are produced.
* `nix flake check` -- passes.

### Why there is a compile check at all

The unit tests hand `deadDisables` a ready-made set of operators that fired.
Producing that set from real syntax is the measuring walk, which is the whole
mechanism, and nothing else exercises it: the example package cannot carry a
dead annotation, because a dead annotation fails to compile there too.

I looked at the alternatives before keeping it:

* **In-process GHC API with `StaticPlugin`, driven from the sydtest suite.**
  Cleanest on paper. Two problems: the plugin's parsed-stage action injects
  `import Test.Syd.Mutation.Plugin.Runtime`, so the session needs the
  project's package databases, discoverable only through environment that
  differs between stack, cabal and nix; and it adds a second GHC-API surface
  (session setup, logger hook, diagnostic extraction) to keep working across
  GHC upgrades, on top of the plugin's own. `ghc -c` is stable across both.
* **`should-not-typecheck`.** Only works for deferred *type* errors;
  `addErrAt` diagnostics are not deferrable.
* **A cabal component expected to fail to build.** Neither cabal nor nix
  expresses "must fail" without the same inverted-exit-code trick, so it is
  this check with more moving parts.
* **A golden test shelling out to `ghc` from the suite.** Trades bash for
  Haskell but keeps the package-database problem, now inside a test that must
  not be flaky.

What I did cut: the hand-rolled bash loop. Each module is its own derivation,
so they compile in parallel, cache individually, and name themselves when they
fail.

## Things worth your judgement

* **Redundancy erroring has a sharp edge**: turning an operator off in
  `mutation.yaml` now breaks the build of every module that also annotates it.
  That is what the answer asked for and nothing in this repo hits it, but it
  is the thing most likely to bite in practice. Say the word and I will make
  the configuration's disables invisible to the judgement instead.
* **A self-disable of everything makes every local disable on the same binding
  redundant**, hence an error. Consistent with the rule; the message says the
  operator "may already be disabled by configuration or by another
  annotation".
* **Binding-level annotations inside a module-disabled module are not
  checked.** The walk that judges the module annotation is thrown away, and a
  walk that is thrown away reports nothing, so nothing inside it is judged.
  `ModuleDisabledWithBindingAnn.hs` pins that.
* **A module-level `DisableMutations: A, B` next to a bare `DisableMutations`**
  is measured in one pass with all of them lifted, so a named one that does
  fire is not flagged as redundant with the bare one. Bizarre edge case, left
  alone.
* **Error message length.** The unknown-operator message lists all 18
  operators; the malformed-annotation one lists all six recognised forms. Both
  are long, and both are exactly when you want the list.

## Two things I did that you did not ask for

* `LocalDisable` is renamed to `MutationDisable`. The type was already used for
  self-disables as well as local ones, and it is now used for module scope too,
  so the old name was actively misleading.
* **`debug` did nothing.** `settingDebug` was read into the instrumentation
  environment and never consulted, so every instrumented build printed a line
  per mutation whether or not it asked to. My measurement pass needed that
  print silenced, and the field I needed to consult was dead, so I gated the
  print on the flag it documents. In-repo checks pass `debug: true` in
  `nix/mutation.yaml` and keep their output; a build that does not ask for it
  is now quiet. Also removed the genuinely unused
  `instrumentEnvDisabledMutations` field.

## History worth knowing about before you squash

An early `git add -A` of mine swept two of your untracked scratch files
(`POSTGRES-STARTUP-FLAKE.md`, `race.hs`) into 035ef706; 11b4d518 untracked
them, a later `git add -A` re-added them in c094d392, and b1cdcbaa finally
deletes them. They are gone from the branch tip and from your working tree
(the note said "Delete or move it when the investigation closes"), and
recoverable from 035ef706 if you want them back. Four commits of churn that
want squashing away.

## Worth trying out locally

```
# The errors themselves, one module at a time:
cd sydtest-mutation-plugin/test_resources/dead-disable
stack exec -- ghc -c -O0 -fplugin=Test.Syd.Mutation.Plugin \
  -plugin-package=sydtest-mutation-plugin -package=sydtest-mutation-plugin \
  DeadSelfOperator.hs

# Or read them all at once:
nix build .#checks.x86_64-linux.mutation-dead-disable -L
```

Then the thing I would most want a second opinion on: take a live annotation in
`sydtest-mutation-example` (say `Example.IgnoreLib.mark`'s
`DisableMutation: ConstEmptyList`), change the operator name to another real
one, and check that the error reads the way you would want it to when it
catches you rather than a test.