fallow 3.10.0 → 3.12.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -128,6 +128,16 @@
       "required": false,
       "description": "Compare against a previously saved baseline file"
     },
+    {
+      "name": "--baseline-mode",
+      "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)",
+      "possible_values": [
+        "count",
+        "identity"
+      ]
+    },
     {
       "name": "--parent-run",
       "type": "string",
@@ -479,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",
@@ -5904,6 +5924,7 @@
     "FALLOW_PRODUCTION_HEALTH": "Set to true/false to override production mode for health analysis.",
     "FALLOW_PRODUCTION_DUPES": "Set to true/false to override production mode for duplication analysis.",
     "FALLOW_REVIEW_GUIDANCE": "Set to true to append collapsed guidance blocks to review-github/review-gitlab inline comment bodies.",
+    "FALLOW_REVIEW_ID": "Stable 1-64 character identifier that isolates inline comments when multiple review jobs target the same PR/MR.",
     "FALLOW_SUMMARY_SCOPE": "Summary scope for pr-comment-github/pr-comment-gitlab: all (default) keeps project-level dependency/catalog/override findings outside the diff filter; diff applies the diff filter to them too. Inline review comments are unaffected.",
     "FALLOW_PR_COMMENT_LAYOUT": "Sticky PR comment layout: default, compact, gate-only, or details.",
     "FALLOW_CONSOLIDATED_STATUS": "When split PR gate check runs are enabled, truthy values add one aggregate Fallow check alongside the per-gate checks.",
@@ -5916,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.10.0",
+  "version": "3.12.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.10.0",
-    "@fallow-cli/darwin-x64": "3.10.0",
-    "@fallow-cli/linux-x64-gnu": "3.10.0",
-    "@fallow-cli/linux-arm64-gnu": "3.10.0",
-    "@fallow-cli/linux-x64-musl": "3.10.0",
-    "@fallow-cli/linux-arm64-musl": "3.10.0",
-    "@fallow-cli/win32-arm64-msvc": "3.10.0",
-    "@fallow-cli/win32-x64-msvc": "3.10.0",
-    "fallow-type-aware": "3.10.0"
+    "@fallow-cli/darwin-arm64": "3.12.0",
+    "@fallow-cli/darwin-x64": "3.12.0",
+    "@fallow-cli/linux-x64-gnu": "3.12.0",
+    "@fallow-cli/linux-arm64-gnu": "3.12.0",
+    "@fallow-cli/linux-x64-musl": "3.12.0",
+    "@fallow-cli/linux-arm64-musl": "3.12.0",
+    "@fallow-cli/win32-arm64-msvc": "3.12.0",
+    "@fallow-cli/win32-x64-msvc": "3.12.0",
+    "fallow-type-aware": "3.12.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

@@ -420,7 +420,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--min-observation-volume` | `string` | - | Minimum total trace volume before the sidecar may emit high-confidence `safe_to_delete` / `review_required` verdicts. Below this, confidence is capped at `medium`. |
 | `--low-traffic-threshold` | `string` | - | Fraction of total trace count below which an invoked function is classified `low_traffic` rather than `active`. Expressed as a decimal (0.001 = 0.1%). |
 
-Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--changed-since`](#global-flags), [`--churn-file`](#global-flags), [`--workspace`](#global-flags), [`--group-by`](#global-flags), [`--baseline`](#global-flags), [`--save-baseline`](#global-flags), [`--production`](#global-flags), [`--no-production`](#global-flags), [`--explain`](#global-flags).
+Common global flags for this command: [`--format`](#global-flags), [`--quiet`](#global-flags), [`--changed-since`](#global-flags), [`--churn-file`](#global-flags), [`--workspace`](#global-flags), [`--group-by`](#global-flags), [`--baseline`](#global-flags), [`--baseline-mode`](#global-flags), [`--save-baseline`](#global-flags), [`--production`](#global-flags), [`--no-production`](#global-flags), [`--explain`](#global-flags).
 <!-- generated:flags:health:end -->
 ### Exit Codes
 
@@ -473,6 +473,10 @@ fallow health --format json --quiet --workspace my-package
 fallow health --format json --quiet --save-baseline fallow-baselines/health.json
 fallow health --format json --quiet --baseline fallow-baselines/health.json
 
+# Strict adoption: a hotspot that replaces a baselined hotspot is reported
+fallow health --format json --quiet --save-baseline fallow-baselines/health.json --baseline-mode identity
+fallow health --format json --quiet --baseline fallow-baselines/health.json --baseline-mode identity
+
 # CI: fail if any function is too complex
 fallow health --max-cyclomatic 25 --max-cognitive 20 --quiet
 
@@ -513,7 +517,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.12.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -911,7 +915,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.12.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -988,7 +992,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.9.1",
+  "version": "3.12.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1089,7 +1093,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.9.1",
+  "version": "3.12.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1118,7 +1122,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.9.1",
+  "version": "3.12.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1677,6 +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` | - | 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) |
@@ -1718,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 -->
@@ -1774,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. |
@@ -1879,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.12.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2039,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.12.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2083,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.12.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.9.1",
+    "version": "3.12.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -747,6 +747,11 @@ export type ReviewProvider = ("github" | "gitlab")
  * GitHub Checks API conclusion field.
  */
 export type ReviewCheckConclusion = ("success" | "neutral" | "failure")
+/**
+ * Stable identifier used to isolate independent review integrations on the
+ * same pull or merge request.
+ */
+export type ReviewId = string
 /**
  * Schema-version discriminator for the review reconcile envelope.
  */
@@ -2124,19 +2129,21 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, or package.json's
- * pnpm.overrides block, whose target package is not declared by any
- * workspace package and is not present in pnpm-lock.yaml. Default severity
+ * Entries in pnpm-workspace.yaml's overrides: section, package.json's
+ * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * whose target package is not declared by any workspace package and is
+ * not present in pnpm-lock.yaml or package-lock.json. Default severity
  * is warn because projects without a readable lockfile fall back to
  * manifest-only checks; the hint field flags those conservative cases.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides entries whose key or value does not parse as a valid
- * override spec (empty key, empty value, malformed selector, unbalanced
- * parent matcher). pnpm install will reject these. Default severity is
- * error. Wrapped in [`MisconfiguredDependencyOverrideFinding`].
+ * pnpm.overrides or npm overrides entries whose key or value does not
+ * parse as a valid override spec (empty key, empty value, malformed
+ * selector, unbalanced parent matcher). The package manager will reject
+ * these at install time. Default severity is error. Wrapped in
+ * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
 /**
@@ -5321,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
@@ -8613,6 +8667,7 @@ export interface ReviewEnvelopeMeta {
 schema: ReviewEnvelopeSchema
 provider: ReviewProvider
 check_conclusion?: (ReviewCheckConclusion | null)
+review_id?: (ReviewId | null)
 }
 /**
  * Envelope emitted by `fallow ci reconcile-review --format json`. Used by
@@ -9401,19 +9456,21 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, or package.json's
- * pnpm.overrides block, whose target package is not declared by any
- * workspace package and is not present in pnpm-lock.yaml. Default severity
+ * Entries in pnpm-workspace.yaml's overrides: section, package.json's
+ * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * whose target package is not declared by any workspace package and is
+ * not present in pnpm-lock.yaml or package-lock.json. Default severity
  * is warn because projects without a readable lockfile fall back to
  * manifest-only checks; the hint field flags those conservative cases.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides entries whose key or value does not parse as a valid
- * override spec (empty key, empty value, malformed selector, unbalanced
- * parent matcher). pnpm install will reject these. Default severity is
- * error. Wrapped in [`MisconfiguredDependencyOverrideFinding`].
+ * pnpm.overrides or npm overrides entries whose key or value does not
+ * parse as a valid override spec (empty key, empty value, malformed
+ * selector, unbalanced parent matcher). The package manager will reject
+ * these at install time. Default severity is error. Wrapped in
+ * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
 /**