fallow 3.24.1 → 3.26.0

package/capabilities.json

@@ -1,9 +1,15 @@
 {
   "name": "fallow",
-  "version": "3.24.1",
+  "version": "3.26.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",
@@ -249,7 +255,7 @@
       "name": "--explain-skipped",
       "type": "bool",
       "required": false,
-      "description": "Show a per-pattern breakdown for default duplicate ignores",
+      "description": "Show per-pattern counts for skipped files: default duplicate ignores on dupes and audit, built-in discovery ignores on check, dead-code, audit and the default run",
       "possible_values": [
         "true",
         "false"
@@ -314,6 +320,16 @@
         "false"
       ]
     },
+    {
+      "name": "--fail-on-stale-baseline",
+      "type": "bool",
+      "required": false,
+      "description": "Exit with code 1 if a loaded --baseline has entries that match nothing in this run",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
     {
       "name": "--tolerance",
       "type": "string",
@@ -882,6 +898,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 +960,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 +1096,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 +1283,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 +1408,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 +1672,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 +1909,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 +2018,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"
         }
       ]
     },
@@ -7198,7 +7262,7 @@
     ]
   },
   "plugins": {
-    "count": 125,
+    "count": 126,
     "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",
@@ -7272,6 +7336,7 @@
       "biome",
       "stylelint",
       "prettier",
+      "oxfmt",
       "oxlint",
       "markdownlint",
       "cspell",

package/package.json

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

package/schema.json

@@ -36,7 +36,7 @@
       "default": []
     },
     "ignorePatterns": {
-      "description": "An array of project-root-relative glob patterns for files to exclude from analysis entirely; entries are unioned with fallow's built-in defaults (**/node_modules/**, **/dist/**, build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.min.mjs, **/*.min.cjs, **/*.bundle.js), so custom globs add to rather than replace them. Set it (e.g. `[\"generated/**\"]`) to drop generated or vendored trees from every detector; patterns are validated at load.",
+      "description": "An array of project-root-relative glob patterns for files to exclude from analysis entirely; entries are unioned with fallow's built-in defaults (**/node_modules/**, **/dist/**, **/build/**, **/.git/**, **/coverage/**, **/*.min.js, **/*.min.mjs, **/*.min.cjs, **/*.bundle.js), so custom globs add to rather than replace them. Set it (e.g. `[\"generated/**\"]`) to drop generated or vendored trees from every detector; patterns are validated at load.",
       "type": "array",
       "items": {
         "type": "string"
@@ -373,6 +373,8 @@
     }
   },
   "additionalProperties": false,
