fallow 2.75.0 → 2.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.75.0",
+  "version": "2.76.0",
   "description": "Codebase intelligence for TypeScript and JavaScript. Finds unused code, duplication, circular dependencies, complexity hotspots, and architecture drift. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, 94 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -73,13 +73,13 @@
     "@tanstack/intent": "0.0.40"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.75.0",
-    "@fallow-cli/darwin-x64": "2.75.0",
-    "@fallow-cli/linux-x64-gnu": "2.75.0",
-    "@fallow-cli/linux-arm64-gnu": "2.75.0",
-    "@fallow-cli/linux-x64-musl": "2.75.0",
-    "@fallow-cli/linux-arm64-musl": "2.75.0",
-    "@fallow-cli/win32-arm64-msvc": "2.75.0",
-    "@fallow-cli/win32-x64-msvc": "2.75.0"
+    "@fallow-cli/darwin-arm64": "2.76.0",
+    "@fallow-cli/darwin-x64": "2.76.0",
+    "@fallow-cli/linux-x64-gnu": "2.76.0",
+    "@fallow-cli/linux-arm64-gnu": "2.76.0",
+    "@fallow-cli/linux-x64-musl": "2.76.0",
+    "@fallow-cli/linux-arm64-musl": "2.76.0",
+    "@fallow-cli/win32-arm64-msvc": "2.76.0",
+    "@fallow-cli/win32-x64-msvc": "2.76.0"
   }
 }

package/schema.json

@@ -186,6 +186,15 @@
         "configObjectHeuristics": false
       }
     },
+    "fix": {
+      "description": "Auto-fix behavior settings.",
+      "$ref": "#/$defs/FixConfig",
+      "default": {
+        "catalog": {
+          "deletePrecedingComments": "auto"
+        }
+      }
+    },
     "resolve": {
       "description": "Module resolver configuration (custom conditions, etc.).",
       "$ref": "#/$defs/ResolveConfig",
@@ -1044,7 +1053,7 @@
           "const": "feature-sliced"
         },
         {
-          "description": "Bulletproof React: app → features → shared + server.\nFeature modules are isolated from each other via `autoDiscover`: every\nimmediate child of `src/features/` becomes its own `features/<name>` zone,\nand cross-feature imports are reported as boundary violations.\n\n**Trade-off (intentional):** top-level files in `src/features/` (e.g.\n`src/features/index.ts` barrel, `src/features/types.ts`) do NOT match any\nchild pattern and are unclassified, meaning they are unrestricted by the\npreset. This is deliberate so feature barrels can re-export children\nwithout producing false-positive `features → features/<child>` violations.\nTo classify top-level files strictly, override the `features` zone with\nan explicit user definition that includes a `patterns` field.",
+          "description": "Bulletproof React: app → features → shared + server.\nFeature modules are isolated from each other via `autoDiscover`: every\nimmediate child of `src/features/` becomes its own `features/<name>` zone,\nand cross-feature imports are reported as boundary violations.\nTop-level files in `src/features/` are classified by the logical\n`features` parent zone, so barrels can re-export child features while\nnon-barrel top-level files still obey the `features` boundary rule.",
           "type": "string",
           "const": "bulletproof"
         }
@@ -1099,6 +1108,13 @@
             "type": "string"
           },
           "default": []
+        },
+        "allowTypeOnly": {
+          "description": "Zones that `from` may type-only-import from even when not listed in\n`allow`. Mirrors the `allow` shape: a list of target zone names. A\ntype-only import declaration (`import type {...}`, `import type * as ns`,\nor a per-specifier inline `type` qualifier on every named specifier) to a\nlisted zone is not reported as a boundary violation. Mixed-specifier\nimports (`import { type Foo, Bar }`) that carry at least one value\nsymbol still fire because the runtime dependency on `Bar` is real.\nType-only re-exports (`export type { Foo } from \"...\"`) participate\nin the same allowance because they surface as edges flagged\n`is_type_only: true` and, like type-only imports, are erased at\ncompile time.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
         }
       },
       "required": [
@@ -1157,6 +1173,50 @@
         "function"
       ]
     },
