fallow 3.21.0 → 3.23.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -906,6 +906,11 @@
       "description": "Inspect the optional TypeScript semantic companion",
       "flags": []
     },
+    {
+      "name": "doctor",
+      "description": "Diagnose project readiness without analysis or mutation",
+      "flags": []
+    },
     {
       "name": "similar-code",
       "description": "Find semantically similar functions with a pinned local model (opt-in)",
@@ -6004,10 +6009,11 @@
     "FALLOW_CACHE_DIR": "Directory for fallow's persistent analysis cache. Relative paths resolve from the project root and override cache.dir.",
     "FALLOW_CACHE_MAX_SIZE": "Extraction cache size cap in megabytes (default 256). Wins over the cache.maxSizeMb config field.",
     "FALLOW_EXTENDS_TIMEOUT_SECS": "Timeout in seconds for fetching https:// configs referenced via the extends field (default 5).",
-    "FALLOW_COVERAGE": "Path to Istanbul coverage data (coverage-final.json) for accurate per-function CRAP scores. CLI --coverage flag overrides this; it wins over the health.coverage config field. Honored by the health, bare fallow, and audit CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage parameter overrides it.",
-    "FALLOW_COVERAGE_ROOT": "Absolute coverage-data path prefix for rebasing Istanbul paths in CI or containers. CLI --coverage-root flag overrides this; it wins over the health.coverageRoot config field. Honored by the health, bare fallow, and audit CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage_root parameter overrides it.",
+    "FALLOW_COVERAGE": "Path to Istanbul coverage data (coverage-final.json) for accurate per-function CRAP scores. CLI --coverage flag overrides this; it wins over the health.coverage config field. Honored by the health, bare fallow, audit, and viz CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage parameter overrides it. Viz reads it through the same precedence and has no coverage flag of its own.",
+    "FALLOW_COVERAGE_ROOT": "Absolute coverage-data path prefix for rebasing Istanbul paths in CI or containers. CLI --coverage-root flag overrides this; it wins over the health.coverageRoot config field. Honored by the health, bare fallow, audit, and viz CLI commands and by the MCP audit and check_health tools on both their typed route and their CLI fallback, where the explicit coverage_root parameter overrides it. Viz reads it through the same precedence and has no coverage flag of its own.",
     "FALLOW_MAX_FILE_SIZE": "Per-file size ceiling in megabytes for source discovery (default 5; 0 = no limit). CLI --max-file-size flag overrides this.",
     "FALLOW_TYPE_AWARE": "Enable or disable TypeScript semantic (type-aware) analysis for the run (true/false/1/0/yes/no/on/off). Precedence: --type-aware/--no-type-aware CLI flags, then FALLOW_TYPE_AWARE, then the audit.typeAware config field, then typeAware.enabled.",
+    "FALLOW_TYPE_AWARE_TIMEOUT_SECS": "Wall clock in seconds allowed for one TypeScript semantic sidecar request (default 120; unset, 0, or a non-numeric value keeps the default). Raise it for very large TypeScript programs, where a semantic query scans the whole program.",
     "FALLOW_TYPE_AWARE_BIN": "Trusted executable override for the TypeScript semantic refinement sidecar used by dead-code --type-aware. Relative paths resolve from the caller's working directory before --root is applied; project node_modules and PATH are intentionally not searched. Default: sibling of the active Fallow executable.",
     "FALLOW_AUDIT_BASE": "Pins the fallow audit comparison base ref when no --base/--changed-since is passed (e.g. upstream/main).",
     "FALLOW_AUDIT_CACHE_MAX_AGE_DAYS": "GC threshold in days for reusable audit base-snapshot caches (default 30; 0 disables the sweep).",
@@ -6524,7 +6530,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "analyze",
@@ -6541,7 +6548,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "analyze"
       },
       {
         "name": "check_changed",
@@ -6555,7 +6563,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "checkChanged"
       },
       {
         "name": "security_candidates",
@@ -6570,7 +6579,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "securityCandidates"
       },
       {
         "name": "find_similar_code",
@@ -6586,7 +6596,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "inspect_similar_code",
@@ -6599,7 +6610,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "inspect_target",
@@ -6613,7 +6625,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "guard",
@@ -6625,7 +6638,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "find_dupes",
@@ -6642,7 +6656,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "findDupes"
       },
       {
         "name": "check_health",
@@ -6662,7 +6677,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "checkHealth"
       },
       {
         "name": "check_runtime_coverage",
@@ -6678,7 +6694,8 @@
         ],
         "license": "freemium",
         "license_note": "A single local runtime-coverage capture is free; continuous or multi-capture runtime monitoring requires an active license (fallow license activate).",
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "checkRuntimeCoverage"
       },
       {
         "name": "get_hot_paths",
@@ -6692,7 +6709,8 @@
         ],
         "license": "freemium",
         "license_note": "A single local runtime-coverage capture is free; continuous or multi-capture runtime monitoring requires an active license (fallow license activate).",
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "getHotPaths"
       },
       {
         "name": "get_blast_radius",
@@ -6705,7 +6723,8 @@
         ],
         "license": "freemium",
         "license_note": "A single local runtime-coverage capture is free; continuous or multi-capture runtime monitoring requires an active license (fallow license activate).",
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "getBlastRadius"
       },
       {
         "name": "get_importance",
@@ -6718,7 +6737,8 @@
         ],
         "license": "freemium",
         "license_note": "A single local runtime-coverage capture is free; continuous or multi-capture runtime monitoring requires an active license (fallow license activate).",
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "getImportance"
       },
       {
         "name": "get_cleanup_candidates",
@@ -6731,7 +6751,8 @@
         ],
         "license": "freemium",
         "license_note": "A single local runtime-coverage capture is free; continuous or multi-capture runtime monitoring requires an active license (fallow license activate).",
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "getCleanupCandidates"
       },
       {
         "name": "get_token_blast_radius",
@@ -6741,7 +6762,8 @@
         "key_params": [],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "audit",
@@ -6758,7 +6780,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "audit"
       },
       {
         "name": "decision_surface",
@@ -6772,7 +6795,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "fallow_explain",
@@ -6784,7 +6808,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "explain"
       },
       {
         "name": "fix_preview",
@@ -6796,7 +6821,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "fix_apply",
@@ -6808,7 +6834,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": false
+        "read_only": false,
+        "code_mode_alias": null
       },
       {
         "name": "project_info",
@@ -6823,7 +6850,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "projectInfo"
       },
       {
         "name": "recommend",
@@ -6835,7 +6863,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "list_boundaries",
@@ -6845,7 +6874,8 @@
         "key_params": [],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "listBoundaries"
       },
       {
         "name": "feature_flags",
@@ -6858,7 +6888,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "featureFlags"
       },
       {
         "name": "list_suppressions",
@@ -6872,7 +6903,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "impact",
@@ -6884,7 +6916,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "impact"
       },
       {
         "name": "impact_all",
@@ -6897,7 +6930,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "trace_export",
@@ -6910,7 +6944,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "traceExport"
       },
       {
         "name": "trace_symbol",
@@ -6925,7 +6960,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "symbol_impact",
@@ -6942,7 +6978,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": null
       },
       {
         "name": "trace_file",
@@ -6954,7 +6991,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "traceFile"
       },
       {
         "name": "impact_closure",
@@ -6966,7 +7004,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "impactClosure"
       },
       {
         "name": "trace_dependency",
@@ -6978,7 +7017,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "traceDependency"
       },
       {
         "name": "trace_clone",
@@ -6994,7 +7034,8 @@
         ],
         "license": "free",
         "license_note": null,
