fallow 3.19.0 → 3.21.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.19.0",
+  "version": "3.21.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -1792,7 +1792,7 @@
           "name": "--walkthrough-file",
           "type": "string",
           "required": false,
-          "description": "Ingest an agent's judgment JSON and POST-VALIDATE it against the LIVE graph. Rejects any judgment whose `signal_id` fallow did not emit (anti-hallucination); refuses the whole payload as stale when the echoed graph-snapshot hash no longer matches (the tree moved). The verifier is the graph, not a second model. Implies the brief; always exits 0. The agent's free-text framing is fenced as non-deterministic and never gates or auto-posts"
+          "description": "Ingest an agent's judgment JSON and POST-VALIDATE it against the LIVE graph. Rejects any judgment whose `signal_id` fallow did not emit (anti-hallucination); refuses the whole payload as stale when the echoed graph-snapshot hash no longer matches (the tree moved); rejects an `action` outside `block`, `address`, `consider`, `fyi` (`invalid-action`). The verifier is the graph, not a second model. Implies the brief; always exits 0. The agent's free-text framing and action label are fenced as non-deterministic and never gate or auto-post"
         },
         {
           "name": "--walkthrough",

package/package.json

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

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

@@ -299,7 +299,7 @@ fallow list --workspaces --format json --quiet
 fallow workspaces --format json --quiet  # alias of `fallow list --workspaces`
 ```
 
-The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `source-read-failure`, `bun-lockb-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file` and `skipped-minified-file`, since those reach an envelope only from the walk that recorded them. The two analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
+The `--workspaces` JSON output carries `workspaces[]` (name, project-root-relative path, `is_internal_dependency` bool) plus `workspace_diagnostics[]`. Each diagnostic has a `kind` discriminator (`undeclared-workspace`, `malformed-package-json`, `glob-matched-no-package-json`, `malformed-tsconfig`, `tsconfig-reference-dir-missing`, `malformed-pnpm-workspace-yaml`, `skipped-large-file`, `skipped-minified-file`, `skipped-source-dotdir`, `source-read-failure`, `bun-lockb-override-resolution-skipped`) with a typed payload (`error`, `pattern`, or none), and a `path` that is project-root-relative with forward slashes on every envelope that carries the array. The same `workspace_diagnostics[]` array is also surfaced on the `fallow dead-code --format json`, `fallow dupes --format json`, and `fallow health --format json` envelopes, at the top level of the bare combined `fallow --format json` envelope, on `fallow audit --format json` under `dead_code`, and on the `audit-brief` envelope shared by `fallow review --format json` and `fallow audit --brief --format json`, also under `dead_code` (omitted when empty). The combined carrier is the envelope root, not a section, so `--skip check`, `--only health`, and `--only dupes` all still report what their analyses recorded. The combined root is the union of what every analysis in the run recorded, deduplicated on the whole `kind` (typed payload included) plus `path`, so two overlapping globs still report the same package-less directory once per `pattern` (a declared glob's no-op `./` prefix is normalised away, so one glob written `"./apps/**"` in `package.json` and `apps/**` in `pnpm-workspace.yaml` stays one entry): a combined run walks the project once per analysis, and a per-analysis `production` mode (`production: { deadCode, health, dupes }`, `--production-health`) can give those walks different file sets, so only the union reports what the run as a whole saw. Each analysis contributes the workspace-discovery list its own config load produced, the same list `fallow list --workspaces` reports, so the combined root can carry an `undeclared-workspace` or `glob-matched-no-package-json` entry that the standalone `dead-code`, `check`, `health`, and `dupes` envelopes, which read the process diagnostics registry instead, do not. `fallow audit --format json` and the `audit-brief` envelope are on the same broad side: they fold the dead-code analysis's own list into their `dead_code.workspace_diagnostics[]`, so they too report an `undeclared-workspace` entry the standalone envelopes miss. The CLI and the programmatic route (MCP code mode, NAPI, embedders) agree on everything an analysis records: both folds close with the same process-registry read, which covers what an analysis records after its section captured its list (a `source-read-failure`, or the analysis-stage kinds a health run's own dead-code precompute records) and skips `skipped-large-file`, `skipped-minified-file`, and `skipped-source-dotdir`, since those reach an envelope only from the walk that recorded them. The two analysis-stage kinds (`malformed-pnpm-workspace-yaml`, `bun-lockb-override-resolution-skipped`) are recorded by the dead-code analyze pass, so they only appear on runs that include it: `fallow dupes --format json` and `fallow --only dupes` report the workspace-discovery and source-discovery kinds alone. A malformed ROOT `package.json` exits 2 at config load; everything else warns and continues.
 
 The `--boundaries` JSON output carries `boundaries.logical_groups[]` alongside the existing `zones[]` / `rules[]` arrays. Each logical-group entry surfaces a user-authored `autoDiscover` parent zone (which expansion otherwise flattens into per-child zones like `features/auth` / `features/billing`): `name`, `children`, `auto_discover` (verbatim user strings), `status` (`ok` / `empty` / `invalid_path`), `source_zone_index`, summed `file_count`, optional `authored_rule` (the pre-expansion `{ allow, allowTypeOnly }` keyed on the parent), optional `fallback_zone` cross-reference when the parent also kept its own `patterns` (Bulletproof case), optional `merged_from` (parent zone indices when the user declared the same parent name twice; surfaces the duplicate in JSON instead of only in `tracing::warn!`), optional `original_zone_root` (echo of the parent's `root` subtree scope for monorepo patchers), and optional `child_source_indices` (parallel to `children`, attributing each child to a specific `auto_discover` entry when multiple paths were authored). The full shape is documented in `docs/output-schema.json` under `ListBoundariesOutput`.
 
@@ -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.19.0",
+  "fallow_version": "3.20.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.16.0",
+  "version": "3.21.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -987,7 +987,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.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.16.0",
+  "version": "3.21.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.16.0",
+    "version": "3.21.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -442,6 +442,8 @@ kind: "skipped-large-file"
 size_bytes: number
 kind: "skipped-minified-file"
 } | {
+kind: "skipped-source-dotdir"
+} | {
 /**
  * Filesystem or UTF-8 decoding error from `read_to_string`.
  */
@@ -988,7 +990,7 @@ export type FeatureFlagActionType = ("investigate-flag" | "suppress-line")
  * Independently-versioned wire-version newtype for the brief envelope.
  * Serializes as the integer `REVIEW_BRIEF_SCHEMA_VERSION`.
  */
-export type ReviewBriefSchemaVersion = 7
+export type ReviewBriefSchemaVersion = 8
 /**
  * The exactly-three shippable decision categories (the SOLID-3). No cut category
  * (abstraction / deletion / convention / irreversibility) is representable: this
@@ -1033,6 +1035,13 @@ export type DecisionSurfaceSchemaVersion = number
  * The discriminated action kinds a decision can carry.
  */
 export type DecisionActionType = ("ask-expert" | "suppress")
+/**
+ * Whether a changed source unit has a test file importing it, and whether that
+ * test moved with the change. A direct-importer fact from the graph, not a
+ * coverage claim: `untouched` says a test exists and was not edited, which is
+ * the verification question the reviewer asks the author, never an answer.
+ */
+export type TestAdjacency = ("none" | "untouched" | "changed")
 /**
  * The `fallow suppressions --format json` schema version. Independently
  * versioned from the main contract, mirroring `SecuritySchemaVersion`.
@@ -2545,7 +2554,8 @@ _meta?: (Meta | null)
  *   `malformed-package-json`, `glob-matched-no-package-json`,
  *   `malformed-tsconfig`, `tsconfig-reference-dir-missing`;
  * - source discovery, during the file walk: `skipped-large-file`,
- *   `skipped-minified-file`, `source-read-failure`;
+ *   `skipped-minified-file`, `skipped-source-dotdir`,
+ *   `source-read-failure`;
  * - dead-code analysis, from the dependency-catalog and override
  *   detectors: `malformed-pnpm-workspace-yaml`,
  *   `bun-lockb-override-resolution-skipped`.
@@ -5435,7 +5445,12 @@ crap?: (number | null)
  */
 coverage_pct?: (number | null)
 /**
- * Coverage tier bucket derived from `coverage_pct`.
+ * Coverage tier bucket.
+ *
+ * Derived from `coverage_pct` when coverage was measured. When
+ * `coverage_source` is estimated, `coverage_pct` is absent and the tier
+ * describes the static estimate behind the CRAP score rather than an
+ * observation, so read the two fields together.
  */
 coverage_tier?: (CoverageTier | null)
 /**
@@ -5735,6 +5750,16 @@ istanbul_matched?: (number | null)
  * Functions in the Istanbul coverage file, in Istanbul mode.
  */
 istanbul_total?: (number | null)
+/**
+ * Analyzed files the Istanbul coverage file carried an entry for.
+ * Read against `istanbul_files_total`, this separates a coverage file
+ * that did not join from code the coverage file says nothing ran in.
+ */
+istanbul_files_matched?: (number | null)
+/**
+ * Files described by the Istanbul coverage file, joined or not.
+ */
+istanbul_files_total?: (number | null)
 /**
  * Findings with critical severity.
  */
@@ -12518,6 +12543,16 @@ units: ReviewUnitFact[]
  * the `units` module directories.
  */
 order: string[]
+/**
+ * Connected components of the inter-unit dependency graph: groups of
+ * module directories that share no import edge with any unit outside the
+ * group. Present only when there are two or more; a single slice is just
+ * `order`. A slice proves the absence of import edges to the rest of the
+ * change, nothing more: whether it can land on its own is still a
+ * judgment (generated files and lockstep contracts share no edge and
+ * still belong together). An orientation fact, never a demand to split.
+ */
+independent_slices?: string[][]
 }
 /**
  * One review unit: a coherent by-module cluster of the changed set.
@@ -12683,6 +12718,19 @@ cycle_introduced: string[]
  * reachable through an `exports` path is present (exactly one).
  */
 public_api_added: string[]
