fallow 3.29.0 → 3.30.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -1055,6 +1055,16 @@
           "required": false,
           "description": "Shortest import path between two modules, as two file paths (e.g. `--path src/app.ts src/db.ts`). Mutually exclusive with the symbol target and the call-chain flags"
         },
+        {
+          "name": "--eager-only",
+          "type": "bool",
+          "required": false,
+          "description": "With `--path`, follow only static value imports, so the route explains why TO loads before FROM runs",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
         {
           "name": "--callers",
           "type": "bool",
@@ -1264,7 +1274,7 @@
     },
     {
       "name": "list",
-      "description": "List discovered entry points, files, plugins, boundaries, and workspaces",
+      "description": "List discovered entry points, files, plugins, boundaries, workspaces, and the startup import weight",
       "flags": [
         {
           "name": "--entry-points",
@@ -1316,6 +1326,16 @@
             "false"
           ]
         },
+        {
+          "name": "--entry-weight",
+          "type": "bool",
+          "required": false,
+          "description": "Show the startup import weight of each runtime entry point, in source bytes (not bundle size)",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
         {
           "name": "path",
           "type": "string",
@@ -1722,6 +1742,77 @@
           "type": "string",
           "required": false,
           "description": "Show only the top N flags"
+        },
+        {
+          "name": "--retirement",
+          "type": "bool",
+          "required": false,
+          "description": "Add a retirement report: one row per flag, with the reasons the flag can be retired. Advisory only; nothing is removed",
+          "possible_values": [
+            "true",
+            "false"
+          ]
+        },
+        {
+          "name": "--reason",
+          "type": "string",
+          "required": false,
+          "description": "Keep only retirement rows with this reason (repeatable)",
+          "possible_values": [
+            "single-read-site",
+            "test-only",
+            "literal-constant",
+            "identical-branches",
+            "empty-branch",
+            "guards-dead-code",
+            "defined-never-read",
+            "fully-rolled-out",
+            "archived-in-vendor",
+            "missing-in-vendor",
+            "vendor-only"
+          ]
+        },
+        {
+          "name": "--sort",
+          "type": "string",
+          "required": false,
+          "description": "Order of the retirement rows",
+          "default": "age",
+          "possible_values": [
+            "age",
+            "sites",
+            "name"
+          ]
+        },
+        {
+          "name": "--flag-age",
+          "type": "string",
+          "required": false,
+          "description": "How to measure flag age: blame (lower bound), pickaxe (first commit with the name, slower) or off",
+          "default": "blame",
+          "possible_values": [
+            "blame",
+            "pickaxe",
+            "off"
+          ]
+        },
+        {
+          "name": "--min-age",
+          "type": "string",
+          "required": false,
+          "description": "Keep only retirement rows at least this many days old"
+        },
+        {
+          "name": "--flag-state",
+          "type": "string",
+          "required": false,
+          "description": "Vendor flag export (JSON, read offline) that adds the fully-rolled-out, archived-in-vendor, missing-in-vendor and vendor-only reasons"
+        },
+        {
+          "name": "--max-flag-age",
+          "type": "string",
+          "required": false,
+          "description": "Exit with code 1 when a flag in scope is older than this many days. Opt-in; needs a flag age"
         }
       ]
     },
@@ -4672,6 +4763,36 @@
       "license_note": null,
       "docs_url": "https://docs.fallow.tools/cli/flags"
     },
+    {
+      "id": "flag-retirement-candidate",
+      "rule_id": "fallow/flag-retirement-candidate",
+      "command": "flags",
+      "category": "Flags",
+      "description": "Feature flag is a retirement candidate",
+      "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://docs.fallow.tools/cli/flags#retirement-report"
+    },
     {
       "id": "tainted-sink",
       "rule_id": "security/tainted-sink",
@@ -6201,8 +6322,10 @@
     "FALLOW_TIMEOUT_SECS": "MCP server: per-tool-call CLI subprocess timeout in seconds (default 120). Raise for long runs like production coverage on large dumps.",
     "FALLOW_DIFF_FILE": "MCP server: path to a unified diff that scopes all findings by changed line.",
     "FALLOW_CHANGED_SINCE": "MCP server: git ref that scopes file discovery for analysis tools.",
+    "FALLOW_MCP_WARM_SESSION": "MCP server: set to 0, false, off or no to stop typed tool calls from keeping parsed modules in memory between calls (default on).",
     "FALLOW_INTEGRATION_SURFACE": "Telemetry integration_surface override for non-CLI surfaces (mcp/lsp/vscode/napi/programmatic). Set by the MCP server on the CLI it spawns.",
-    "FALLOW_MCP_TOOL": "Telemetry mcp_tool dimension, validated against the MCP tool-name allowlist. Set by the MCP server alongside FALLOW_INTEGRATION_SURFACE=mcp."
+    "FALLOW_MCP_TOOL": "Telemetry mcp_tool dimension, validated against the MCP tool-name allowlist. Set by the MCP server alongside FALLOW_INTEGRATION_SURFACE=mcp.",
+    "FALLOW_LSP_REUSE_SESSION": "Language server: set to 0/false/off/no to load a new project session on each analysis run. By default the server keeps one session per project root between saves and parses only the changed files."
   },
   "severity_levels": [
     "error",
@@ -7331,7 +7454,7 @@
     ]
   },
   "plugins": {
-    "count": 127,
+    "count": 128,
     "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",
@@ -7345,6 +7468,7 @@
       "react-router",
       "redwoodsdk",
       "tanstack-router",
+      "waku",
       "react-native",
       "expo",
       "expo-router",

package/issue-registry.json

@@ -2402,6 +2402,36 @@
       "license_note": null,
       "docs_url": "https://docs.fallow.tools/cli/security"
     },
