fallow 3.41.0 → 3.42.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -1261,6 +1261,22 @@
           "required": false,
           "description": "Run at most N covered mutants, in rank order. Uncovered mutants do not count. The others are `pending`"
         },
+        {
+          "name": "--mutants-per-line",
+          "type": "string",
+          "required": false,
+          "description": "Keep at most N mutants on each source line. The plan keeps the most productive mutants of the line (relational, condition, arithmetic and logical operators first). The others are `pending` with the reason `sampled-out` and do not run (default: the `mutation.mutantsPerLine` key, else each mutant)"
+        },
+        {
+          "name": "--function-scope",
+          "type": "bool",
+          "required": false,
+          "description": "Widen each changed line to the whole function that holds it, so that a changed parameter or signature selects the mutants of the function. Only the changed-code scope uses it (default: the `mutation.functionScope` key, else the changed lines only)",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
         {
           "name": "--time-budget",
           "type": "string",
@@ -1309,7 +1325,7 @@
           "name": "--operators",
           "type": "string",
           "required": false,
-          "description": "The operators to use, comma-separated (default: each operator)"
+          "description": "The operators to use, comma-separated. Default: the default set. The opt-in operators (block-statement, array-literal, object-literal, method-expression, switch-case, call-expression, throw-statement, regex-constructor, regex-assertion) run only when named here"
         },
         {
           "name": "--verdicts",
@@ -1333,7 +1349,7 @@
           "name": "--typecheck",
           "type": "bool",
           "required": false,
-          "description": "Type-check each survived mutant through the `--type-aware` companion. A survivor that does not type-check becomes `compile_error` and leaves the score",
+          "description": "Type-check each survived mutant through the `--type-aware` companion. A survivor that does not type-check becomes `compile_error` and leaves the score. An optional-chaining survivor on a receiver whose type excludes `null` and `undefined` gets an advisory `equivalence_hint`. Its status and the score do not change",
           "possible_values": [
             "true",
             "false"
@@ -2692,6 +2708,24 @@
           "type": "string",
           "required": true,
           "description": "Path to a fallow JSON results file produced by `--format json` (dead-code, architecture, dupes, health, audit, security, or bare combined)"
+        },
+        {
+          "name": "--mutation-report",
+          "type": "string",
+          "required": false,
+          "description": "A saved `fallow mutation --format json` report, or the JSON error envelope of a failed run, to render with the results. Applies to the pr-comment, review, github-summary, github-annotations and codeclimate formats only. The paths in the report are relative to the root of the mutation run, which must be the `--root` of this call"
+        },
+        {
+          "name": "--mutation-not-run",
+          "type": "string",
+          "required": false,
+          "description": "Why mutation testing did not run in this job, so the render states it. Applies to the same formats as `--mutation-report`",
+          "possible_values": [
+            "event-refused",
+            "fork-refused",
+            "no-change-scope",
+            "interrupted"
+          ]
         }
       ]
     },
@@ -7249,6 +7283,36 @@
       "license": "free",
       "license_note": null,
       "docs_url": "https://fallow.tools/docs/cli/audit/#diff-risk-rules"
+    },
+    {
+      "id": "mutation-survived",
+      "rule_id": "fallow/mutation-survived",
+      "command": "mutation",
+      "category": "Tests",
+      "description": "A small code change made no test fail",
+      "label": null,
+      "config_key": null,
+      "registry_index": null,
+      "aliases": [],
+      "lsp": false,
+      "filter_flag": null,
+      "result_key": null,
+      "summary_label": null,
+      "summary_docs_anchor": null,
+      "sarif_rule_ids": null,
+      "codeclimate_check_names": null,
+      "ts_alias": null,
+      "counts_in_total": false,
+      "fixable": false,
+      "suppressible": false,
+      "suppress_comment": null,
+      "default_severity": null,
+      "opt_in": null,
+      "frameworks": [],
+      "note": null,
+      "license": "free",
+      "license_note": null,
+      "docs_url": "https://fallow.tools/docs/cli/mutation/"
     }
   ],
   "suppression_comments": {
@@ -7946,6 +8010,8 @@
           "all",
           "paths",
           "max_mutants",
+          "mutants_per_line",
+          "function_scope",
           "operators"
         ],
         "license": "free",