+/**
+ * Third-party dependencies a changed `package.json` declares that the base
+ * manifest did not, as `<manifest>::<name>` keys. Every dependency section
+ * participates. Always present, empty when no manifest changed.
+ */
+dependency_added: string[]
+/**
+ * Declared dependencies whose range moved across a major version (or a
+ * `0.x` minor) vs base, as `<manifest>::<name>@<from>-><to>` keys. Minor
+ * and patch moves are not candidates; a non-numeric range is skipped.
+ * Always present, empty when nothing crossed a major version.
+ */
+dependency_major_bumped: string[]
 }
 /**
  * One weakening signal: a category, the file it was detected in, and a short
@@ -12963,6 +13011,11 @@ out_of_diff: string[]
  * Routed expert(s), when ownership signals are available.
  */
 expert: string[]
+/**
+ * Direct test adjacency of this unit. Absent when the graph was not
+ * retained or the unit is itself a test file.
+ */
+test_adjacency?: (TestAdjacency | null)
 }
 /**
  * One stable per-hunk CHANGE ANCHOR: a changed region the agent may cite as a
@@ -13005,8 +13058,10 @@ previous_change_anchor?: (string | null)
  */
 export interface AgentSchema {
 /**
- * How the agent must structure each judgment: cite an emitted `signal_id`,
- * add free-text `framing` (non-deterministic, fenced), an optional `concern`.
+ * How the agent must structure each judgment: cite an emitted `signal_id`
+ * or `change_anchor`, add free-text `framing` (non-deterministic, fenced),
+ * an optional `concern`, and an optional `action` from the closed
+ * vocabulary.
  */
 judgment_shape: string
 /**
@@ -13018,6 +13073,16 @@ echo_field: string
  * The anchoring rule name.
  */
 anchoring_rule: string
+/**
+ * The closed `action` vocabulary ([`JUDGMENT_ACTIONS`]): a judgment with
+ * any other value is rejected on reentry.
+ */
+action_vocabulary: string[]
+/**
+ * The recommended `concern` vocabulary ([`JUDGMENT_CONCERNS`]), documented
+ * for grouping; free text is still accepted.
+ */
+concern_vocabulary: string[]
 }
 /**
  * The `fallow review --walkthrough-file` validation envelope: the result of
@@ -13095,6 +13160,13 @@ agent_framing: string
  * The agent's optional concern category.
  */
 concern?: (string | null)
+/**
+ * The author-action label the judgment carries (`block`, `address`,
+ * `consider`, or `fyi`), validated against [`JUDGMENT_ACTIONS`]. It tells
+ * the receiving author what is required and what is optional; it is the
+ * reviewer's instruction, fenced with the framing, never a gate.
+ */
+action?: (string | null)
 /**
  * Hard fence: always `false`. The framing is agent prose, never a
  * deterministic fallow result, so it never gates or auto-posts.
@@ -13118,9 +13190,15 @@ change_anchor: string
 /**
  * The rejection reason: `unanchored-signal-id` (cited a signal fallow did
  * not emit), `unknown-change-anchor` (cited a region fallow did not emit),
- * or `stale-snapshot` (the tree moved).
+ * `stale-snapshot` (the tree moved), or `invalid-action` (an `action`
+ * outside [`JUDGMENT_ACTIONS`]; the anchor itself resolved).
  */
 reason: string
+/**
+ * The offending value for an `invalid-action` rejection, echoed so the
+ * agent can correct it in one round trip. Absent for the other reasons.
+ */
+invalid_value?: (string | null)
 }
 /**
  * The `fallow suppressions --format json` envelope. `FallowOutput`