+    {
+      "id": "flag-retirement-candidate",
+      "rule_id": "fallow/flag-retirement-candidate",
+      "command": "flags",
+      "category": "Flags",
+      "description": "Feature flag is a retirement candidate",
+      "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://docs.fallow.tools/cli/flags#retirement-report"
+    },
     {
       "id": "hardcoded-secret",
       "rule_id": "security/hardcoded-secret",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "mcpName": "io.github.fallow-rs/fallow",
   "description": "Codebase intelligence for TypeScript and JavaScript. Free static analysis of code and styles, optional paid runtime intelligence (Fallow Runtime). Quality, risk, architecture, dependencies, duplication, and design-system drift for humans, CI, and the agents writing your code. Zero-config framework support.",
   "license": "MIT",
@@ -88,14 +88,14 @@
     "@tanstack/intent": "0.4.0"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.29.0",
-    "@fallow-cli/darwin-x64": "3.29.0",
-    "@fallow-cli/linux-x64-gnu": "3.29.0",
-    "@fallow-cli/linux-arm64-gnu": "3.29.0",
-    "@fallow-cli/linux-x64-musl": "3.29.0",
-    "@fallow-cli/linux-arm64-musl": "3.29.0",
-    "@fallow-cli/win32-arm64-msvc": "3.29.0",
-    "@fallow-cli/win32-x64-msvc": "3.29.0",
-    "fallow-type-aware": "3.29.0"
+    "@fallow-cli/darwin-arm64": "3.30.0",
+    "@fallow-cli/darwin-x64": "3.30.0",
+    "@fallow-cli/linux-x64-gnu": "3.30.0",
+    "@fallow-cli/linux-arm64-gnu": "3.30.0",
+    "@fallow-cli/linux-x64-musl": "3.30.0",
+    "@fallow-cli/linux-arm64-musl": "3.30.0",
+    "@fallow-cli/win32-arm64-msvc": "3.30.0",
+    "@fallow-cli/win32-x64-msvc": "3.30.0",
+    "fallow-type-aware": "3.30.0"
   }
 }

package/schema.json

@@ -265,7 +265,7 @@
       }
     },
     "flags": {
-      "description": "Configures feature-flag detection: `sdkPatterns` (custom flag-evaluating call signatures, each `{ function, nameArg (zero-based arg index of the flag name, default 0), provider? }`, merged with built-ins for LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, and Eppo), `envPrefixes` (env-var prefixes marking `process.env.*` accesses as flags, merged with built-ins), and `configObjectHeuristics` (default false; when true, property accesses on objects whose name contains `feature`/`flag`/`toggle` are reported as low-confidence flags). Set `sdkPatterns`/`envPrefixes` to teach fallow a proprietary flag SDK or naming convention, or enable `configObjectHeuristics` for projects that read flags off config objects (higher false-positive rate). Feature-flag findings surface only when the `feature-flags` rule is enabled (default `off`).",
+      "description": "Configures feature-flag detection: `sdkPatterns` (custom flag-evaluating call signatures, each `{ function, nameArg (zero-based arg index of the flag name, default 0), provider? }`, merged with built-ins for LaunchDarkly, Statsig, Unleash, GrowthBook, Split, PostHog, Vercel Flags, ConfigCat, Flagsmith, Optimizely, and Eppo), `envPrefixes` (env-var prefixes marking `process.env.*` and `import.meta.env.*` accesses as flags, merged with built-ins), and `configObjectHeuristics` (default false; when true, property accesses on objects whose name contains `feature`/`flag`/`toggle` are reported as low-confidence flags). Set `sdkPatterns`/`envPrefixes` to teach fallow a proprietary flag SDK or naming convention, or enable `configObjectHeuristics` for projects that read flags off config objects (higher false-positive rate). Feature-flag findings surface only when the `feature-flags` rule is enabled (default `off`).",
       "$ref": "#/$defs/FlagsConfig",
       "default": {
         "configObjectHeuristics": false
@@ -1824,7 +1824,7 @@
           }
         },
         "envPrefixes": {
-          "description": "Environment variable prefixes that indicate feature flags.\nMerged with built-in prefixes. Only `process.env.*` accesses matching\nthese prefixes are reported as feature flags.",
+          "description": "Environment variable prefixes that indicate feature flags.\nMerged with built-in prefixes. Only `process.env.*` and\n`import.meta.env.*` accesses matching these prefixes are reported as\nfeature flags.",
           "type": "array",
           "items": {
             "type": "string"
@@ -1834,6 +1834,13 @@
           "description": "Enable config object heuristic detection.\nWhen true, property accesses on objects whose name contains \"feature\",\n\"flag\", or \"toggle\" are reported as low-confidence feature flags.\nDefault: false (opt-in due to higher false positive rate).",
           "type": "boolean",
           "default": false
+        },
+        "vendorKeyPrefix": {
+          "description": "Prefix to remove from each key of a `--flag-state` vendor export\nbefore the key is compared with the flag names in the code. For\nexample, `\"web.\"` makes the vendor key `web.new-checkout` match the\ncode flag `new-checkout`. A key without the prefix is compared as it\nis.",
+          "type": [
+            "string",
+            "null"
+          ]
         }
       }
     },