-        "read_only": true
+        "read_only": true,
+        "code_mode_alias": "traceClone"
       }
     ]
   },
@@ -7069,7 +7110,7 @@
     ]
   },
   "plugins": {
-    "count": 124,
+    "count": 125,
     "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",
@@ -7195,7 +7236,8 @@
       "wuchale",
       "varlock",
       "pnpm",
-      "bun"
+      "bun",
+      "deno"
     ]
   },
   "task_matrix": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.21.0",
+  "version": "3.23.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.3.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.21.0",
-    "@fallow-cli/darwin-x64": "3.21.0",
-    "@fallow-cli/linux-x64-gnu": "3.21.0",
-    "@fallow-cli/linux-arm64-gnu": "3.21.0",
-    "@fallow-cli/linux-x64-musl": "3.21.0",
-    "@fallow-cli/linux-arm64-musl": "3.21.0",
-    "@fallow-cli/win32-arm64-msvc": "3.21.0",
-    "@fallow-cli/win32-x64-msvc": "3.21.0",
-    "fallow-type-aware": "3.21.0"
+    "@fallow-cli/darwin-arm64": "3.23.0",
+    "@fallow-cli/darwin-x64": "3.23.0",
+    "@fallow-cli/linux-x64-gnu": "3.23.0",
+    "@fallow-cli/linux-arm64-gnu": "3.23.0",
+    "@fallow-cli/linux-x64-musl": "3.23.0",
+    "@fallow-cli/linux-arm64-musl": "3.23.0",
+    "@fallow-cli/win32-arm64-msvc": "3.23.0",
+    "@fallow-cli/win32-x64-msvc": "3.23.0",
+    "fallow-type-aware": "3.23.0"
   }
 }