+    "FixConfig": {
+      "description": "Auto-fix behavior settings.",
+      "type": "object",
+      "properties": {
+        "catalog": {
+          "description": "Auto-fix behavior for pnpm catalog edits.",
+          "$ref": "#/$defs/CatalogFixConfig",
+          "default": {
+            "deletePrecedingComments": "auto"
+          }
+        }
+      }
+    },
+    "CatalogFixConfig": {
+      "description": "Auto-fix behavior for pnpm catalog entries.",
+      "type": "object",
+      "properties": {
+        "deletePrecedingComments": {
+          "description": "Whether removing an unused catalog entry also removes the contiguous\nYAML comment block immediately above it.",
+          "$ref": "#/$defs/CatalogPrecedingCommentPolicy",
+          "default": "auto"
+        }
+      }
+    },
+    "CatalogPrecedingCommentPolicy": {
+      "description": "Policy for deleting comments immediately above removed catalog entries.",
+      "oneOf": [
+        {
+          "description": "Delete the comment block when it is separated from previous siblings by\na blank line, or when it directly follows the parent catalog header.",
+          "type": "string",
+          "const": "auto"
+        },
+        {
+          "description": "Always delete the contiguous comment block immediately above the entry.",
+          "type": "string",
+          "const": "always"
+        },
+        {
+          "description": "Never delete leading comments; leave them in place as orphan comments.",
+          "type": "string",
+          "const": "never"
+        }
+      ]
+    },
     "ResolveConfig": {
       "description": "Module resolver configuration.\n\nControls how fallow resolves import specifiers against package.json\n`exports` / `imports` fields and tsconfig paths. Configured via the\n`resolve` section in `.fallowrc.json`, `.fallowrc.jsonc`, `fallow.toml`, or `.fallow.toml`.\n\n# Examples\n\n```json\n{\n  \"resolve\": {\n    \"conditions\": [\"development\", \"worker\"]\n  }\n}\n```",
       "type": "object",

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

@@ -203,9 +203,10 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|
-| `--dry-run` | bool | `false` | Show what would be removed without modifying files |
+| `--dry-run` | bool | `false` | Show what would be removed without modifying files. For `add-to-config` actions, prints a unified-diff preview of the proposed config write; JSON mode includes the diff under a `proposed_diff` field on the fix entry. |
 | `--yes` | bool | `false` | Skip confirmation prompt (**required** in non-TTY) |
 | `--force` | bool | `false` | Alias for `--yes` |
+| `--no-create-config` | bool | `false` | Refuse to create a new `.fallowrc.json` when none exists. The duplicate-export config-add path is skipped with `skip_reason: "no_create_config"`; source-file edits proceed normally. Use in pre-commit hooks, CI bots, and `fallow watch` where silently materialising a new top-level file would surprise the user. |
 | `--format` | `human\|json` | `human` | Output format |
 | `--quiet` | bool | `false` | Suppress progress bars |
 
@@ -214,7 +215,8 @@ Auto-removes unused exports, dependencies, enum members, and pnpm catalog entrie
 - Unused exports (removes the `export` keyword; whole-enum block when every member is unused)
 - Unused dependencies (removed from `package.json`)
 - Unused enum members (removed from the declaration)
-- Unused pnpm catalog entries (removed from `pnpm-workspace.yaml` by line-aware deletion; comments preserved). When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` / `<name>: {}` so pnpm doesn't reject the resulting null value. Entries with non-empty `hardcoded_consumers` are skipped to avoid breaking `pnpm install`; the skip is surfaced in the JSON fix output as `{"type": "remove_catalog_entry", "applied": false, "skipped": true, "skip_reason": "hardcoded_consumers", "consumers": [...]}`. After a successful catalog edit the CLI emits a one-line `Run pnpm install to refresh pnpm-lock.yaml` reminder. The JSON envelope carries a top-level `"skipped"` count alongside `"total_fixed"` for partial-fix gating.
+- Unused pnpm catalog entries (removed from `pnpm-workspace.yaml` by line-aware deletion). Object-form entries are removed as one block. By default, fallow also removes a contiguous YAML comment block immediately above the entry when it clearly belongs to that entry; configure this with `fix.catalog.deletePrecedingComments` (`"auto"`, `"always"`, or `"never"`). Two escape hatches keep curated comments safe regardless of policy: a `# fallow-keep` marker on any line in the block preserves it, and the `auto` policy additionally preserves section-banner blocks whose body starts with three or more `=`, `-`, `*`, `_`, `~`, `+`, or `#` characters (e.g. `# === React 18 production pins ===`). Other comments and stylistic choices are preserved. When the last entry of a catalog group is removed, the header is rewritten to `catalog: {}` / `<name>: {}` so pnpm doesn't reject the resulting null value. Entries with non-empty `hardcoded_consumers` are skipped to avoid breaking `pnpm install`; the skip is surfaced in the JSON fix output as `{"type": "remove_catalog_entry", "applied": false, "skipped": true, "skip_reason": "hardcoded_consumers", "consumers": [...]}`. The JSON action carries both `line` (first deleted line, the leading comment when policy absorbs one) and `entry_line` (the catalog entry's original 1-based line); use `entry_line` as a stable anchor across policy changes. After a successful catalog edit the CLI emits a one-line `Run pnpm install to refresh pnpm-lock.yaml` reminder, and the human stderr summary appends `(+M catalog comment lines)` to the fixed-issue count when comment lines were absorbed. The JSON envelope carries a top-level `"skipped"` count alongside `"total_fixed"` for partial-fix gating.
+- Duplicate exports (appends an `ignoreExports` rule to your fallow config file). When no fallow config file exists, `.fallowrc.json` is created using the same scaffolding `fallow init` would emit (framework detection, `$schema`, `entry`, `ignorePatterns`, etc.) and the rules are layered on top. Inside a monorepo subpackage (`pnpm-workspace.yaml`, `package.json#workspaces`, `turbo.json`, `lerna.json`, or `rush.json` above the invocation directory) the create-fallback refuses to fire and emits `skip_reason: "monorepo_subpackage"` with a relative `workspace_root` path pointing at the workspace root. The applied entry carries `created_files: [".fallowrc.json"]` so consumers can detect file-creation side effects programmatically.
 
 ### Examples
 
@@ -239,7 +241,7 @@ Inspect discovered files, entry points, detected frameworks, and architecture bo
 | `--files` | bool | List all discovered files |
 | `--entry-points` | bool | List detected entry points |
 | `--plugins` | bool | List active framework plugins |
-| `--boundaries` | bool | Show architecture boundary zones, rules, and per-zone file counts |
+| `--boundaries` | bool | Show architecture boundary zones, rules, per-zone file counts, and `logical_groups[]` for `autoDiscover` parents |
 | `--format` | `human\|json` | Output format |
 | `--quiet` | bool | Suppress progress bars |
 
@@ -252,6 +254,8 @@ fallow list --plugins --format json --quiet
 fallow list --boundaries --format json --quiet
 ```
 
+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`.
+
 ---
 
 ## `init`: Config Generation
@@ -437,7 +441,7 @@ fallow health --format json --quiet --trend
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -823,7 +827,7 @@ fallow audit \
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -896,7 +900,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1131,7 +1135,7 @@ Coverage CI helper for bundled/minified runtime coverage. It scans a build direc
 | `--dir <PATH>` | path | `dist` | Directory scanned recursively. |
 | `--include <GLOB>` | glob | `**/*.map` | Include glob relative to `--dir`. |
 | `--exclude <GLOB>` | glob | `**/node_modules/**` | Exclude glob, repeatable. |
-| `--repo <NAME>` | string | `package.json` `repository.url`, then `git remote get-url origin` | Repo name used in the source-map API path. |
+| `--repo <NAME>` | string | `package.json` `repository.url`, then `git remote get-url origin` parsed to `owner/repo` | Repo identifier used in the source-map API path. Must match the beacon's `projectId` (and `upload-inventory`'s `--project-id`); pass `--repo <bare-name>` explicitly if the beacon reports a bare name. |
 | `--git-sha <SHA>` | string | `$GITHUB_SHA` -> `$CI_COMMIT_SHA` -> `$COMMIT_SHA` -> `git rev-parse HEAD` | Commit SHA, 7-40 hex chars. |
 | `--endpoint <URL>` | string | `$FALLOW_API_URL` or `https://api.fallow.cloud` | Override for staging / on-prem. |
 | `--strip-path <BOOL>` | bool | `true` | Upload basename-only `fileName` values. Use `--strip-path=false` when runtime coverage reports paths like `assets/app.js`. |