package/skills/fallow/SKILL.md

@@ -192,9 +192,10 @@ Reports unused exports in entry files (package.json `main`/`exports`, framework
 ```bash
 fallow flags --format json --quiet
 fallow flags --format json --quiet --top 20
+fallow flags --retirement --format json --quiet
 ```
 
-Reports environment-variable gates (`process.env.FEATURE_*`), SDK calls from common flag providers, and config-object patterns, with flag locations, detection confidence, and a cross-reference against dead code. Only `--top N` is command-specific.
+Reports environment-variable gates (`process.env.FEATURE_*`), SDK calls from common flag providers, and config-object patterns, with flag locations, detection confidence, and a cross-reference against dead code. `--top N` limits the list. `--retirement` adds a `retirement` object with one row per flag, the reasons it can be retired (`single-read-site`, `test-only`, `literal-constant`, `identical-branches`, `empty-branch`, `guards-dead-code`, `defined-never-read`), and its age from git (`--flag-age blame|pickaxe|off`; blame gives a lower bound). Filter with `--reason <CODE>` and `--min-age <DAYS>`, order with `--sort age|sites|name`. `--flag-state <FILE>` reads an offline vendor export in one vendor-neutral schema and adds `fully-rolled-out`, `archived-in-vendor`, `missing-in-vendor` and `vendor-only`. With `--retirement`, `--save-regression-baseline <PATH>` and `--fail-on-regression --regression-baseline <PATH>` gate on `distinct_flags` (plus each `--reason` count), and the opt-in `--max-flag-age <DAYS>` fails on old flags. Every format works: compact prints `flag-retire:<reason>:<path>:<line>:<name>`, SARIF adds the rule `fallow/flag-retirement-candidate`, CodeClimate adds `fallow/flag-retirement`. The report is advisory: every action has `auto_fixable: false`, and a person decides what to remove.
 
 ### Surface security candidates for verification
 ```bash
@@ -260,7 +261,7 @@ fallow dead-code --format json --quiet --save-baseline .fallow/snapshot.json
 fallow dead-code --format json --quiet --baseline .fallow/snapshot.json
 ```
 
-`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code` and bare combined mode. `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
+`--save-regression-baseline` / `--regression-baseline` / `--fail-on-regression` / `--tolerance` are count-based gates for `dead-code`, bare combined mode, and `flags --retirement` (a flags baseline needs a PATH; without `--retirement` the options have no effect on `flags` and it warns). `--save-baseline` / `--baseline` are identity-based (track finding identity, fail on new). `audit` rejects the global baseline flags and uses `--dead-code-baseline` / `--health-baseline` / `--dupes-baseline` instead.
 
 With no path, `--save-regression-baseline` updates `regression.baseline` in the discovered fallow config, or creates `.fallowrc.json` when none exists. Pass a path only when a standalone baseline file is preferred.
 

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

@@ -52,7 +52,7 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `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` |
 | `inspect` | Compose one evidence bundle for a file or exported symbol | `--file <path>`, `--symbol <file>:<export>` |
-| `trace` | Trace a symbol's call chain (best-effort, syntactic; OFF the ranked path) | `symbol`, `--callers`, `--callees`, `--depth` |
+| `trace` | Trace a symbol's call chain (best-effort, syntactic; OFF the ranked path) | `symbol`, `--callers`, `--callees`, `--depth`, `--path`, `--eager-only` |
 | `trace-error` | Resolve a runtime stack trace's frames to the definitions they name (best-effort, syntactic; OFF the ranked path) | `trace_file` |
 | `fix` | Auto-remove unused exports/deps | `--dry-run`, `--yes` (required in non-TTY) |
 | `init` | Generate config file, AGENTS.md agent guide, or pre-commit hook | `--toml`, `--agents`, `--hooks`, `--branch` |
@@ -68,11 +68,11 @@ Every fallow command with its purpose and key flags. The table is regenerated fr
 | `guard` | Show which architecture rules apply to files before changing them | `files` |
 | `config` | Show the loaded config path and resolved config (verifies which `.fallowrc.json` is in effect) | `--path` |
 | `recommend` | Recommend a project-tailored config for an agent to author |  |
-| `list` | Inspect project structure | `--files`, `--entry-points`, `--plugins`, `--boundaries`, `--workspaces` |
+| `list` | Inspect project structure | `--files`, `--entry-points`, `--plugins`, `--boundaries`, `--workspaces`, `--entry-weight` |
 | `workspaces` | Inspect monorepo workspaces + discovery diagnostics (shorthand for `list --workspaces`) | (no flags) |
 | `dupes` | Code duplication detection | `--mode`, `--near`, `--threshold`, `--top`, `--changed-since`, `--workspace`, `--changed-workspaces`, `--skip-local`, `--cross-language`, `--ignore-imports`, `--explain-skipped`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
 | `health` | Function complexity analysis (also covers component templates as synthetic `<template>` findings: Angular external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals, plus Vue, Svelte and Astro single-file components; suppress an Angular external template with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, an Angular inline template with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator, and a `.svelte` / `.vue` / `.astro` template with `<!-- fallow-ignore-next-line complexity -->` on the line immediately above the reported line) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--css`, `--complexity-breakdown`, `--min-severity`, `--report-only`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
-| `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top` |
+| `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top`, `--retirement`, `--reason`, `--min-age`, `--flag-state`, `--max-flag-age` |
 | `suppressions` | List active fallow-ignore suppression markers (read-only inventory) | `--file` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
 | `audit` | Combined dead-code + complexity + duplication + styling for changed files, returns a verdict; `fallow review` is an alias for `fallow audit --brief` (advisory orientation brief, always exits 0) | `--base`, `--gate`, `--brief`, `--max-decisions`, `--walkthrough-guide`, `--walkthrough-file`, `--show-deprioritized`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--no-css`, `--css-deep`, `--no-css-deep`, `--include-entry-exports` |
@@ -347,6 +347,7 @@ Inspect discovered files, entry points, detected frameworks, and architecture bo
 | `--plugins` | `bool` | `false` | List active framework plugins |
 | `--boundaries` | `bool` | `false` | Show architecture boundary zones, rules, per-zone file counts, and `logical_groups[]` for `autoDiscover` parents |
 | `--workspaces` | `bool` | `false` | Show discovered monorepo workspaces plus any workspace-discovery diagnostics (malformed `package.json`, unreachable glob matches, missing tsconfig references). Available as the `fallow workspaces` alias too. |
+| `--entry-weight` | `bool` | `false` | Show the startup import weight of each runtime entry point, in source bytes (not bundle size): eager, deferred and out-of-thread modules, eager packages, and the imports that keep the most bytes eager |
 
 Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags).
 <!-- generated:flags:list:end -->
@@ -358,9 +359,14 @@ fallow list --entry-points --format json --quiet
 fallow list --plugins --format json --quiet
 fallow list --boundaries --format json --quiet
 fallow list --workspaces --format json --quiet
+fallow list --entry-weight --format json --quiet
 fallow workspaces --format json --quiet  # alias of `fallow list --workspaces`
 ```
 
+The `--entry-weight` JSON output carries `entry_weight.entries[]`, one row per runtime entry point, heaviest first. Each row has `eager_modules` and `eager_bytes` (the project modules and source bytes that load before the entry runs; `import type` and a declaration file do not count), `eager_css_bytes`, `deferred_modules` and `deferred_bytes` (reached only through `import()` or a lazy glob), `out_of_thread_modules` and `out_of_thread_bytes` (reached only through a `new URL(..., import.meta.url)` reference such as a worker URL, `child_process.fork`, a pino transport or a `module.register` hook), `eager_packages[]` with the specifiers as written, and `dominating_imports[]`. A dominating import is one import that alone keeps `exclusive_bytes` on the startup path. The unit is `source_bytes`: types and comments count, and tree shaking does not apply, so the value is not a bundle size. An import without the `type` keyword counts as eager, even when it brings in only types that TypeScript removes, so `eager_bytes` can be too high. Treat a dominating import as evidence for a review, not as a fix: a lazy load of code that the first screen needs can make startup slower.
+
+To gate eager growth in CI, save a baseline file on the main branch with `fallow list --entry-weight --save-regression-baseline <PATH>`. A later run with `--regression-baseline <PATH>` adds `entry_weight.regression`: per-entry `baseline_eager_bytes`, `current_eager_bytes`, `new_eager_packages` and `exceeded`. The comparison is report-only until you add `--fail-on-regression`; then an entry that grew more than `--tolerance` (bytes, or a percentage such as `5%`) exits 1. A new entry never fails the gate.
+
 The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `skipped-source-dotdir`, `source-read-failure`, `bun-lockb-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file`, `skipped-minified-file`, and `skipped-source-dotdir`, since those reach an envelope only from the walk that recorded them. The two analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
 
 The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
@@ -447,7 +453,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.29.0",
+  "fallow_version": "3.30.0",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -651,7 +657,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1054,7 +1060,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1110,6 +1116,13 @@ Detects feature flag patterns in the codebase. Identifies environment variable f
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--top` | `string` | - | Show only the top N flags |
+| `--retirement` | `bool` | `false` | Add a retirement report: one row per flag, with the reasons the flag can be retired. Advisory only; nothing is removed |
+| `--reason` | `single-read-site\|test-only\|literal-constant\|identical-branches\|empty-branch\|guards-dead-code\|defined-never-read\|fully-rolled-out\|archived-in-vendor\|missing-in-vendor\|vendor-only` | - | Keep only retirement rows with this reason (repeatable) |
+| `--sort` | `age\|sites\|name` | `age` | Order of the retirement rows |
+| `--flag-age` | `blame\|pickaxe\|off` | `blame` | How to measure flag age: blame (lower bound), pickaxe (first commit with the name, slower) or off |
+| `--min-age` | `string` | - | Keep only retirement rows at least this many days old |
+| `--flag-state` | `string` | - | Vendor flag export (JSON, read offline) that adds the fully-rolled-out, archived-in-vendor, missing-in-vendor and vendor-only reasons |
+| `--max-flag-age` | `string` | - | Exit with code 1 when a flag in scope is older than this many days. Opt-in; needs a flag age |
 
 Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--changed-since`](#global-flags), [`--workspace`](#global-flags).
 <!-- generated:flags:flags:end -->
@@ -1122,6 +1135,10 @@ fallow flags --format json --quiet
 # Top 10 flags
 fallow flags --format json --quiet --top 10
 
+# Flags at least 90 days old, oldest first. A row with an empty
+# `reasons` array is not a retirement candidate.
+fallow flags --retirement --min-age 90 --format json --quiet
+
 # Single workspace package
 fallow flags --format json --quiet --workspace my-package
 ```
@@ -1131,7 +1148,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1232,7 +1249,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1261,7 +1278,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1386,12 +1403,17 @@ The target is a positional argument, formatted as `FILE:SYMBOL` (for example `sr
 ```bash
 fallow trace src/utils.ts:formatDate
 fallow trace src/utils.ts:formatDate --callers --depth 3
+fallow trace --path src/main.ts src/chart.ts --format json --quiet
+fallow trace --path src/main.ts src/chart.ts --eager-only --format json --quiet
 ```
 
+Each `--path` hop carries `type_only` and `dynamic`. A `dynamic` hop loads its target only on demand (`import()`, a lazy glob) or on another thread (a worker, a fork). `--eager-only` follows static value imports only, so its route explains why a module is in the `--entry-weight` eager set of `fallow list`.
+
 <!-- generated:flags:trace:start -->
 | Flag | Type | Default | Description |
 |---|---|---|---|
 | `--path` | `string` | - | Shortest import path between two modules, as two file paths (e.g. `--path src/app.ts src/db.ts`). Mutually exclusive with the symbol target and the call-chain flags |
+| `--eager-only` | `bool` | `false` | With `--path`, follow only static value imports, so the route explains why TO loads before FROM runs. `import()`, lazy globs, worker loads and `import type` do not qualify |
 | `--callers` | `bool` | `false` | Walk UP to callers (modules that import the symbol). When neither `--callers` nor `--callees` is set, both directions are walked |
 | `--callees` | `bool` | `false` | Walk DOWN to callees (the symbol's module's import-symbol edges plus unresolved call sites). When neither flag is set, both are walked |
 | `--depth` | `string` | - | Chain depth bound for both directions (default 2). Symbol-level is best-effort, so a shallow bound keeps the trace legible |
@@ -2034,7 +2056,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2194,7 +2216,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2238,11 +2260,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.29.0",
+  "version": "3.30.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.29.0",
+    "version": "3.30.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

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

@@ -72,6 +72,7 @@ The `generated:issue-types` table below is regenerated from `fallow schema` by s
 | `untested-export` | `--coverage-gaps` | - | `// fallow-ignore-file coverage-gaps` | Runtime-reachable export has no test dependency path |
 | `code-duplication` | - | - | `// fallow-ignore-next-line code-duplication` | Duplicated code block; Reported by fallow dupes (and bare fallow / fallow audit) |
 | `feature-flag` | - | - | `// fallow-ignore-next-line feature-flag` | Detected feature flag pattern; Reported by fallow flags |
+| `flag-retirement-candidate` | - | - | - | Feature flag is a retirement candidate |
 | `tainted-sink` | - | - | `// fallow-ignore-next-line security-sink` | Syntactic security sink candidates require verification |
 | `client-server-leak` | - | - | `// fallow-ignore-file security-client-server-leak` | Client-bound code reaches a non-public env read |
 | `hardcoded-secret` | - | - | `// fallow-ignore-next-line security-sink` | Provider-prefixed or contextual secret literals require verification; Include-required category: enable via security.categories.include |

package/skills/fallow/references/mcp.md

@@ -36,7 +36,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `project_info` | introspection | free | `fallow list --files --entry-points --plugins --format json --quiet` | `entry_points`, `files`, `plugins`, `boundaries` | Project metadata. Set `entry_points`, `files`, `plugins`, or `boundaries` to `true` to request specific sections |
 | `recommend` | introspection | free | `fallow recommend --format json --quiet` | `root` | Recommend a project-tailored config from framework/workspace/tooling detection: a loader-validated proposed_config and three-valued auto/default/taste decisions for cold-start onboarding |
 | `list_boundaries` | introspection | free | `fallow list --boundaries --format json --quiet` | - | Architecture boundary zones, access rules, and pre-expansion `autoDiscover` `logical_groups[]` (user-authored parent name, verbatim paths, discovered children, `status` enum, summed `file_count`). Returns `{"configured": false}` if no boundaries configured |
-| `feature_flags` | analysis | free | `fallow flags --format json --quiet` | `workspace`, `production` | Detect feature flag patterns (env vars, SDK calls, config objects). Set `top` to limit results |
+| `feature_flags` | analysis | free | `fallow flags --format json --quiet` | `workspace`, `production` | Detect feature flag patterns (env vars, SDK calls, config objects). Set `top` to limit results. `retirement: true` adds the retirement rows; `flag_state` and `flag_age` tune them |
 | `list_suppressions` | analysis | free | `fallow suppressions --format json --quiet` | `workspace`, `changed_since`, `file` | List active fallow-ignore suppression markers grouped per file (line, kind, level, reason, and a stale cross-reference); a read-only governance inventory that always exits 0 |
 | `impact` | introspection | free | `fallow impact --format json --quiet` | `root` | Read the local, opt-in Fallow Impact value report (`fallow impact --format json`). Runs no analysis: current surfacing counts, trend since the last recorded run, pre-commit gate containment, and (on impact v1.5+) resolved/suppressed attribution. History is read from a per-project file in the user's private config dir (never inside the repo). Read-only and `root`-only; the mutating `enable` / `disable` / `default` lifecycle is not exposed. A never-enabled project returns a populated `{"enabled": false, ...}` report (never `{}`); branch on `enabled` and `enabled_source` (`project` / `user` / `default`) then `record_count`, recommending `fallow impact enable` only when `explicit_decision` is `false` (never asked) and staying silent when `true` (deliberately disabled here). Local-developer signal: fallow never records in CI, so empty there and not a CI metric |
 | `impact_all` | introspection | free | `fallow impact --all --format json --quiet` | `sort`, `limit` | Roll every tracked fallow project on this machine into one cross-repo value report (hashed keys plus basename labels, never paths; local-dev only) |

package/types/output-contract.d.ts

@@ -731,6 +731,15 @@ reason: string
 kind: "plugin-effect-not-modeled"
 } | {
 kind: "coverage-auto-detected"
+} | {
+kind: "flag-age-shallow-clone"
+} | {
+/**
+ * Why no history is available, as a kebab-case token:
+ * `not-a-repository` or `no-commits`. The set is open.
+ */
+cause: string
+kind: "flag-age-unavailable"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -905,6 +914,11 @@ export type RuntimeCoverageVerdict = ("safe_to_delete" | "review_required" | "co
  * Confidence level for a runtime coverage finding.
  */
 export type RuntimeCoverageConfidence = ("very_high" | "high" | "medium" | "low" | "none" | "unknown")
+/**
+ * The per-call cost that `optimization_target.cost_score` multiplies with
+ * `invocations`.
+ */
+export type RuntimeCoverageCostBasis = ("inner_iterations" | "cognitive")
 /**
  * Blast-radius risk band. The current thresholds are high at >=20 static
  * callers or >=1,000,000 traffic-weighted caller reach; medium at >=5 callers
@@ -1301,6 +1315,30 @@ export type FeatureFlagConfidence = ("high" | "medium" | "low")
  * Feature flag action discriminants.
  */
 export type FeatureFlagActionType = ("investigate-flag" | "suppress-line")
+/**
+ * How the report measures the age of a flag.
+ */
+export type FlagAgeMode = ("blame" | "pickaxe" | "off")
+/**
+ * How a retirement row's flag was detected.
+ */
+export type RetirementFlagKind = ("environment_variable" | "sdk_call" | "config_object" | "constant" | "vendor_export")
+/**
+ * What a site does with the flag.
+ */
+export type FlagSiteRole = ("read" | "definition")
+/**
+ * Why a flag is a retirement candidate.
+ */
+export type RetirementReason = ("single-read-site" | "test-only" | "literal-constant" | "identical-branches" | "empty-branch" | "guards-dead-code" | "defined-never-read" | "fully-rolled-out" | "archived-in-vendor" | "missing-in-vendor" | "vendor-only")
+/**
+ * Action discriminants for a retirement row.
+ */
+export type RetirementActionType = "review-retirement"
+/**
+ * State of a flag in a `--flag-state` vendor export.
+ */
+export type VendorFlagState = ("on" | "off" | "rolled_out" | "archived" | "experiment")
 /**
  * Independently-versioned wire-version newtype for the brief envelope.
  * Serializes as the integer `REVIEW_BRIEF_SCHEMA_VERSION`.
@@ -8362,6 +8400,48 @@ percentile: number
  * when empty.
  */
 actions?: RuntimeCoverageAction[]
+/**
+ * Per-call cost inputs and the speed-work score for this hot function.
+ * Omitted when the hot path has no `stable_id` or no static counterpart
+ * in this checkout.
+ */
+optimization_target?: (RuntimeCoverageOptimizationTarget | null)
+}
+/**
+ * Speed-work inputs for one hot function: how often it runs and how much
+ * work each call does. `importance` ranks the risk of a change; this block
+ * ranks where speed work gives the largest gain.
+ */
+export interface RuntimeCoverageOptimizationTarget {
+/**
+ * `invocations` multiplied by the per-call cost that `cost_basis` names.
+ * Uncapped integer. Compare it only between hot paths with the same
+ * `cost_basis`: sort by `cost_basis` first, then by `cost_score`
+ * descending. On the `cognitive` basis the per-call cost is at least 1.
+ */
+cost_score: number
+cost_basis: RuntimeCoverageCostBasis
+/**
+ * Static cognitive complexity of the function. A static proxy for the
+ * work per call, not a measurement.
+ */
+cognitive: number
+/**
+ * Static cyclomatic complexity of the function.
+ */
+cyclomatic: number
+/**
+ * Number of lines in the function body.
+ */
+line_count: number
+/**
+ * Peak executions of one block inside the function per call, from V8
+ * block coverage. `1.0` means no block ran more than once per call. A
+ * loop body that runs 3 times per call gives `3.0`. Calls to other
+ * functions do not change the value.
+ * Omitted when the coverage input has no block counts for the function.
+ */
+inner_iterations_per_call?: (number | null)
 }
 /**
  * One blast-radius entry in `runtime_coverage.blast_radius`: how far a
@@ -10925,6 +11005,13 @@ to: string
  * chain is a real compile-time coupling.
  */
 type_only: boolean
+/**
+ * Whether the edge carries a runtime value but no static one: the target
+ * loads only on demand (`import()`, a lazy glob or template pattern) or
+ * on another thread (a worker URL, `child_process.fork`). False for a
+ * static hop and for a type-only hop.
+ */
+dynamic: boolean
 /**
  * 1-based line in `from` of the imported binding that creates this edge:
  * the first value-carrying symbol on the import, or the first symbol when
@@ -14063,6 +14150,15 @@ total_flags: number
  * change.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
+/**
+ * One row per flag with the reasons the flag can be retired.
+ *
+ * Present only with `--retirement`. Without that option the key is
+ * omitted, so the envelope stays byte-identical and `schema_version`
+ * does not move. The per-site `feature_flags[]` array is the same with
+ * and without the option.
+ */
+retirement?: (FlagRetirementReport | null)
 /**
  * `_meta` block; see [`FeatureFlagsMeta`].
  */
@@ -14138,6 +14234,347 @@ dead_export_count: number
  */
 dead_exports: string[]
 }