@@ -8576,7 +8642,7 @@
     ]
   },
   "plugins": {
-    "count": 150,
+    "count": 156,
     "note": "Built-in framework plugins, auto-activated when their enabler dependency is present; run fallow list --plugins for the set active in a specific project",
     "names": [
       "nextjs",
@@ -8592,6 +8658,7 @@
       "redwoodsdk",
       "tanstack-router",
       "waku",
+      "solid-start",
       "react-native",
       "expo",
       "expo-router",
@@ -8612,6 +8679,7 @@
       "supabase",
       "vitepress",
       "rspress",
+      "dumi",
       "next-intl",
       "relay",
       "electron",
@@ -8630,6 +8698,7 @@
       "ember",
       "eve",
       "vite",
+      "vite-plugin-pages",
       "vscode",
       "webpack",
       "rollup",
@@ -8673,6 +8742,7 @@
       "tailwind",
       "postcss",
       "unocss",
+      "unplugin-icons",
       "pandacss",
       "prisma",
       "drizzle",
@@ -8710,10 +8780,12 @@
       "typedoc",
       "openapi-ts",
       "plop",
+      "gulp",
       "c8",
       "nyc",
       "msw",
       "napi-rs",
+      "n8n",
       "opencode",
       "nodemon",
       "pm2",

package/issue-registry.json

@@ -3336,6 +3336,36 @@
       "license_note": null,
       "docs_url": "https://fallow.tools/docs/cli/security/"
     },
+    {
+      "id": "mutation-survived",
+      "rule_id": "fallow/mutation-survived",
+      "command": "mutation",
+      "category": "Tests",
+      "description": "A small code change made no test fail",
+      "label": null,
+      "config_key": null,
+      "registry_index": null,
+      "aliases": [],
+      "lsp": false,
+      "filter_flag": null,
+      "result_key": null,
+      "summary_label": null,
+      "summary_docs_anchor": null,
+      "sarif_rule_ids": null,
+      "codeclimate_check_names": null,
+      "ts_alias": null,
+      "counts_in_total": false,
+      "fixable": false,
+      "suppressible": false,
+      "suppress_comment": null,
+      "default_severity": null,
+      "opt_in": null,
+      "frameworks": [],
+      "note": null,
+      "license": "free",
+      "license_note": null,
+      "docs_url": "https://fallow.tools/docs/cli/mutation/"
+    },
     {
       "id": "mysql-multiple-statements",
       "rule_id": "security/mysql-multiple-statements",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript: health, complexity, duplication, architecture, styling drift, and unused code from one graph. CLI, LSP, and MCP server. Zero config for over 100 frameworks.",
   "license": "MIT",
@@ -92,14 +92,14 @@
     "@tanstack/intent": "0.5.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.41.0",
-    "@fallow-cli/darwin-x64": "3.41.0",
-    "@fallow-cli/linux-x64-gnu": "3.41.0",
-    "@fallow-cli/linux-arm64-gnu": "3.41.0",
-    "@fallow-cli/linux-x64-musl": "3.41.0",
-    "@fallow-cli/linux-arm64-musl": "3.41.0",
-    "@fallow-cli/win32-arm64-msvc": "3.41.0",
-    "@fallow-cli/win32-x64-msvc": "3.41.0",
-    "fallow-type-aware": "3.41.0"
+    "@fallow-cli/darwin-arm64": "3.42.0",
+    "@fallow-cli/darwin-x64": "3.42.0",
+    "@fallow-cli/linux-x64-gnu": "3.42.0",
+    "@fallow-cli/linux-arm64-gnu": "3.42.0",
+    "@fallow-cli/linux-x64-musl": "3.42.0",
+    "@fallow-cli/linux-arm64-musl": "3.42.0",
+    "@fallow-cli/win32-arm64-msvc": "3.42.0",
+    "@fallow-cli/win32-x64-msvc": "3.42.0",
+    "fallow-type-aware": "3.42.0"
   }
 }

package/schema.json