@@ -1315,7 +1319,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1367,7 +1371,7 @@ Every issue in `dead-code` JSON output includes an `actions` array with structur
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `type` | string | yes | Action type in kebab-case (for example `remove-export`, `remove-file`, `remove-dependency`, `move-dependency`, `suppress-line`, `add-to-config`) |
-| `auto_fixable` | bool | yes | `true` if `fallow fix` handles this action automatically |
+| `auto_fixable` | bool | yes | `true` if `fallow fix` handles this action automatically. Evaluated PER FINDING, not per action type: the same `type` may carry `true` on one finding and `false` on another when per-instance guards in the applier discriminate. Filter on this bool of each individual action, not on `type` alone. |
 | `description` | string | yes | Human-readable description of the action |
 | `comment` | string | no | Suppression comment text (on `suppress-line` actions) |
 | `note` | string | no | Additional context on non-auto-fixable items |
@@ -1424,6 +1428,14 @@ Dependency issues use `add-to-config` with `config_key` and `value`:
 
 When a dependency action is `move-dependency`, `auto_fixable` is `false`; the package is imported from another workspace and needs a package.json ownership move rather than removal.
 
+Per-instance `auto_fixable` flips today (the same action `type` flipping between findings):
+
+- `remove-catalog-entry` (unused-catalog-entries): `true` only when `hardcoded_consumers` is empty; `false` otherwise (the applier skips the entry to avoid breaking `pnpm install`).
+- `remove-dependency` vs `move-dependency` (dependency findings): primary action flips between `remove-dependency` (`true`) and `move-dependency` (`false`) on `used_in_workspaces`.
+- `add-to-config` for `ignoreExports` (duplicate-exports): `true` when `fallow fix` can safely apply the action, which today means EITHER a fallow config file already exists OR no config exists and the working directory is NOT inside a monorepo subpackage. In the second case the applier creates `.fallowrc.json` using `fallow init`'s framework-aware scaffolding and layers the new rules on top. `false` inside a monorepo subpackage with no workspace-root config (the applier refuses to fragment per-package configs). Pass `--no-create-config` to `fallow fix` from pre-commit hooks, CI bots, and `fallow watch` to opt out of the create-fallback; the action then surfaces with `auto_fixable: false`.
+- `update-catalog-reference` (unresolved-catalog-references): always `false` today; non-singleton on the wire so a future applier can promote it without a schema change.
+- All `suppress-line` and `suppress-file` actions are uniformly `false`.
+
 #### Health `actions` array (CRAP findings)
 
 Health findings (`fallow health` JSON output) include an `actions` array. Primary action selection is formula-aware: the rule first checks whether full coverage CAN bring CRAP under threshold (CRAP bottoms out at `cyclomatic` at 100% coverage, so `cyclomatic < maxCrap` means coverage is a viable remediation), then uses `coverage_tier` to choose the description.