+  "allowComments": true,
+  "allowTrailingCommas": true,
   "$defs": {
     "ExternalPluginDef": {
       "description": "A declarative plugin definition loaded from a standalone file or inline config.\n\nExternal plugins provide the same static pattern capabilities as built-in\nplugins (entry points, always-used files, used exports, tooling dependencies),\nbut are defined in standalone files or inline in the fallow config rather than\ncompiled Rust code.\n\nThey cannot do AST-based config parsing (`resolve_config()`), but cover the\nvast majority of framework integration use cases.\n\nSupports JSONC, JSON, and TOML formats. All use camelCase field names.\n\n```json\n{\n  \"$schema\": \"https://raw.githubusercontent.com/fallow-rs/fallow/main/plugin-schema.json\",\n  \"name\": \"my-framework\",\n  \"enablers\": [\"my-framework\", \"@my-framework/core\"],\n  \"entryPoints\": [\"src/routes/**/*.{ts,tsx}\"],\n  \"configPatterns\": [\"my-framework.config.{ts,js}\"],\n  \"alwaysUsed\": [\"src/setup.ts\"],\n  \"toolingDependencies\": [\"my-framework-cli\"],\n  \"usedExports\": [\n    { \"pattern\": \"src/routes/**/*.{ts,tsx}\", \"exports\": [\"default\", \"loader\", \"action\"] }\n  ]\n}\n```",

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.1",
+  "fallow_version": "3.26.0",
   "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.1",
+  "version": "3.26.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -1053,7 +1053,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.24.1",
+  "version": "3.26.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.1",
+  "version": "3.26.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.1",
+  "version": "3.26.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.1",
+  "version": "3.26.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1808,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 |
@@ -1835,7 +1836,7 @@ Available on all commands:
 | `--group-by` | `owner\|directory\|package\|section` | - | Group output by CODEOWNERS ownership (`owner`), first path component (`directory`), workspace package (`package`, aliases: `workspace`, `pkg`), or GitLab CODEOWNERS `[Section]` headers (`section`, alias: `gl-section`). All output formats partition issues into labeled groups. `section` mode attaches an `owners` array to each group in JSON output |
 | `--performance` | `bool` | `false` | Show pipeline timing breakdown |
 | `--explain` | `bool` | `false` | JSON: include metric definitions in `_meta`. Human: print a `Description:` line under each section header. Always on for MCP. |
-| `--explain-skipped` | `bool` | `false` | Show a per-pattern breakdown for default duplicate ignores |
+| `--explain-skipped` | `bool` | `false` | Human/markdown only: show per-pattern counts for files skipped by the default duplicates ignores. `dupes` prints only that breakdown; on `check`, `dead-code`, `audit` and the default run the same flag reports source files the built-in discovery ignores removed |
 | `--summary` | `bool` | `false` | Show only category counts without individual items. Useful for dashboards and quick overviews |
 | `--ci` | `bool` | `false` | CI mode: `--format sarif --fail-on-issues --quiet` |
 | `--fail-on-issues` | `bool` | `false` | Exit 1 if any issues found (promotes `warn` to `error`) |
@@ -1843,6 +1844,7 @@ Available on all commands:
 | `-o, --output-file` | `string` | - | Write the report to a file instead of stdout, for any --format (no ANSI codes). Useful on large projects where the terminal scrollback truncates the top. Progress and the confirmation stay on stderr |
 | `--report-path-prefix` | `string` | - | Prefix prepended to every path in the CI-facing formats (`github-annotations`, `github-summary`, `codeclimate`, `review-github`, `review-gitlab`). CI platforms address files by repository-root-relative path, so when the analyzed project lives in a subdirectory (e.g. `packages/app/`), paths need that offset. fallow detects the offset via the git toplevel automatically; this flag overrides the detection. Pass an empty string to disable rebasing and emit paths relative to `--root` |
 | `--fail-on-regression` | `bool` | `false` | Fail if issue count increased beyond tolerance vs a regression baseline |
+| `--fail-on-stale-baseline` | `bool` | `false` | Exit with code 1 if a loaded --baseline has entries that match nothing in this run |
 | `--tolerance` | `string` | `0` | Allowed increase: `"2%"` (percentage) or `"5"` (absolute). Default: `"0"` |
 | `--regression-baseline` | `string` | - | Path to a standalone regression baseline file. Without it, fallow uses `regression.baseline` from the config |
 | `--save-regression-baseline` | `string` | - | Save current issue counts. With no path, update `regression.baseline` in the discovered fallow config or create `.fallowrc.json`; with a path, write a standalone baseline file |
@@ -2028,7 +2030,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.24.1",
+  "version": "3.26.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2188,7 +2190,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.24.1",
+  "version": "3.26.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2232,11 +2234,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.24.1",
+  "version": "3.26.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.24.1",
+    "version": "3.26.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -500,6 +500,31 @@ kind: "node-modules-missing"
 kind: "boundaries-not-configured"
 } | {
 kind: "rule-packs-not-configured"
+} | {
+/**
+ * The built-in glob that matched, verbatim (for example
+ * `** /build/**`).
+ */
+pattern: string
+/**
+ * Candidate source files this pattern excluded in this walk, across
+ * every directory it matched, not just the one `path` anchors at.
+ * Exact: the walk counts each excluded candidate once.
+ */
+file_count: number
+/**
+ * Distinct directories this pattern matched at, `path` included, and
+ * not the number of directories that held the files. A
+ * directory-shaped pattern (`** /dist/**`) matches at the directory it
+ * names, so an excluded subtree counts once however many nested
+ * directories inside it held source: a `dist/` holding files in three
+ * sub-directories reports `1`. A file-shaped pattern (`** /*.min.js`)
+ * has no directory to collapse to and counts each matched file's own
+ * parent. Exact either way, and anything above `1` says `path` names
+ * one matched location out of several.
+ */
+directory_count: number
+kind: "excluded-by-default-ignore"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -2663,7 +2688,8 @@ _meta?: (Meta | null)
  *   `malformed-tsconfig`, `tsconfig-reference-dir-missing`;
  * - source discovery, during the file walk: `skipped-large-file`,
  *   `skipped-minified-file`, `skipped-source-dotdir`,
- *   `source-read-failure`, `source-parse-degraded`;
+ *   `excluded-by-default-ignore`, `source-read-failure`,
+ *   `source-parse-degraded`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`.
@@ -2684,6 +2710,18 @@ _meta?: (Meta | null)
  * optional `reachability_caveats[]` array, and a reader who never scrolls
  * back up to this list still sees it. `fallow fix` reads the same array
  * and withholds the removal while a caveat stands.
+ *
+ * `excluded-by-default-ignore` is the one source-discovery kind that
+ * reports unseen files WITHOUT raising a caveat. It names a built-in
+ * ignore pattern (`** /dist/**`, `** /build/**`, `** /coverage/**`, or one
+ * of the four minified-bundle globs) that removed candidate source files
+ * from the walk, which is designed behavior on generated output rather
+ * than a degraded run, so it is advisory only and no finding inherits it.
+ * One entry per pattern, never per file, so the array stays bounded on a
+ * project of any size. Gitignored trees are pruned before the walk sees
+ * them and count zero, and `** /node_modules/**` is never reported:
+ * installed dependencies are not the first-party source the kind is
+ * about.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -6034,9 +6072,10 @@ stale_entries: number
 moved_entries: number
 /**
  * True when this run analyzed a subset of the project (changed-file,
- * diff, or workspace scoping), so the baseline was compared against a
- * narrowed finding set and staleness cannot be judged. `stale` is always
- * false on scoped runs.
+ * diff, or workspace scoping, or production mode, which drops test, story
+ * and dev files), so the baseline was compared against a narrowed finding
+ * set and staleness cannot be judged. `stale` is always false on scoped
+ * runs.
  */
 change_scoped: boolean
 /**