fallow 3.11.0 → 3.13.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -133,7 +133,6 @@
       "type": "string",
       "required": false,
       "description": "How `--baseline` matches health findings: per file and category (`count`, the default) or per function identity (`identity`, strict, and only against a baseline that was saved with `--baseline-mode identity`; such a baseline still reads in count mode)",
-      "default": "count",
       "possible_values": [
         "count",
         "identity"
@@ -490,6 +489,16 @@
         "false"
       ]
     },
+    {
+      "name": "--no-type-aware",
+      "type": "bool",
+      "required": false,
+      "description": "Disable TypeScript semantic analysis even when `typeAware.enabled` or `FALLOW_TYPE_AWARE` opts in, keeping this run fully syntactic",
+      "possible_values": [
+        "true",
+        "false"
+      ]
+    },
     {
       "name": "--type-aware-project",
       "type": "string",
@@ -5928,6 +5937,7 @@
     "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.",
     "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_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).",
     "FALLOW_IMPACT_STORE_MAX_AGE_DAYS": "GC threshold in days for per-project fallow impact stores; a recorded run reclaims stores older than this (unset/0 keeps every store forever).",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.11.0",
+  "version": "3.13.0",
   "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",
   "repository": {
@@ -87,14 +87,14 @@
     "@tanstack/intent": "0.3.6"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "3.11.0",
-    "@fallow-cli/darwin-x64": "3.11.0",
-    "@fallow-cli/linux-x64-gnu": "3.11.0",
-    "@fallow-cli/linux-arm64-gnu": "3.11.0",
-    "@fallow-cli/linux-x64-musl": "3.11.0",
-    "@fallow-cli/linux-arm64-musl": "3.11.0",
-    "@fallow-cli/win32-arm64-msvc": "3.11.0",
-    "@fallow-cli/win32-x64-msvc": "3.11.0",
-    "fallow-type-aware": "3.10.0"
+    "@fallow-cli/darwin-arm64": "3.13.0",
+    "@fallow-cli/darwin-x64": "3.13.0",
+    "@fallow-cli/linux-x64-gnu": "3.13.0",
+    "@fallow-cli/linux-arm64-gnu": "3.13.0",
+    "@fallow-cli/linux-x64-musl": "3.13.0",
+    "@fallow-cli/linux-arm64-musl": "3.13.0",
+    "@fallow-cli/win32-arm64-msvc": "3.13.0",
+    "@fallow-cli/win32-x64-msvc": "3.13.0",
+    "fallow-type-aware": "3.13.0"
   }
 }

package/schema.json

@@ -2705,6 +2705,13 @@
           ],
           "format": "uint32",
           "minimum": 0
+        },
+        "typeAware": {
+          "description": "Overrides the top-level `typeAware.enabled` opt-in for `fallow audit` only: set `false` to keep persistent type-aware analysis on for cleanup commands (`dead-code`, `fix`, `health`) while the audit gate stays syntactic, or `true` to enable it for audit alone. Unset inherits `typeAware.enabled`. The `--type-aware`/`--no-type-aware` CLI flags and the `FALLOW_TYPE_AWARE` environment variable both take precedence over this field.",
+          "type": [
+            "boolean",
+            "null"
+          ]
         }
       }
     },

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

@@ -517,7 +517,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -915,7 +915,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -992,7 +992,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1093,7 +1093,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1122,7 +1122,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1681,7 +1681,7 @@ Available on all commands:
 | `--churn-file` | `string` | - | Import change history from a `fallow-churn/v1` JSON file instead of `git log`, powering hotspots, ownership, and bus-factor on projects with no git repository (Yandex Arc, Mercurial, Perforce). A small wrapper translates your VCS log into the contract. Resolved relative to `--root`. Affects `health --hotspots` / `--ownership` / `--targets` only; `audit`, `impact`, and `--changed-since` still require git |
 | `--max-file-size` | `string` | - | Skip source files larger than this many megabytes (default 5) instead of parsing them, guarding against the out-of-memory blowup a single multi-MB generated/vendored/bundled file causes on large repos. Use `0` for no limit. Declaration files (`.d.ts`) are always analyzed. Skipped files are reported and excluded from every analysis. Also settable via `FALLOW_MAX_FILE_SIZE` |
 | `--baseline` | `string` | - | Compare to baseline |
-| `--baseline-mode` | `count\|identity` | `count` | How `--baseline` matches health findings: per file and category (`count`, the default) or per function identity (`identity`, strict, and only against a baseline saved with `--baseline-mode identity`; such a baseline still reads in count mode). Identity is file path plus function name, so renaming or moving a function that is still in the baseline reports it as new; re-save after that kind of refactor. |
+| `--baseline-mode` | `count\|identity` | - | How `--baseline` matches health findings: per file and category (`count`, the default) or per function identity (`identity`, strict, and only against a baseline saved with `--baseline-mode identity`; such a baseline still reads in count mode). Identity is file path plus function name, so renaming or moving a function that is still in the baseline reports it as new; re-save after that kind of refactor. |
 | `--parent-run` | `string` | - | Correlate this run with a previous telemetry analysis run |
 | `--save-baseline` | `string` | - | Save results as baseline |
 | `--production` | `bool` | `false` | Exclude test/dev files, only start/build scripts (applies to every analysis) |
@@ -1723,6 +1723,7 @@ Available on all commands:
 | `--coverage-root` | `string` | - | Absolute prefix to strip from Istanbul file paths in combined mode. Also settable via `FALLOW_COVERAGE_ROOT` or `health.coverageRoot` |
 | `--include-entry-exports` | `bool` | `false` | Report unused exports in entry files instead of auto-marking them as used |
 | `--type-aware` | `bool` | `false` | Opt in to TypeScript semantic analysis for project-wide symbol evidence. This does not emit compiler diagnostics or typed lint findings |