@@ -1437,6 +1449,8 @@ Health findings (`fallow health` JSON output) include an `actions` array. Primar
 
 The `coverage_tier` field is `"none"` (file not test-reachable / Istanbul 0%), `"partial"` (Istanbul `(0, 70)` / estimated 40%), or `"high"` (Istanbul `>= 70` / estimated 85%).
 
+Each CRAP finding also carries a `coverage_source` discriminator: `"istanbul"` (direct fnMap match for this function), `"estimated"` (graph-based estimate evaluated against the finding's own file), or `"estimated_component_inherited"` (graph-based estimate inherited from an Angular component `.ts` reached via the inverse `templateUrl` edge). Synthetic `<template>` findings on Angular `.html` templates use the `estimated_component_inherited` source and ship an `inherited_from` field with the project-relative path to the owning `.component.ts`. When the inherit path applies, the primary `increase-coverage` action targets that `.ts` file (description names the component path explicitly and includes a `target_path` field) so AI agents add component tests rather than scaffolding tests against a structurally untestable `.html` path. The human `fallow health` output renders `(inherited from foo.component.ts)` after the CRAP score on those rows. This is the JIT-test fallback (Angular's runtime renders templates via `ɵɵconditional` / `ɵɵrepeaterCreate` calls; Istanbul never has `fnMap` entries keyed at `.html` paths). AOT-compiled coverage with source-map back-mapping is planned as a tier 2 follow-up; when it lands, `coverage_source` will gain a `"measured_aot_source_map"` variant.
+
 When CRAP-only with cyclomatic count within 5 of `maxCyclomatic` AND cognitive at or above `maxCognitive / 2`, a secondary `refactor-function` is appended. The cognitive floor suppresses false positives on flat type-tag dispatchers and JSX render maps (high CC, near-zero cog). A single finding can carry multiple action types: e.g. a finding that exceeds both cyclomatic and CRAP at `coverage_tier=partial` gets `increase-coverage` AND `refactor-function`. Treat the first non-`suppress-line` action as primary.
 
 The `suppress-line` action is auto-omitted when `--baseline`/`--save-baseline` is set, OR when `health.suggestInlineSuppression: false` in config. The report root carries an `actions_meta: { suppression_hints_omitted: true, reason: "baseline-active" | "config-disabled" }` breadcrumb in that case.