@@ -189,7 +189,7 @@
       }
     },
     "mutation": {
-      "description": "Configures the explicit `fallow mutation` workflow: `runner` (`auto`\nor `vitest`), `operators` (kebab-case names, default each operator),\n`minScore` (0 to 100; a lower score exits with code 1), and\n`concurrency` (half the logical cores). No key starts a run, and the\nside-effect override is a CLI flag only.",
+      "description": "Configures the explicit `fallow mutation` workflow: `runner` (`auto`\nor `vitest`), `operators` (kebab-case names, default the default set),\n`minScore` (0 to 100; a lower score exits with code 1), and\n`concurrency` (half the logical cores). No key starts a run, and the\nside-effect override is a CLI flag only.",
       "$ref": "#/$defs/MutationConfig"
     },
     "health": {
@@ -1174,7 +1174,7 @@
           "default": "auto"
         },
         "operators": {
-          "description": "The operators to use. Unset uses each operator. `--operators` wins.",
+          "description": "The operators to use. Unset uses the default set. An opt-in operator\nruns only when this list or `--operators` names it. `--operators`\nwins.",
           "type": [
             "array",
             "null"
@@ -1202,8 +1202,24 @@
           "format": "uint",
           "minimum": 1
         },
+        "mutantsPerLine": {
+          "description": "The maximum number of mutants on one source line. The plan keeps the\nmost productive mutants of the line (relational, condition,\narithmetic and logical operators first). The others are `pending`\nwith the reason `sampled-out`. Unset keeps each mutant.\n`--mutants-per-line` wins.",
+          "type": [
+            "integer",
+            "null"
+          ],
+          "format": "uint",
+          "minimum": 1
+        },
+        "functionScope": {
+          "description": "Widen each changed line to the whole function that holds it, so that a\nchange to a parameter or a signature selects the mutants of the\nfunction. Only the changed-code scope uses it. Unset or `false` mutates\nthe changed lines only. `--function-scope` turns it on.",
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
         "typecheck": {
-          "description": "Type-check each survived mutant through the TypeScript-Go companion\nof `--type-aware`. A survivor that does not type-check becomes\n`compile_error` and does not count in the score. Unset or `false`\nchecks no survivor. `--typecheck` turns the check on.",
+          "description": "Type-check each survived mutant through the TypeScript-Go companion\nof `--type-aware`. A survivor that does not type-check becomes\n`compile_error` and does not count in the score. A survivor that\nremoves an optional-chaining link from a receiver whose type excludes\n`null` and `undefined` gets an advisory `equivalence_hint`. Its status\nand the score do not change. Unset or `false` checks no survivor.\n`--typecheck` turns the check on.",
           "type": [
             "boolean",
             "null"
@@ -1293,7 +1309,7 @@
           "const": "boolean-literal"
         },
         {
-          "description": "A string literal emptied or filled.",
+          "description": "A string or template literal emptied or filled.",
           "type": "string",
           "const": "string-literal"
         },
@@ -1303,7 +1319,7 @@
           "const": "optional-chaining"
         },
         {
-          "description": "One token of a regular expression literal changed: an anchor\nremoved, a character class negated, or a class escape with the\nopposite case.",
+          "description": "One token of a regular expression literal changed: an anchor or a\nquantifier removed, a `{n,m}` range shortened to `{n}`, a character\nclass negated, or a class escape with the opposite case.",
           "type": "string",
           "const": "regex-literal"
         },
@@ -1311,6 +1327,51 @@
           "description": "`z.number().int()` to `z.number()` in a module-level `const`\ninitializer: one call link of a fluent chain removed.",
           "type": "string",
           "const": "removed-chain-link"
+        },
+        {
+          "description": "Opt-in. The statements of a block or function body removed.",
+          "type": "string",
+          "const": "block-statement"
+        },
+        {
+          "description": "Opt-in. `[x]` to `[]`, and `[]` to `[\"fallow\"]`.",
+          "type": "string",
+          "const": "array-literal"
+        },
+        {
+          "description": "Opt-in. A non-empty object literal to `{}`.",
+          "type": "string",
+          "const": "object-literal"
+        },
+        {
+          "description": "Opt-in. `startsWith` to `endsWith` and the other method pairs, or\n`s.trim()` to `s`.",
+          "type": "string",
+          "const": "method-expression"
+        },
+        {
+          "description": "Opt-in. The statements of a `case` clause removed.",
+          "type": "string",
+          "const": "switch-case"
+        },
+        {
+          "description": "Opt-in. A call in an expression position to `void 0`.",
+          "type": "string",
+          "const": "call-expression"
+        },
+        {
+          "description": "Opt-in. A `throw new X(...)` statement removed.",
+          "type": "string",
+          "const": "throw-statement"
+        },
+        {
+          "description": "Opt-in. The regex changes applied to a `new RegExp(\"...\")` pattern.",
+          "type": "string",
+          "const": "regex-constructor"
+        },
+        {
+          "description": "Opt-in. A lookaround negated, or `\\b` and `\\B` swapped.",
+          "type": "string",
+          "const": "regex-assertion"
         }
       ]
     },