+| `--no-type-aware` | `bool` | `false` | Disable TypeScript semantic analysis even when `typeAware.enabled` or `FALLOW_TYPE_AWARE` opts in, keeping this run fully syntactic |
 | `--type-aware-project` | `string` | - | TypeScript project config to use for type-aware analysis (repeatable) |
 | `--type-aware-require` | `best-effort\|complete` | - | Decide whether incomplete type-aware analysis is advisory or gating |
 <!-- generated:flags:global:end -->
@@ -1779,6 +1780,7 @@ These are global flags with behavior specific to bare `fallow` combined mode.
 | `FALLOW_CACHE_MAX_SIZE` | Maximum on-disk extraction cache (`.fallow/cache.bin`) size in megabytes (default: `256`). Triggers LRU eviction when crossed. Wins over `cache.maxSizeMb` config field. Intended for CI runners with disk quotas. `--no-cache` short-circuits this knob. |
 | `FALLOW_COVERAGE` | Path to Istanbul coverage data for exact CRAP scoring in `health`, `audit`, and bare `fallow`. |
 | `FALLOW_COVERAGE_ROOT` | Absolute coverage-data prefix to strip before matching Istanbul paths in `health`, `audit`, and bare `fallow`. |
+| `FALLOW_TYPE_AWARE` | Enable or disable TypeScript semantic (type-aware) analysis for the run. Accepts `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`; any other value is a hard error. Sits mid-chain in the precedence: the `--type-aware`/`--no-type-aware` CLI flags win over it, and it wins over the `audit.typeAware` config field, which wins over `typeAware.enabled`. |
 | `FALLOW_AUDIT_BASE` | Pin the `fallow audit` comparison base when `--base` / `--changed-since` is unset (precedence: flag > env > auto-detect). Escape hatch for the agent gate and forks, e.g. `FALLOW_AUDIT_BASE=upstream/main`. When unset, audit auto-detects the `git merge-base` against the branch's upstream or the remote default. A malformed value exits 2. |
 | `FALLOW_AUDIT_CACHE_MAX_AGE_DAYS` | Max age (in days since last reuse or fresh create) of a persistent reusable `fallow audit` base-snapshot worktree cache. Older entries are reclaimed at the top of the next `fallow audit` invocation (default: `30`). Wins over `audit.cacheMaxAgeDays` config field. `0` disables the GC; invalid values silently fall back to config / default. |
 | `FALLOW_UPDATE_CHECK` | Set to `off`, `0`, `false`, `disabled`, or `no` to disable the human-TTY upgrade nudge and its background latest-version check. `DO_NOT_TRACK`, `FALLOW_TELEMETRY_DISABLED`, and CI also suppress it. |
@@ -1884,7 +1886,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2044,7 +2046,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2088,11 +2090,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.13.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.9.1",
+    "version": "3.13.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/patterns.md

@@ -780,7 +780,7 @@ Manual files:
 Prefer `fallow hooks install --target agent` to install this file. The script is written and maintained by fallow itself; the canonical source is [`crates/cli/src/setup_hooks/fallow-gate.sh`](https://github.com/fallow-rs/fallow/blob/main/crates/cli/src/setup_hooks/fallow-gate.sh).
 
 Behavior you can rely on:
-- Runs only when the intercepted command matches `git commit` or `git push`; otherwise exits 0.
+- Runs only when the intercepted command is a `git commit` or `git push`, including invocations that pass git-level options before the subcommand (`git -c user.name=x commit`, `git --no-pager commit`, `git -C dir push`, `git --git-dir=/x push`); anything else exits 0. Set `FALLOW_GATE_DEBUG=1` to log skipped commands to stderr.
 - Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
 - Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.85.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
 - Runs `fallow audit --format json --quiet --explain --gate-marker agent` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.

package/types/output-contract.d.ts

@@ -5328,6 +5328,53 @@ istanbul_total?: (number | null)
 severity_critical_count: number
 severity_high_count: number
 severity_moderate_count: number
+/**
+ * Baseline staleness data, present only when a baseline was loaded.
+ */
+baseline_staleness?: (HealthBaselineStaleness | null)
+}
+/**
+ * Staleness of a loaded health baseline.
+ *
+ * Reports how many saved complexity and CRAP finding entries still matched a
+ * current finding on this run, so consumers can see a rotting baseline before
+ * it degrades to zero overlap. Runtime-coverage suppressions and refactoring
+ * target keys carried by the same baseline are not counted here. Present in
+ * the summary only when a baseline was loaded.
+ */
+export interface HealthBaselineStaleness {
+/**
+ * Complexity and CRAP finding entries carried by the loaded baseline.
+ */
+baseline_entries: number
+/**
+ * Entries that matched a current finding in the active baseline mode,
+ * including entries matched through a followed file move.
+ */
+matched_entries: number
+/**
+ * Entries that matched no current finding on this run.
+ */
+stale_entries: number
+/**
+ * Entries that matched only by following a file move in identity mode.
+ * Always zero in count mode.
+ */
+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.
+ */
+change_scoped: boolean
+/**
+ * True exactly when the run was not change-scoped, at least one current
+ * finding existed before baseline filtering, and `stale_entries` reached
+ * a quarter of `baseline_entries`. Mirrors the human warning so machine
+ * consumers do not have to reimplement the threshold.
+ */
+stale: boolean
 }
 /**
  * Report entry describing whether a threshold override is active, stale, or