+/**
+ * The `retirement` block of `fallow flags --retirement --format json`.
+ */
+export interface FlagRetirementReport {
+/**
+ * The analysis clock that ages count from, as an RFC 3339 UTC
+ * timestamp. `null` when the age mode is `off`, and also when no git
+ * history is available: outside a repository, on a branch without
+ * commits, or in a shallow clone. A `workspace_diagnostics` entry then
+ * gives the reason.
+ */
+generated_at_clock?: (string | null)
+age_mode: FlagAgeMode
+/**
+ * The vendor export that the report read. Present only with
+ * `--flag-state`.
+ */
+vendor_state?: (RetirementVendorState | null)
+summary: RetirementSummary
+/**
+ * Verdict of `--fail-on-regression` against a flags regression
+ * baseline. Present only when the gate ran.
+ */
+regression?: (FlagRegressionResult | null)
+/**
+ * Verdict of `--max-flag-age`. Present only with that option.
+ */
+max_flag_age?: (FlagAgeGate | null)
+/**
+ * One row per flag after the `--min-age`, `--reason`, `--sort` and
+ * `--top` options. A row with an empty `reasons` array is not a
+ * candidate.
+ */
+flags: RetirementFlag[]
+}
+/**
+ * The `--flag-state` vendor export that the report read.
+ */
+export interface RetirementVendorState {
+/**
+ * The vendor name from the export, for example `launchdarkly`.
+ */
+source: string
+/**
+ * When the export was made, as the export gives it.
+ */
+exported_at: string
+/**
+ * Days between `exported_at` and the analysis clock. `null` when the
+ * date cannot be read.
+ */
+export_age_days?: (number | null)
+/**
+ * Number of flags in the export.
+ */
+flags: number
+}
+/**
+ * Totals of the retirement report.
+ */
+export interface RetirementSummary {
+/**
+ * Distinct flags in the code in scope, before `--min-age` and
+ * `--reason`. The `vendor-only` rows of a `--flag-state` export do not
+ * count here, so the count does not change when a key is added in the
+ * vendor only. `by_reason` counts them.
+ */
+distinct_flags: number
+/**
+ * Rows in scope with at least one reason, `vendor-only` rows included.
+ */
+candidates: number
+/**
+ * Number of rows in scope per reason.
+ */
+by_reason: {
+[k: string]: number
+}
+}
+/**
+ * Verdict of the flags regression gate.
+ */
+export interface FlagRegressionResult {
+status: RegressionStatus
+/**
+ * The `--tolerance` value. Absent when the status is `skipped`.
+ */
+tolerance?: (number | null)
+/**
+ * How to read `tolerance`. Absent when the status is `skipped`.
+ */
+tolerance_kind?: (RegressionToleranceKind | null)
+/**
+ * The compared counts: `distinct_flags` first, then each `--reason`
+ * code. Empty when the status is `skipped`.
+ */
+metrics: FlagRegressionMetric[]
+/**
+ * Whether one count grew more than the tolerance.
+ */
+exceeded: boolean
+/**
+ * Why the gate did not run. Present only when the status is `skipped`.
+ */
+reason?: (string | null)
+}
+/**
+ * One count that the flags regression gate compares.
+ */
+export interface FlagRegressionMetric {
+/**
+ * `distinct_flags`, or a reason code from `--reason`.
+ */
+metric: string
+/**
+ * The count in the baseline.
+ */
+baseline: number
+/**
+ * The count in this run.
+ */
+current: number
+/**
+ * `current - baseline`.
+ */
+delta: number
+/**
+ * Whether the growth is more than the tolerance.
+ */
+exceeded: boolean
+}
+/**
+ * Verdict of `--max-flag-age`.
+ */
+export interface FlagAgeGate {
+status: RegressionStatus
+/**
+ * The `--max-flag-age` value in days.
+ */
+max_days: number
+/**
+ * Whether one flag in scope is older than `max_days`.
+ */
+exceeded: boolean
+/**
+ * Flags in the code in scope without a measured age. The gate cannot
+ * check these flags.
+ */
+unmeasured: number
+/**
+ * Why the gate did not run. Present only when the status is `skipped`.
+ */
+reason?: (string | null)
+/**
+ * The flags in scope that are older than `max_days`, oldest first.
+ * The `--reason`, `--min-age` and `--top` options do not change this
+ * list.
+ */
+flags: FlagAgeGateEntry[]
+}
+/**
+ * A flag that is older than `--max-flag-age`.
+ */
+export interface FlagAgeGateEntry {
+/**
+ * Flag identifier.
+ */
+flag_name: string
+kind: RetirementFlagKind
+/**
+ * Flag SDK, for SDK flags with a known provider.
+ */
+sdk_name?: (string | null)
+/**
+ * Workspace root of the flag, in a project with workspaces.
+ */
+workspace?: (string | null)
+/**
+ * Age of the flag in days.
+ */
+age_days: number
+}
+/**
+ * One flag in the retirement report.
+ */
+export interface RetirementFlag {
+/**
+ * Flag identifier.
+ */
+flag_name: string
+kind: RetirementFlagKind
+/**
+ * Flag SDK, for SDK flags with a known provider.
+ */
+sdk_name?: (string | null)
+/**
+ * Workspace root relative to the analysed root, when the project has
+ * workspaces and the flag is inside one. Part of the flag identity.
+ */
+workspace?: (string | null)
+/**
+ * Every site of the flag, sorted by path, line and column.
+ */
+sites: RetirementSite[]
+/**
+ * Number of sites in this row that read the flag.
+ */
+read_sites: number
+/**
+ * Whether every read site is in a test, story or mock file. Read sites
+ * of the same flag in other workspaces count too.
+ */
+test_only: boolean
+/**
+ * First commit that added the flag name. Set in `pickaxe` mode only.
+ */
+first_seen?: (FlagCommit | null)
+/**
+ * Oldest commit among the lines that still hold the flag.
+ */
+oldest_surviving_site?: (FlagCommit | null)
+/**
+ * Newest commit among the lines that still hold the flag.
+ */
+last_touched?: (FlagCommit | null)
+/**
+ * Days between the flag's oldest known commit and the analysis clock.
+ * In `blame` mode this is a lower bound.
+ */
+age_days?: (number | null)
+/**
+ * Retirement reasons, in report order. Empty for a flag that is not a
+ * candidate.
+ */
+reasons: RetirementReason[]
+/**
+ * Evidence for each reason.
+ */
+evidence: RetirementEvidence[]
+/**
+ * Follow-up actions. Empty for a flag that is not a candidate.
+ */
+actions: RetirementAction[]
+/**
+ * The vendor state of the flag. Present only with `--flag-state`, for
+ * a flag whose key is in the export.
+ */
+vendor?: (RetirementVendor | null)
+}
+/**
+ * One site of a flag in the retirement report.
+ */
+export interface RetirementSite {
+/**
+ * File path relative to the analysed root.
+ */
+path: string
+/**
+ * 1-based line.
+ */
+line: number
+/**
+ * 0-based byte column.
+ */
+col: number
+role: FlagSiteRole
+/**
+ * Whether the file is a test, story or mock file.
+ */
+in_test: boolean
+}
+/**
+ * A commit that git history links to a flag.
+ */
+export interface FlagCommit {
+/**
+ * Abbreviated commit hash.
+ */
+commit: string
+/**
+ * Commit date in UTC, as `YYYY-MM-DD`.
+ */
+date: string
+}
+/**
+ * One piece of evidence for a retirement reason.
+ */
+export interface RetirementEvidence {
+reason: RetirementReason
+/**
+ * File path relative to the analysed root. For `vendor-only`, the path
+ * of the `--flag-state` file: relative to the root when the file is
+ * inside it, else as given.
+ */
+path: string
+/**
+ * 1-based line.
+ */
+line: number
+/**
+ * What the evidence shows.
+ */
+detail: string
+}
+/**
+ * A follow-up action for a retirement candidate.
+ */
+export interface RetirementAction {
+type: RetirementActionType
+/**
+ * Always `false`: Fallow never removes a flag.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable action description.
+ */
+description: string
+}
+/**
+ * The vendor state of one flag in the retirement report.
+ */
+export interface RetirementVendor {
+/**
+ * The key in the vendor export, before `flags.vendorKeyPrefix` is
+ * removed.
+ */
+key: string
+state: VendorFlagState
+/**
+ * Whether the flag serves one variation, when the export says so.
+ */
+serves_single_variation?: (boolean | null)
+/**
+ * When the vendor created the flag, as the export gives it.
+ */
+created_at?: (string | null)
+/**
+ * When the vendor last evaluated the flag, as the export gives it.
+ */
+last_evaluated_at?: (string | null)
+}
 /**
  * Optional `_meta` block for [`FeatureFlagsOutput`]. Both fields are optional
  * because the two contributors are independent: `feature_flags` details are