fallow 3.24.0 → 3.25.0

package/capabilities.json

@@ -1,9 +1,15 @@
 {
   "name": "fallow",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
+    {
+      "name": "path",
+      "type": "string",
+      "required": false,
+      "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
+    },
     {
       "name": "--root",
       "type": "string",
@@ -882,6 +888,12 @@
           "type": "string",
           "required": false,
           "description": "Only report issues in the specified file(s). Accepts multiple values. The full project graph is still built, but only issues in matching files are reported. Useful for lint-staged pre-commit hooks"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -938,6 +950,12 @@
           "type": "string",
           "required": false,
           "description": "Report pairs touching one of these project-relative files"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -1068,6 +1086,12 @@
             "true",
             "false"
           ]
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed. Only fixes touching scoped files are planned and applied"
         }
       ]
     },
@@ -1249,6 +1273,12 @@
             "true",
             "false"
           ]
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -1368,6 +1398,12 @@
           "type": "string",
           "required": false,
           "description": "Trace all clones at a specific location (format: `FILE:LINE`)"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -1626,6 +1662,12 @@
           "type": "string",
           "required": false,
           "description": "Fraction of total trace count below which an invoked function is classified as `low_traffic` rather than `active`. Expressed as a decimal (e.g. `0.001` for 0.1%). Omit to use the sidecar's spec default (0.001)"
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -1857,11 +1899,17 @@
           "name": "--show-deprioritized",
           "type": "bool",
           "required": false,
-          "description": "Expand the de-prioritized units in the review brief's weighted focus map (\"show me what you de-prioritized\"). The `deprioritized` escape-hatch list is ALWAYS present in `--format json` regardless; this flag only re-expands the collapse-by-default human focus render. Only consulted on the brief path",
+          "description": "Expand the de-prioritized units in the review brief's weighted focus map (\"show me what you de-prioritized\"). The `deprioritized` escape-hatch list is ALWAYS present in `--format json` regardless; this flag only re-expands the collapse-by-default human focus render. Only consulted on the `--walkthrough` path",
           "possible_values": [
             "true",
             "false"
           ]
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },
@@ -1960,6 +2008,12 @@
             "true",
             "false"
           ]
+        },
+        {
+          "name": "path",
+          "type": "string",
+          "required": false,
+          "description": "Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed"
         }
       ]
     },

package/package.json

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

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

@@ -446,7 +446,7 @@ Human output groups paths under "Shared with your team (commit these)" and "Loca
 {
   "kind": "agent-install",
   "schema_version": 1,
-  "fallow_version": "3.24.0",
+  "fallow_version": "3.24.1",
   "root": "/abs/path",
   "mode": "install",
   "dry_run": false,
@@ -650,7 +650,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1053,7 +1053,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -1130,7 +1130,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1231,7 +1231,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1260,7 +1260,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1709,6 +1709,8 @@ Cloud analysis emits the same `runtime_coverage` JSON block as local mode. Its s
 
 Each finding's `actions[].type` uses the canonical kebab-case vocabulary: `delete-cold-code` is emitted on `verdict=safe_to_delete`, `review-runtime` on `verdict=review_required`. The sidecar may emit additional protocol-specific identifiers, so consumers should treat unknown values as forward-compat extensions rather than schema violations.
 
+Under `--production` the evidence block also carries `test_only_reference`. It is `true` when the function is unreachable in the production module graph but still referenced from a file production mode excludes (test, spec, story, fixture, benchmark). Such a function is never `safe_to_delete`: it is reported as `review_required` with the action "Only tests reference this export; delete the test usage together with the function or keep it". The field is absent when no production filter was applied, because there is no second reachability answer to report.
+
 ### `upload-inventory` flags
 
 | Flag | Type | Default | Description |
@@ -1806,6 +1808,7 @@ Available on all commands:
 <!-- generated:flags:global:start -->
 | Flag | Type | Default | Description |
 |---|---|---|---|
+| `path` | `string` | - | Scope reported findings to this file or directory (default: whole project). The full project graph is still built; only reported items are narrowed |
 | `-r, --root` | `string` | - | Project root directory |
 | `-c, --config` | `string` | - | Config file path |
 | `--allow-remote-extends` | `bool` | `false` | Allow trusted config files to extend HTTPS URLs |
@@ -2026,7 +2029,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2186,7 +2189,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2230,11 +2233,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.24.0",
+  "version": "3.25.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.24.0",
+    "version": "3.25.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -7191,6 +7191,16 @@ static_status: string
  * `not_covered` otherwise.
  */
 test_coverage: string
+/**
+ * `true` when the function is unreachable in the production module graph
+ * but still referenced from a file that production mode excludes (test,
+ * spec, story, fixture, or benchmark). Such a function is not dead code:
+ * removing it breaks the referencing test. `false` when the production
+ * graph was compared against the full tree and no such reference exists.
+ * `null` when the report was produced without a production filter, or by
+ * a surface that carries no second reachability answer.
+ */
+test_only_reference?: (boolean | null)
 /**
  * `tracked` when V8 observed the function, `untracked` otherwise.
  */