package/skills/fallow/references/cli-reference.md

@@ -53,7 +53,7 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `type-aware` | Inspect the optional TypeScript semantic companion |  |
 | `doctor` | Diagnose project readiness without analysis or mutation |  |
 | `similar-code` | Find semantically similar functions with a pinned local model (opt-in) | `--threshold`, `--min-lines`, `--top`, `--file` |
-| `mutation` | Measure how well the tests detect changes in the code (opt-in) | `--all`, `--plan`, `--max-mutants`, `--time-budget`, `--concurrency`, `--runtime`, `--runner-config`, `--allow-dirty`, `--allow-side-effects` |
+| `mutation` | Measure how well the tests detect changes in the code (opt-in) | `--all`, `--plan`, `--max-mutants`, `--mutants-per-line`, `--function-scope`, `--time-budget`, `--concurrency`, `--runtime`, `--runner-config`, `--allow-dirty`, `--allow-side-effects` |
 | `inspect` | Compose one evidence bundle for a file or exported symbol, with optional Fallow Cloud production data | `--file <path>`, `--symbol <file>:<export>`, `--cloud`, `--repo <owner/repo>` |
 | `cloud` | Log in to Fallow Cloud with the device flow and store a read-only API key (login, logout) | `login --machine-name <name>`, `login --api-url <url>`, `logout` |
 | `trace` | Trace a symbol's call chain, or with `--path` the shortest import path between two modules (best-effort, syntactic; OFF the ranked path) | `symbol`, `--path <FROM> <TO>`, `--eager-only`, `--callers`, `--callees`, `--depth` |
@@ -85,7 +85,7 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `decision-surface` | Surface the consequential structural DECISIONS a change embeds (the apex of the review brief), each framed as a judgment question with the routed expert to ask | `--max-decisions` |
 | `impact` | Show what fallow has done for you: how many issues it is surfacing, the trend since the last recorded run, and how many commits it contained at the pre-commit gate | `--all`, `--sort`, `--limit` |
 | `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Rule families include the graph rule `client-server-leak`, a data-driven `tainted-sink` catalogue, and the include-required `hardcoded-secret` category for provider-prefix credentials and high-entropy literals assigned to secret-shaped identifiers. Most catalogue rows require non-literal input; narrowly literal-aware rows flag deterministic unsafe literals. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. Add project-local request object names with `security.requestReceivers`; it extends the built-in `req` / `request` / `ctx` / `context` / `event` allowlist for HTTP `query`, `params`, and `body` reads. `hardcoded-secret` runs only when listed in `security.categories.include`. | `--format human\|json\|sarif`, `--changed-since`, `--file`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--surface`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
-| `report` | Render a saved `--format json` results file in another format without re-running analysis (analyze once, render annotations and the job summary from the same file). | `--from` |
+| `report` | Render a saved `--format json` results file in another format without re-running analysis (analyze once, render annotations and the job summary from the same file). With a CI format, `--mutation-report` adds a saved `fallow mutation --format json` report, and `--mutation-not-run` states why mutation testing did not run. | `--from`, `--mutation-report`, `--mutation-not-run` |
 | `schema` | Dump CLI definition as JSON |  |
 | `ci-template` | Print or vendor CI integration templates |  |
 | `migrate` | Convert knip/jscpd config | `--dry-run`, `--from PATH` |