package/schema.json

@@ -12,6 +12,13 @@
       ],
       "writeOnly": true
     },
+    "minimumVersion": {
+      "description": "The lowest fallow version this config is written for, as `MAJOR.MINOR.PATCH`. An older binary stops with a message naming both versions instead of failing on the first field it does not recognize, so a config committed to a shared repository says which upgrade it needs rather than reading like a typo. Optional and unset by default; set it in the same change that adds a field introduced in a newer version. It gates nothing on its own: an unknown key still fails on a binary at or above this version, because there the key really is a typo.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
     "extends": {
       "description": "An ordered array of parent config sources to inherit before this file's own keys apply; each entry is a file-relative path, an `npm:<package>` specifier, or an `https://` URL (`http://` is rejected), deep-merged in order so objects merge field-by-field while arrays and scalars in this file replace the parent's, with cycle and depth guards. Set it to share a base config across a monorepo or team; it is consumed at load and stripped before serialization (serde skip_serializing).",
       "type": "array",
@@ -898,7 +905,7 @@
           "type": "array",
           "items": {
             "type": "string",
-            "pattern": "^dup:(?:[0-9a-f]{8}|[0-9a-f]{16}(?:-[1-9][0-9]*)?):(?:[2-9]|[1-9][0-9]+)$"
+            "pattern": "^dup:(?:[0-9a-f]{8}|[0-9a-f]{16}(?:-r?[1-9][0-9]*)?):(?:[2-9]|[1-9][0-9]+)$"
           },
           "default": []
         },
@@ -1067,7 +1074,7 @@
           "default": 60
         },
         "coverage": {
-          "description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\nand the MCP `audit` / `check_health` tools.",
+          "description": "Path to Istanbul-format coverage data for accurate per-function CRAP\nscores. Relative paths resolve against the project root. The CLI\n`--coverage` flag and `FALLOW_COVERAGE` environment variable override\nthis value. Consulted by `fallow health`, bare `fallow`, `fallow audit`,\n`fallow viz`, and the MCP `audit` / `check_health` tools.",
           "type": [
             "string",
             "null"
@@ -1075,7 +1082,7 @@
           "default": null
         },
         "coverageRoot": {
-          "description": "Absolute prefix to strip from Istanbul file paths before CRAP matching.\nUse when coverage was generated under a different checkout root in CI\nor Docker. The CLI `--coverage-root` flag and `FALLOW_COVERAGE_ROOT`\nenvironment variable override this value. Consulted by `fallow health`,\nbare `fallow`, `fallow audit`, and the MCP `audit` / `check_health`\ntools.",
+          "description": "Absolute prefix to strip from Istanbul file paths before CRAP matching.\nUse when coverage was generated under a different checkout root in CI\nor Docker. The CLI `--coverage-root` flag and `FALLOW_COVERAGE_ROOT`\nenvironment variable override this value. Consulted by `fallow health`,\nbare `fallow`, `fallow audit`, `fallow viz`, and the MCP `audit` /\n`check_health` tools.",
           "type": [
             "string",
             "null"
@@ -1132,7 +1139,7 @@
           }
         },
         "functions": {
-          "description": "Exact emitted function names this override applies to. Empty means every\nfunction in matching files.",
+          "description": "Exact emitted function names this override applies to. Empty means every\nfunction in matching files. Synthetic units are matched by their emitted\nname, so `\"<template>\"` and `\"<snippet:NAME>\"` are valid keys. The\nsynthetic `\"<module>\"` unit is not: it carries a file's module-scope\ndecision points into the aggregate metrics and never produces a finding,\nso there is no ceiling for an override to move.",
           "type": "array",
           "items": {
             "type": "string"

package/skills/fallow/SKILL.md

@@ -87,6 +87,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `dead-code` | Dead code analysis (`check` is an alias) | `--unused-exports`, `--changed-since`, `--changed-workspaces`, `--production`, `--file`, `--include-entry-exports`, `--stale-suppressions`, `--ci`, `--group-by`, `--summary`, `--fail-on-regression`, `--tolerance`, `--regression-baseline`, `--save-regression-baseline` |
 | `watch` | Watch for changes and re-run analysis | `--no-clear` |
 | `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` |
 | `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` |
@@ -125,7 +126,7 @@ Route by intent before reaching for the big analysis commands. Same matrix as `f
 | `coverage` | Runtime coverage setup, focused analysis, and cloud inventory workflow helper | `setup`, `setup --yes`, `setup --non-interactive`, `analyze --runtime-coverage <path>`, `analyze --cloud --repo owner/repo`, `upload-inventory` |
 | `coverage upload-source-maps` | Upload build source maps from CI so bundled runtime coverage resolves to original source paths. Retries 429 `Retry-After` and transient gateway failures. Use `FALLOW_CA_BUNDLE` for complete custom PEM trust bundles. | `--dir dist`, `--git-sha <sha>`, `--repo <name>`, `--strip-path=false`, `--dry-run` |
 | `setup-hooks` | Deprecated (removed in the next major): use `agent install` or `hooks install --target agent`; still installs the Claude Code PreToolUse gate with a stderr warning | `--agent`, `--dry-run`, `--force`, `--user`, `--gitignore-claude`, `--uninstall` |
-| `viz` | Render the codebase as a self-contained interactive HTML map (treemap + import graph, four lenses: dead code, duplication, boundaries, complexity, with click-through detail panels), or emit the import graph as text. Read-only. | `--out <path>`, `--no-open`, `--viz-format html\|dot\|mermaid`, `--root`, `--config`, `--production`, `--no-cache` |
+| `viz` | Render the codebase as a self-contained interactive HTML map (treemap + import graph) with six primary lenses (Overview, Unused, Duplication, Architecture, Health, Security) and Dependencies, Frameworks, Styling, and Feature flags under an adaptive More menu, each with click-through detail panels. Every lens carries an availability state (complete, disabled, not applicable, unavailable) next to its count, so an analysis that did not run reads as missing data instead of as zero findings. Or emit the import graph as text. Read-only. | `--out <path>`, `--no-open`, `--viz-format html\|dot\|mermaid`, `--root`, `--config`, `--production`, `--no-cache` |
 
 Run `fallow <command> --help` for the full flag list per command (see also references/cli-reference.md).
 <!-- generated:commands:end -->

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

@@ -385,7 +385,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.20.0",
+  "fallow_version": "3.23.0",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -589,7 +589,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -987,7 +987,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1064,7 +1064,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1165,7 +1165,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1194,7 +1194,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1959,7 +1959,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2119,7 +2119,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2163,11 +2163,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.21.0",
+  "version": "3.23.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.21.0",
+    "version": "3.23.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/mcp.md

@@ -11,7 +11,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 <!-- generated:mcp-tools:start -->
 | Tool | Kind | License | CLI fallback | Key params | Description |
 |---|---|---|---|---|---|
-| `code_execute` | composition | free | - | `code`, `timeout_ms`, `max_output_bytes` | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. Similar-code is excluded because Code Mode is capped at 30 seconds; use standalone `find_similar_code` and `inspect_similar_code`, which have dedicated 15-minute timeouts. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, `eval`, `Function`, `process`, `require`, `Deno`, `Bun`, or shell access. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000). |
+| `code_execute` | composition | free | - | `code`, `timeout_ms`, `max_output_bytes` | Bounded read-only Code Mode for composing multiple fallow analysis calls in one JavaScript snippet. The snippet receives `{ fallow, root }`, returns JSON-serializable data, and can call read-only helpers such as `fallow.projectInfo`, `fallow.audit`, `fallow.checkHealth`, and `fallow.run(tool, params)` for the same allowlist. `fallow.all(requests)` fans out independent calls in one go: pass `[{ tool, params }, ...]` and get back a positionally aligned array of `{ ok: true, value }` or `{ ok: false, error }`, so one failing element never hides the rest. Host calls are memoized for the duration of one snippet, so repeating the same tool with the same params (key order does not matter) is served from cache, spends no `max_host_calls` slot and no output budget, and is reported in `calls[]` with `cache_hit: true`; a call refused before dispatch (unknown tool, malformed params) spends no slot either, and `limits.max_rejected_host_calls` bounds how many of those the response records. Similar-code is excluded because Code Mode is capped at 30 seconds; use standalone `find_similar_code` and `inspect_similar_code`, which have dedicated 15-minute timeouts. Mutating fix tools are not exposed. The sandbox has no filesystem, network, imports, `process`, `require`, `Deno`, `Bun`, or shell access, and no dynamic code compilation: `eval`, `Function`, and the async and generator function constructors are removed, including the `constructor` route reachable through function prototypes. Params: `code`, optional `root`, `timeout_ms` (capped at 30000), and `max_output_bytes` (capped at 4000000). `max_output_bytes` bounds two separate things: the total fallow JSON host calls read, shared across a `fallow.all` fan-out rather than granted per element, and the serialized snippet result. An oversized result is refused with `ok:false`, `truncated:true`, `result_bytes`, and a short `result_preview` in place of the value, never returned whole, so return a projection rather than a whole report. |
 | `analyze` | analysis | free | `fallow dead-code --format json --quiet` | `issue_types`, `production`, `workspace`, `baseline`, `group_by`, `file` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + rule-pack policy violations (banned calls, imports, and catalogue-derived effects declared via the `rulePacks` config key) + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | analysis | free | `fallow dead-code --changed-since <ref> --format json --quiet` | `since`, `baseline`, `fail_on_regression` | Incremental analysis of files changed since a git ref |
 | `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://docs.fallow.tools/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. |

package/types/output-contract.d.ts

@@ -24,7 +24,7 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`, `type-aware-status`, `similar-code`, `similar-code-inspect`, `similar-code-review`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`, `doctor`, `type-aware-status`, `similar-code`, `similar-code-inspect`, `similar-code-review`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field.
  */
 export type FallowJsonOutput = (FallowOutput | CodeClimateOutput | ErrorOutput)
 /**
@@ -96,6 +96,8 @@ kind: "review-walkthrough-guide"
 kind: "review-walkthrough-validation"
 }) | (SuppressionInventoryOutput & {
 kind: "suppression-inventory"
+}) | (DoctorOutput & {
+kind: "doctor"
 }) | (TypeAwareStatusOutput & {
 kind: "type-aware-status"
 }) | (SimilarCodeOutput & {
@@ -1026,6 +1028,10 @@ export type ConfidenceFlag = ("dynamic-dispatch" | "re-export-indirection")
  * The category of a single weakening signal.
  */
 export type WeakeningKind = ("test-weakened" | "threshold-lowered" | "suppression-added" | "security-check-removed")
+/**
+ * Where a cognitive-complexity improvement came from.
+ */
+export type CognitiveAttribution = ("nesting-reset" | "fewer-branch-points" | "mixed")
 /**
  * Independently-versioned wire-version newtype. Serializes as the integer
  * [`DECISION_SURFACE_SCHEMA_VERSION`].
@@ -1055,6 +1061,30 @@ export type SuppressionInventoryLevel = ("file" | "line")
  * How a suppression in the inventory was authored.
  */
 export type SuppressionInventoryOrigin = "comment"
+/**
+ * Schema projection for the exact doctor envelope version.
+ */
+export type DoctorSchemaVersion = 1
+/**
+ * Schema projection for `.` as the privacy-safe diagnosed project root.
+ */
+export type DoctorProjectRoot = "."
+/**
+ * Aggregate readiness outcome.
+ */
+export type DoctorStatus = ("pass" | "warn" | "fail")
+/**
+ * Stable identifier for a doctor check. Declaration order is output order.
+ */
+export type DoctorCheckId = ("root" | "config" | "workspaces" | "plugins" | "type-aware")
+/**
+ * Stable category for a doctor check.
+ */
+export type DoctorCheckCategory = ("project" | "configuration" | "workspace" | "plugin" | "companion")
+/**
+ * Per-check readiness outcome.
+ */
+export type DoctorCheckStatus = ("pass" | "warn" | "fail" | "skipped")
 /**
  * Schema projection for the type-aware status envelope's exact version.
  */
@@ -5698,7 +5728,13 @@ export interface HealthSummary {
  */
 files_analyzed: number
 /**
- * Functions scored across the analyzed files.
+ * Real functions scored across the analyzed files. This counts functions
+ * only, so it is smaller than the sum of `file_scores[].function_count`,
+ * which also counts the synthetic per-file units (`<module>` for
+ * module-scope branching, `<template>` and `<snippet:NAME>` for component
+ * templates). The complexity aggregates below, including
+ * `average_cyclomatic` and `p90_cyclomatic`, are computed over that larger
+ * population rather than over this count.
  */
 functions_analyzed: number
 /**
@@ -12361,6 +12397,11 @@ duplication?: (DupesReportPayload | null)
  * Complexity findings scoped to the audit changeset.
  */
 complexity?: (HealthReport | null)
+/**
+ * Branching conservation across the changeset. Absent when no base
+ * comparison ran.
+ */
+branching?: (BranchingReport | null)
 }
 /**
  * The ranked, capped decision surface plus the set of signal_ids the
@@ -12776,6 +12817,200 @@ expert: string[]
  */
 bus_factor_one?: boolean
 }
+/**
+ * The brief's branching section.
+ */
+export interface BranchingReport {
+/**
+ * Files carrying the split signature: branching within `tolerance` of
+ * where it was, more functions, a smaller largest function. Empty when
+ * none do, which is the common case and is not itself a finding. See
+ * `SplitInPlace` for why this describes a shape rather than asserting a
+ * refactor.
+ */
+split_in_place: SplitInPlace[]
+/**
+ * The band inside which a file's branching counts as held. Published
+ * because a claim against an unpublished threshold is not reproducible by
+ * a consumer.
+ */
+tolerance: number
+scope: BranchingScope
+branch_points: BranchingMetric
+functions: BranchingMetric
+peak_unit_cyclomatic: BranchingMetric
+/**
+ * Base-side branch points of the files that have no head entry.
+ */
+branch_points_only_in_base: number
+cognitive: BranchingCognitive
+/**
+ * The files that moved the numbers most, largest absolute branch-point
+ * change first.
+ */
+by_file: BranchingFileDelta[]
+/**
+ * Files with a change that the list did not name.
+ */
+by_file_omitted: number
+}
+/**
+ * One file present on both revisions whose branching held while it gained
+ * functions and its largest function shrank.
+ *
+ * Local by construction: nothing here depends on any other file, so unrelated
+ * work in the changeset cannot make it more or less true. A set-level
+ * classifier cannot make this claim, because a changeset contains arbitrary
+ * other work and an aggregate cannot attribute.
+ *
+ * It is a description, not an inference. The three conditions are the
+ * signature a split leaves, and they are also satisfiable without one: the
+ * peak is a file-level maximum (`FileBranching::peak_cyclomatic`), so it can
+ * fall because the largest function left the file while arriving helpers
+ * happen to carry the branching it took with it. Both numbers are reported so
+ * a reader can see that for themselves, and the rendered text states what was
+ * measured rather than concluding a refactor happened.
+ *
+ * Files carrying synthetic template units are excluded, because those units
+ * are outside every count here, so the numbers would not describe the file a
+ * reader opens. Test paths are excluded too: their totals are reported in
+ * `BranchingScope` instead.
+ */
+export interface SplitInPlace {
+/**
+ * Root-relative path.
+ */
+path: string
+/**
+ * Branch points on the base revision.
+ */
+branch_points_before: number
+/**
+ * And on head. Within `tolerance` of `branch_points_before`, which is what
+ * "held" means here. Both are reported because one number alone cannot be
+ * checked.
+ */
+branch_points_after: number
+/**
+ * Accounted functions before the split.
+ */
+functions_before: number
+/**
+ * Accounted functions after it.
+ */
+functions_after: number
+/**
+ * Highest single-function cyclomatic score before.
+ */
+peak_before: number
+/**
+ * And after. It falls by construction when a function is split, which is
+ * why it is evidence here and never a metric to celebrate.
+ */
+peak_after: number
+}
+/**
+ * Size and composition of the compared set.
+ */
+export interface BranchingScope {
+/**
+ * Files carrying units on both revisions.
+ */
+files_both: number
+/**
+ * Files carrying units on the head revision only.
+ */
+files_added: number
+/**
+ * Files that carried units on the base revision only, whether they were
+ * deleted or merely lost every accounted unit. Reported, and excluded from
+ * every headline number: such a file contributes its whole base-side total
+ * as a fall with no head counterpart.
+ */
+files_only_in_base: number
+/**
+ * Branch points on test-shaped paths within the head totals. Test code
+ * routinely dominates both terms, so a reader needs to see its share
+ * before reading the headline.
+ */
+test_branch_points: number
+/**
+ * Functions on test-shaped paths within the head totals.
+ */
+test_functions: number
+/**
+ * Share of head branch points owned by the single largest file, so a
+ * reader can see when one vendored or generated file owns the number.
+ */
+largest_file_share_of_branch_points: number
+}
+/**
+ * One metric across the two revisions.
+ */
+export interface BranchingMetric {
+/**
+ * Value on the base revision.
+ */
+previous: number
+/**
+ * Value on the head revision.
+ */
+current: number
+/**
+ * `current - previous`. Signed, so a consumer never has to infer direction
+ * from a separate field.
+ */
+delta: number
+}
+/**
+ * The cognitive figure and what drove it.
+ *
+ * `previous` and `current` exclude prop-count and hook-density increments.
+ * Both are cognitive-only, and prop count records an excess over a floor, so
+ * it is superlinear in a split and would move this number with branching and
+ * nesting both flat. This therefore does not match the cognitive score the
+ * complexity findings report.
+ */
+export interface BranchingCognitive {
+/**
+ * Cognitive weight on the base revision.
+ */
+previous: number
+/**
+ * Cognitive weight on the head revision.
+ */
+current: number
+/**
+ * `current - previous`.
+ */
+delta: number
+/**
+ * Change in the summed nesting depth behind those increments.
+ */
+nesting_weight_delta: number
+/**
+ * What the improvement is attributable to, absent when cognitive did not
+ * fall. There is nothing to attribute when the number rose or held.
+ */
+attributed_to?: (CognitiveAttribution | null)
+}
+/**
+ * One file's contribution to the change.
+ */
+export interface BranchingFileDelta {
+/**
+ * Root-relative path.
+ */
+path: string
+/**
+ * Change in branch points for this file.
+ */
+branch_points_delta: number
+/**
+ * Change in accounted functions for this file.
+ */
+functions_delta: number
+}
 /**
  * The separable `decision-surface` envelope: the single call that puts taste-
  * decisions in front of a human, callable WITHOUT the full pipeline (the
@@ -12962,6 +13197,13 @@ deltas: ReviewDeltas
 weakening: WeakeningSignal[]
 routing: RoutingFacts
 decisions: DecisionSurface
+/**
+ * Branching conservation across the changeset: total branching against
+ * the number of functions now holding it. Absent when no base comparison
+ * ran, which keeps the wire shape byte-identical for a consumer that
+ * never had a base snapshot.
+ */
+branching?: (BranchingReport | null)
 }
 /**
  * The review direction artifact: the order to review in, the coherent units,
@@ -13300,6 +13542,75 @@ reason?: (string | null)
  */
 reason_present: boolean
 }