@@ -1462,7 +1476,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 ```json
 {
   "schema_version": 3,
-  "version": "2.74.0",
+  "version": "2.75.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1506,7 +1520,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "check": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],
@@ -1528,7 +1542,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "dupes": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 82,
     "total_clones": 15,
     "total_lines_duplicated": 230,
@@ -1537,7 +1551,7 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
   },
   "health": {
     "schema_version": 3,
-    "version": "2.74.0",
+    "version": "2.75.0",
     "elapsed_ms": 32,
     "summary": {},
     "findings": [],
@@ -1621,17 +1635,20 @@ Config files are searched in priority order: `.fallowrc.json` > `.fallowrc.jsonc
 
   // Architecture boundaries (preset, custom zones/rules, or auto-discovered feature zones)
   // Presets: "layered", "hexagonal", "feature-sliced", "bulletproof"
+  // Rules accept an optional `allowTypeOnly: [zones]` list that admits type-only imports
+  // (`import type`, inline `{ type Foo }`, namespace type imports, and `export type` re-exports)
+  // to the listed zones even when not present in `allow`. Mixed-specifier imports still fire.
   "boundaries": {
     "preset": "bulletproof"
     // Or:
     // "zones": [
     //   { "name": "app", "patterns": ["src/app/**"] },
-    //   { "name": "features", "autoDiscover": ["src/features"] },
+    //   { "name": "features", "patterns": ["src/features/**"], "autoDiscover": ["src/features"] },
     //   { "name": "shared", "patterns": ["src/shared/**"] }
     // ],
     // "rules": [
     //   { "from": "app", "allow": ["features", "shared"] },
-    //   { "from": "features", "allow": ["shared"] }
+    //   { "from": "features", "allow": ["shared"], "allowTypeOnly": ["features"] }
     // ]
   },