@@ -530,7 +530,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.41.0",
+  "fallow_version": "3.42.0",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -742,7 +742,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1217,7 +1217,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1305,7 +1305,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1406,7 +1406,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1435,7 +1435,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -2263,7 +2263,7 @@ Use this mode to check whether specific tests are redundant without a full kill
 
 - Only the mutants that a target test covers run. The other mutants are `pruned` with `prune_reason: "no-target-coverage"`.
 - Each mutant runs its target tests with bail disabled, then its other covering tests with bail enabled, up to the first failure.
-- `kill_matrix.targets` lists each target with the `test_ids` that it selects. A target that selects no test exits `2` with `FALLOW_MUTATION_TARGET_UNMATCHED`.
+- `kill_matrix.targets` lists each target with the `test_ids` that it selects. A target that selects no test exits `2` with `FALLOW_MUTATION_TARGET_UNMATCHED`. A test ID target that names a duplicate test ID (two tests of one file with the same title) exits `2` with `FALLOW_MUTATION_TARGET_DUPLICATE_TEST_ID`. A file target drops the duplicate IDs, and the `duplicate-test-ids` entry of `errors` names them.
 - Each target has its own `status` (`complete` or `incomplete`) and `reasons`. Only the tests of a complete target can be candidates. `candidates` can be nonempty while the top-level `status` is `incomplete`.
 - `kill_matrix.tests` has rows for target tests only. `unique_kills` are kills that no other test detects, target or not. `target_only_kills` lists kills that only other targets share, each with those `targets`. `subsuming_tests` is empty (note `subsumers-not-computed`).
 - A target with kills and no `unique_kills` is a candidate. With `target_only_kills`, it stays redundant only while one of the sharing targets stays. Do not remove all sharing targets together.
@@ -2331,7 +2331,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2491,7 +2491,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2535,11 +2535,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.41.0",
+  "version": "3.42.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.41.0",
+    "version": "3.42.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/issue-types.md

@@ -90,6 +90,7 @@ The `generated:issue-types` table below is regenerated from `fallow schema` by s
 | `test-only-branch` | - | - | `// fallow-ignore-next-line test-only-branch` | The change adds a test-environment branch to source code |
 | `diverged-clone-sibling` | - | - | `// fallow-ignore-next-line diverged-clone-sibling` | The change edits one copy of duplicated code but not its siblings |
 | `added-dependency` | - | - | - | The change adds a dependency. Config suppression only, because `package.json` cannot hold a comment: set `added-dependency` to `off` for the path in an `overrides` entry. |
+| `mutation-survived` | - | - | - | A small code change made no test fail |
 
 Runtime-coverage verdicts and the full security sink catalogue are listed by `fallow schema` (`issue_types`).
 <!-- generated:issue-types:end -->

package/skills/fallow/references/mcp.md