+/**
+ * Versioned readiness envelope emitted by `fallow doctor --format json`.
+ */
+export interface DoctorOutput {
+schema_version: DoctorSchemaVersion
+version: ToolVersion
+root: DoctorProjectRoot
+status: DoctorStatus
+summary: DoctorSummary
+/**
+ * Checks in stable contract order.
+ */
+checks: DoctorCheck[]
+}
+/**
+ * Counts for every per-check status.
+ */
+export interface DoctorSummary {
+/**
+ * Successful checks.
+ */
+pass: number
+/**
+ * Advisory checks.
+ */
+warn: number
+/**
+ * Failed checks.
+ */
+fail: number
+/**
+ * Inapplicable or prerequisite-blocked checks.
+ */
+skipped: number
+}
+/**
+ * One deterministic doctor check result.
+ */
+export interface DoctorCheck {
+id: DoctorCheckId
+category: DoctorCheckCategory
+status: DoctorCheckStatus
+/**
+ * Whether failure makes the project not ready.
+ */
+required: boolean
+/**
+ * Human-readable result with no host-specific absolute paths.
+ */
+message: string
+/**
+ * Optional actionable next command.
+ */
+remediation?: (DoctorRemediation | null)
+}
+/**
+ * Actionable remediation attached to a doctor check.
+ */
+export interface DoctorRemediation {
+/**
+ * Command the user or agent can choose to run.
+ */
+command: string
+cwd: DoctorProjectRoot
+/**
+ * Whether running the command can modify project files or dependencies.
+ */
+mutating: boolean
+}
 /**
  * Envelope emitted by `fallow type-aware status --format json`.
  */
@@ -13905,6 +14216,12 @@ severity: CodeClimateSeverity
  */
 fingerprint: string
 location: CodeClimateLocation
+/**
+ * Other source locations that provide evidence for the finding. GitLab's
+ * Code Quality widget ignores this standard CodeClimate field, but Fallow
+ * preserves it for review-comment rendering.
+ */
+other_locations?: CodeClimateLocation[]
 /**
  * Optional owner attribution used by grouped dead-code output.
  */
@@ -13926,13 +14243,17 @@ path: string
 lines: CodeClimateLines
 }
 /**
- * `lines.begin` for [`CodeClimateLocation`].
+ * Inclusive line range for [`CodeClimateLocation`].
  */
 export interface CodeClimateLines {
 /**
  * 1-based start line.
  */
 begin: number
+/**
+ * Inclusive 1-based end line. Omitted for point findings.
+ */
+end?: (number | null)
 }
 /**
  * Structured JSON error emitted on stdout when `--format json` is active and a