@@ -18,7 +18,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `security_candidates` | analysis | free | `fallow security --format json --quiet` | `gate`, `surface`, `changed_since`, `paths` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, severity, evidence, trace, optional `reachability`, blind-spot counters, and optional `unresolved_callee_diagnostics` samples for dynamic callee follow-up. `severity` is a review-priority tier, not a verified vulnerability verdict. Each finding also carries an agent-actionable `candidate` (`source_kind`/`sink`/`boundary`), where URL-category sinks may include `url_shape` (`fixed-origin-dynamic-path` or `dynamic-origin`), an optional `taint_flow` source-to-sink triple, and a stable `finding_id` (equal to the SARIF fingerprint) for cross-run correlation; there is no `impact` field (deciding exploitability is the agent's job). Set `surface: true` to include top-level `attack_surface[]` entries with defensive-boundary prompts for a verifier. Set `gate` to `new` for changed-line candidates or `newly-reachable` for candidates that became reachable from entry points; `newly-reachable` requires `changed_since`. `reachability.untrusted_source_trace` is module-level import context only and does not prove value flow; `reachability.taint_confidence` tiers each reachable candidate as `arg-level` (sink argument traces to a same-module source read, strong) or `module-level` (only the module is import-reachable from a source, weak), so tier from this field instead of the evidence text. Verify trace, reachability context, severity, and evidence before editing code. Supports `root`, `config`, `workspace`, `paths`, `changed_since`, `changed_workspaces`, `surface`, `gate`, `no_cache`, and `threads`; `paths` forwards repeated `fallow security --file` filters for finding anchors, trace hops, untrusted-source reachability trace hops, and unresolved-callee diagnostics. See <https://fallow.tools/docs/cli/security-agent-verification/> for the verifier packet and verdict recipe. Inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `find_similar_code` | analysis | free | `fallow similar-code --format json --quiet` | `threshold`, `min_lines`, `top`, `changed_since`, `paths` | Find unverified semantically similar function candidates with the exact pinned local model. Discovery is read-only and never authorizes or performs model setup. Scoped output materializes the exact admitted files once in `generation.scope.paths` as provenance. Ask the user to run `fallow similar-code setup --local` when setup is missing. Cold local inference has a dedicated 15-minute subprocess window. |
 | `inspect_similar_code` | trace | free | `fallow similar-code inspect <candidate-id> --candidates <report.json> --format json --quiet` | `candidate_id`, `snapshot` | Inspect one exact unverified candidate without rerunning provider retrieval or global ranking. Pass `candidate_id` plus a bounded typed snapshot containing the unchanged discovery `schema_version`, `generation`, selected `candidate`, `completion`, and `diagnostics`. Current source is re-extracted and both endpoint hashes must still match, so stale source fails closed. Keep candidate worthiness, behavioral equivalence, and refactor safety as separate verdicts, and abstain when evidence is incomplete. |
-| `mutation_plan` | analysis | free | `fallow mutation --plan --format json --quiet` | `changed_since`, `all`, `paths`, `max_mutants`, `operators` | Static mutation plan for changed code: mutant ids, operators, dispositions, and static test files; runs no tests |
+| `mutation_plan` | analysis | free | `fallow mutation --plan --format json --quiet` | `changed_since`, `all`, `paths`, `max_mutants`, `mutants_per_line`, `function_scope`, `operators` | Static mutation plan for changed code: mutant ids, operators, dispositions, and static test files; runs no tests |
 | `mutation_inspect` | trace | free | `fallow mutation inspect <mutant-id> [--report <report.json>] --format json --quiet` | `mutant_id`, `report` | Inspect one mutant of a saved mutation report (default: the last run report), with a stale status when its source changed; runs no tests |
 | `mutation_tasks` | trace | free | `fallow mutation tasks [--report <report.json>] --format json --quiet` | `report` | The open tasks of a saved mutation report (default: the last run report) as one batch: each survived or uncovered mutant with its source lines before and after the change; runs no tests |
 | `inspect_target` | analysis | free | `fallow inspect --format json --quiet` | `target`, `production`, `include_churn`, `cloud` | Compose one evidence bundle for a file or exported symbol. File targets use `target: { type: "file", file }`; symbol targets use `target: { type: "symbol", file, export_name }`. Returns `kind: "inspect_target"`, normalized target identity, `trace_file`, optional `trace_export`, file-scoped dead-code actions, duplication groups filtered to the file, complexity findings filtered to the file, and security candidates scoped to the file. Set `include_churn: true` to add target-level git churn from the health hotspot subsystem. Churn is off by default, and unavailable git history or analysis failures remain explicit section states. Evidence sections carry `status` and `scope`; symbol targets warn when supporting evidence is file-scoped. Set `cloud: true` on a file target to add the `cloud` evidence section of `fallow inspect --cloud` (production data per local function). The CLI reads the key: `FALLOW_API_KEY` in the server environment, else the key that `fallow cloud login` stored; the key is never a parameter. `repo` (`owner/repo`) selects the repository and needs `cloud: true`. The section `status` is `ok`, `no_key`, `plan_required`, `unavailable` or `untracked`; a status other than `ok` never fails the call. `cloud: true` with a symbol target is refused. Set `format: "compact"` to get the plain text of `fallow inspect --format compact` (about 1 KB, no JSON) instead of the JSON bundle. Supports `root`, `config`, `production`, `workspace`, `include_churn`, `cloud`, `repo`, `format`, `no_cache`, and `threads`; `production` applies to trace, dead-code, and health evidence only. Raise `FALLOW_TIMEOUT_SECS` for large repos. |

package/types/output-contract.d.ts

@@ -1811,7 +1811,7 @@ export type MutationSchemaVersion = "2"
 /**
  * Why a run is partial.
  */
-export type MutationIncompleteReason = ("runtime-error" | "mutant-limit" | "time-budget" | "skipped-files" | "unloaded-files" | "test-files-not-discovered" | "baseline-failure" | "worktree-changed" | "typecheck-failed" | "worktree-unchecked")
+export type MutationIncompleteReason = ("runtime-error" | "mutant-limit" | "sampled-out" | "time-budget" | "skipped-files" | "unloaded-files" | "test-files-not-discovered" | "baseline-failure" | "worktree-changed" | "typecheck-failed" | "worktree-unchecked")
 /**
  * The quality of observed test-to-mutant evidence.
  */
@@ -1832,6 +1832,10 @@ export type MutantStatus = ("killed" | "timeout" | "survived" | "no_coverage" |
  * How a run detected a mutant.
  */
 export type MutantFailureKind = ("assertion" | "error" | "timeout")
+/**
+ * Why a survivor may be equivalent, as far as the type check can tell.
+ */
+export type MutantEquivalenceHint = "type-non-nullish"
 /**
  * Why the type check did not check a survivor.
  */
@@ -2054,7 +2058,7 @@ diff_risk_introduced: number
  * The key set is OPEN. A name that a consumer does not recognize means "some
  * gate", not an error.
  *
- * The names that this build can emit are `error-severity-findings`, `regression`, `stale-baseline`, `baseline-growth`, `duplication-threshold`, `duplication-findings`, `health-min-score`, `health-min-severity`, `health-findings`, `health-coverage-gaps`, `health-runtime-coverage`, `security`, `security-advisory`, `audit-verdict`, `type-aware-require` and `parse-error`. `GateName` describes each name and the default entries of each command.
+ * The names that this build can emit are `error-severity-findings`, `regression`, `stale-baseline`, `baseline-growth`, `duplication-threshold`, `duplication-findings`, `health-min-score`, `health-min-severity`, `health-findings`, `health-coverage-gaps`, `health-runtime-coverage`, `security`, `security-advisory`, `audit-verdict`, `type-aware-require`, `parse-error` and `mutation-min-score`. `GateName` describes each name and the default entries of each command.
  */
 export interface GateOutcomes {
 [k: string]: GateOutcome
@@ -7928,11 +7932,11 @@ start_line: number
  */
 end_line: number
 /**
- * 0-based start column.
+ * 0-based byte column offset of the start.
  */
 start_col: number
 /**
- * 0-based end column.
+ * 0-based byte column offset of the end.
  */
 end_col: number
 /**
@@ -15236,11 +15240,11 @@ start_line: number
  */
 end_line: number
 /**
- * 0-based start column.
+ * 0-based byte column offset of the start.
  */
 start_col: number
 /**
- * 0-based end column.
+ * 0-based byte column offset of the end.
  */
 end_col: number
 /**
@@ -20731,6 +20735,12 @@ recheck?: (MutationRecheck | null)
  * `--compare`, and absent when this run is not complete.
  */
 compare?: (MutationCompare | null)
+/**
+ * The verdict of the `mutation-min-score` gate. Present only when a
+ * minimum applies: from `--min-score`, or from `mutation.minScore` when
+ * the run is not a recheck. The exit code of the run reads this entry.
+ */
+gate_outcomes?: (GateOutcomes | null)
 }
 /**
  * The completion status of a run.
@@ -20969,6 +20979,11 @@ score?: (number | null)
  * mutants never count. `null` when no mutant is covered or unreached.
  */
 coverage?: (number | null)
+/**
+ * The `pending` mutants that the `--mutants-per-line` limit left out of
+ * the plan. They are part of `counts.pending`.
+ */
+sampled_out: number
 }
 /**
  * One mutant of a run.
@@ -21023,6 +21038,13 @@ status: MutantStatus
  * The static rule of a `pruned` mutant, kebab-case.
  */
 prune_reason?: (string | null)
+/**
+ * Why a `pending` mutant did not run, kebab-case. Only `sampled-out` has
+ * a reason: the `--mutants-per-line` limit left the mutant out of the
+ * plan. A mutant that the mutant limit or the time budget left out has
+ * no reason.
+ */
+pending_reason?: (string | null)
 /**
  * The test that killed the mutant in this run. Absent for a kill by an
  * error outside a test.
@@ -21092,14 +21114,23 @@ resumed?: boolean
  * `compile_error` mutant, sorted, at most 8.
  */
 type_error_codes?: number[]
+/**
+ * An advisory hint that the mutant may be equivalent to the original
+ * code. The hint never changes the status: the mutant stays `survived`
+ * and counts in the score. A person decides, and records the decision in
+ * a verdict file. The hint can be wrong.
+ */
+equivalence_hint?: (MutantEquivalenceHint | null)
 }
 /**
  * The edit of a mutant, without project text.
  *
  * Each side is an operator token (for example `??` or `<=`), a fixed literal
  * (`true`, `undefined`, `""`, `"fallow"`, `void 0`), a regular expression
- * token (`^`, `$`, `[`, `[^`, `\d`), or a placeholder for a side that is
- * project code: `<condition>`, `<call>`, `<expression>` or `<string>`. An
+ * token (`^`, `$`, `[`, `[^`, `+`, `{n,m}`, `\d`), or a placeholder for a
+ * side that is project code: `<condition>`, `<call>`, `<expression>`,
+ * `<string>`, `<template>`, `<statement>`, `<statements>`, `<array>` or
+ * `<object>`. An
  * empty side means that the edit removes the token.
  */
 export interface MutantChange {
@@ -21284,9 +21315,9 @@ changed_paths: string[]
 export interface MutationRunIssue {
 /**
  * A stable kebab-case code: `cache-write-failed`,
- * `journal-write-failed`, `runtime-error`, `static-map-miss`,
- * `test-files-not-discovered`, `typecheck-failed`, `worktree-changed`
- * or `worktree-check-failed`.
+ * `duplicate-test-ids`, `journal-write-failed`, `runtime-error`,
+ * `skipped-tests`, `static-map-miss`, `test-files-not-discovered`,
+ * `typecheck-failed`, `worktree-changed` or `worktree-check-failed`.
  */
 code: string
 /**
@@ -21401,6 +21432,12 @@ checked: number
  * `compile_error`.
  */
 compile_errors: number
+/**
+ * The mutants of the final report that have an `equivalence_hint`. They
+ * keep the status `survived`. A verdict that makes a mutant `equivalent`
+ * removes its hint and lowers this count.
+ */
+hinted?: number
 /**
  * The survivors that the checker did not check, by reason.
  */
@@ -21586,9 +21623,13 @@ total: number
  */
 planned: number
 /**
- * Mutants after the mutant limit.
+ * Mutants after the mutant limit, and the sampled-out mutants.
  */
 pending: number
+/**
+ * The `pending` mutants that the `--mutants-per-line` limit left out.
+ */
+sampled_out: number
 /**
  * Mutants that no test file reaches.
  */
@@ -21663,6 +21704,13 @@ disposition: MutationPlanDisposition
  * The static rule of a `pruned` mutant, kebab-case.
  */
 prune_reason?: (string | null)
+/**
+ * Why a `pending` mutant did not run, kebab-case. Only `sampled-out` has
+ * a reason: the `--mutants-per-line` limit left the mutant out of the
+ * plan. A mutant that the mutant limit or the time budget left out has
+ * no reason.
+ */
+pending_reason?: (string | null)
 /**
  * How tests reach the code of the mutant in the module graph. Only a
  * `no_coverage` mutant has this field.
@@ -21864,6 +21912,12 @@ original_lines?: (string | null)
  * stale.
  */
 mutated_lines?: (string | null)
+/**
+ * An advisory hint that the mutant may be equivalent. The task stays
+ * open: a person decides, and records an equivalent mutant in a verdict
+ * file.
+ */
+equivalence_hint?: (MutantEquivalenceHint | null)
 /**
  * Why the current file no longer gives the mutant. Absent for a fresh
  * task.