fallow 2.98.0 → 2.99.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.98.0",
+  "version": "2.99.0",
   "description": "Deterministic codebase intelligence for TypeScript and JavaScript. Quality, risk, architecture, dependencies, duplication, and safe cleanup evidence for humans, CI, and agents. Optional runtime intelligence layer (Fallow Runtime) adds production execution evidence. Rust-native, sub-second, zero-config framework support.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.42"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.98.0",
-    "@fallow-cli/darwin-x64": "2.98.0",
-    "@fallow-cli/linux-x64-gnu": "2.98.0",
-    "@fallow-cli/linux-arm64-gnu": "2.98.0",
-    "@fallow-cli/linux-x64-musl": "2.98.0",
-    "@fallow-cli/linux-arm64-musl": "2.98.0",
-    "@fallow-cli/win32-arm64-msvc": "2.98.0",
-    "@fallow-cli/win32-x64-msvc": "2.98.0"
+    "@fallow-cli/darwin-arm64": "2.99.0",
+    "@fallow-cli/darwin-x64": "2.99.0",
+    "@fallow-cli/linux-x64-gnu": "2.99.0",
+    "@fallow-cli/linux-arm64-gnu": "2.99.0",
+    "@fallow-cli/linux-x64-musl": "2.99.0",
+    "@fallow-cli/linux-arm64-musl": "2.99.0",
+    "@fallow-cli/win32-arm64-msvc": "2.99.0",
+    "@fallow-cli/win32-x64-msvc": "2.99.0"
   }
 }

package/schema.json

@@ -178,6 +178,7 @@
         "coverage-gaps": "off",
         "feature-flags": "off",
         "stale-suppressions": "warn",
+        "require-suppression-reason": "off",
         "unused-catalog-entries": "warn",
         "empty-catalog-groups": "warn",
         "unresolved-catalog-references": "error",
@@ -1139,6 +1140,11 @@
           "$ref": "#/$defs/Severity",
           "default": "warn"
         },
+        "require-suppression-reason": {
+          "description": "Opt-in suppression hygiene rule: when enabled, every `fallow-ignore-*`\ncomment and `@expected-unused` tag must carry a `-- <reason>` suffix.",
+          "$ref": "#/$defs/Severity",
+          "default": "off"
+        },
         "unused-catalog-entries": {
           "$ref": "#/$defs/Severity",
           "default": "warn"
@@ -1939,6 +1945,16 @@
             }
           ]
         },
+        "require-suppression-reason": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/Severity"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
         "unused-catalog-entries": {
           "anyOf": [
             {

package/skills/fallow/SKILL.md

@@ -172,8 +172,8 @@ Run `fallow <command> --help` for the full flag list per command (see also refer
 | `prop-drilling` | - | - | `// fallow-ignore-next-line prop-drilling` | A React/Preact prop is forwarded unchanged through 3+ pass-through components to a distant consumer; Opt-in: set rules.prop-drilling to warn or error to enable. Defaults to off. |
 | `thin-wrapper` | - | - | `// fallow-ignore-next-line thin-wrapper` | A React/Preact component whose whole body is a single spread-forwarded child render (a candidate for inlining); Opt-in: set rules.thin-wrapper to warn or error to enable. Defaults to off. |
 | `duplicate-prop-shape` | - | - | `// fallow-ignore-next-line duplicate-prop-shape` | Three or more React/Preact components across two or more files declare an identical prop-name set (a missing shared Props type); Opt-in: set rules.duplicate-prop-shape to warn or error to enable. Defaults to off. |
-| `route-collision` | - | - | - | Two or more Next.js App Router route files resolve to the same URL |
-| `dynamic-segment-name-conflict` | - | - | - | Sibling Next.js dynamic route segments use different slug names at the same position |
+| `route-collision` | - | - | `// fallow-ignore-file route-collision` | Two or more Next.js App Router route files resolve to the same URL |
+| `dynamic-segment-name-conflict` | - | - | `// fallow-ignore-file dynamic-segment-name-conflict` | Sibling Next.js dynamic route segments use different slug names at the same position |
 | `high-cyclomatic-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cyclomatic complexity |
 | `high-cognitive-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function has high cognitive complexity |
 | `high-complexity` | `--complexity` | - | `// fallow-ignore-next-line complexity` | Function exceeds both complexity thresholds |

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

@@ -504,7 +504,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -891,7 +891,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -966,7 +966,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1066,7 +1066,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1095,7 +1095,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1712,7 +1712,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1872,7 +1872,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1916,11 +1916,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.98.0",
+  "version": "2.99.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.98.0",
+    "version": "2.99.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -138,10 +138,12 @@ export type AuditGate = ("new-only" | "all")
  * Current per-instance flips:
  *
  * - `remove-catalog-entry` (`unused-catalog-entries`): `true` only when the
- *   finding's `hardcoded_consumers` array is empty. When a workspace
- *   package still pins a hardcoded version of the same package, `fallow fix`
- *   skips the entry to avoid breaking `pnpm install`, and the action is
- *   emitted with `auto_fixable: false`.
+ *   finding's `hardcoded_consumers` array is empty and the source is
+ *   `pnpm-workspace.yaml`. When a workspace package still pins a hardcoded
+ *   version of the same package, `fallow fix` skips the entry to avoid
+ *   breaking `pnpm install`. Bun `package.json` catalog entries are also
+ *   emitted with `auto_fixable: false` because the current fixer is
+ *   YAML-only.
  * - `remove-dependency` vs `move-dependency` (dependency findings): when the
  *   finding's `used_in_workspaces` array is non-empty, the primary action
  *   flips to `move-dependency` with `auto_fixable: false` (`fallow fix` will
@@ -172,7 +174,7 @@ export type IssueAction = (FixAction | SuppressLineAction | SuppressFileAction |
  * Discriminant string for [`FixAction`]. Kebab-case per the JSON output
  * contract.
  */
-export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-re-export-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override" | "resolve-policy-violation" | "move-to-server-module" | "split-mixed-barrel" | "hoist-directive" | "wire-server-action" | "provide-inject" | "use-load-data" | "render-component" | "use-component-prop" | "emit-component-event" | "wire-svelte-event" | "resolve-route-collision" | "resolve-dynamic-segment-name-conflict")
+export type FixActionType = ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-re-export-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "remove-empty-catalog-group" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference" | "remove-dependency-override" | "fix-dependency-override" | "resolve-policy-violation" | "move-to-server-module" | "split-mixed-barrel" | "hoist-directive" | "wire-server-action" | "provide-inject" | "use-load-data" | "render-component" | "use-component-prop" | "emit-component-event" | "wire-svelte-event" | "resolve-route-collision" | "resolve-dynamic-segment-name-conflict" | "add-suppression-reason" | "remove-stale-suppression")
 /**
  * Singleton discriminant for [`SuppressLineAction`].
  */
@@ -253,6 +255,10 @@ export type SuppressionOrigin = ({
  * The issue kind token from the comment (e.g., "unused-exports"), or None for blanket.
  */
 issue_kind?: (string | null)
+/**
+ * Human-authored reason after `--`, when present.
+ */
+reason?: (string | null)
 /**
  * Whether this was a file-level suppression.
  */
@@ -272,6 +278,10 @@ type: "comment"
  * The name of the export that was tagged.
  */
 export_name: string
+/**
+ * Human-authored reason after `--`, when present.
+ */
+reason?: (string | null)
 type: "jsdoc_tag"
 })
 /**
@@ -1032,24 +1042,25 @@ policy_violations?: PolicyViolationFinding[]
  */
 stale_suppressions?: StaleSuppression[]
 /**
- * Entries in pnpm-workspace.yaml's catalog: or catalogs: sections not
- * referenced by any workspace package via the catalog: protocol. Wrapped
- * in [`UnusedCatalogEntryFinding`] so each entry carries a typed
+ * Entries in package manager catalog sections not referenced by any
+ * workspace package via the catalog: protocol. Supports
+ * `pnpm-workspace.yaml` catalogs and Bun root `package.json` catalogs.
+ * Wrapped in [`UnusedCatalogEntryFinding`] so each entry carries a typed
  * `actions` array natively, with per-instance `auto_fixable` derived
- * from `hardcoded_consumers`.
+ * from `hardcoded_consumers` and the catalog source file.
  */
 unused_catalog_entries?: UnusedCatalogEntryFinding[]
 /**
- * Named groups under pnpm-workspace.yaml's catalogs: section that declare
- * no package entries. The top-level catalog: map is not reported. Wrapped
- * in [`EmptyCatalogGroupFinding`].
+ * Named groups under package manager catalogs sections that declare no
+ * package entries. The top-level catalog: map is not reported. Wrapped in
+ * [`EmptyCatalogGroupFinding`].
  */
 empty_catalog_groups?: EmptyCatalogGroupFinding[]
 /**
  * Workspace package.json references to catalogs (`catalog:` or
- * `catalog:<name>`) that do not declare the consumed package. pnpm install
- * will error until the named catalog grows to include the package or the
- * reference is switched / removed. Wrapped in
+ * `catalog:<name>`) that do not declare the consumed package. The package
+ * manager install will error until the named catalog grows to include the
+ * package or the reference is switched / removed. Wrapped in
  * [`UnresolvedCatalogReferenceFinding`] with the discriminated
  * `add-catalog-entry` / `update-catalog-reference` primary at position 0.
  */
@@ -1452,11 +1463,12 @@ type: FixActionType
  * FINDING, not per action type: the same `type` may carry
  * `auto_fixable: true` on one finding and `auto_fixable: false` on
  * another when per-instance guards in the applier discriminate (e.g.
- * `remove-catalog-entry` flips on `hardcoded_consumers`, the primary
- * dependency action flips between `remove-dependency` /
- * `move-dependency` on `used_in_workspaces`). Filter on this bool of
- * each individual action, not on `type`. See the [`IssueAction`]
- * enum-level docs for the full list of per-instance flips.
+ * `remove-catalog-entry` flips on `hardcoded_consumers` and catalog
+ * source file, the primary dependency action flips between
+ * `remove-dependency` / `move-dependency` on `used_in_workspaces`).
+ * Filter on this bool of each individual action, not on `type`. See the
+ * [`IssueAction`] enum-level docs for the full list of per-instance
+ * flips.
  */
 auto_fixable: boolean
 /**
@@ -2428,12 +2440,20 @@ line: number
  */
 col: number
 origin: SuppressionOrigin
+/**
+ * True when `rules.require-suppression-reason` reported a suppression
+ * comment or tag that has no reason.
+ */
+missing_reason?: boolean
+/**
+ * Suggested next steps. Always emitted.
+ */
+actions: IssueAction[]
 }
 /**
  * Wire-shape envelope for an [`UnusedCatalogEntry`] finding. Per-instance
- * `auto_fixable` flips to `false` when `hardcoded_consumers` is non-empty:
- * the entry cannot be removed safely while a workspace package still pins
- * the same package via a hardcoded version range.
+ * `auto_fixable` flips to `false` when `hardcoded_consumers` is non-empty or
+ * the source is not `pnpm-workspace.yaml`.
  */
 export interface UnusedCatalogEntryFinding {
 /**
@@ -2441,16 +2461,16 @@ export interface UnusedCatalogEntryFinding {
  */
 entry_name: string
 /**
- * Catalog group: `"default"` for the top-level `catalog:` map, or the
- * named catalog key for entries declared under `catalogs.<name>:`.
+ * Catalog group: `"default"` for the default catalog map, or the named
+ * catalog key for entries declared under `catalogs.<name>`.
  */
 catalog_name: string
 /**
- * Path to `pnpm-workspace.yaml`, relative to the analyzed root.
+ * Path to the catalog source file, relative to the analyzed root.
  */
 path: string
 /**
- * 1-based line number of the catalog entry within `pnpm-workspace.yaml`.
+ * 1-based line number of the catalog entry within the source file.
  */
 line: number
 /**
@@ -2472,20 +2492,20 @@ introduced?: (AuditIntroduced | null)
 }
 /**
  * Wire-shape envelope for an [`EmptyCatalogGroup`] finding. Carries a
- * straightforward `remove-empty-catalog-group` primary plus a YAML-comment
- * suppress.
+ * `remove-empty-catalog-group` primary. YAML-sourced findings also include a
+ * YAML-comment suppress action.
  */
 export interface EmptyCatalogGroupFinding {
 /**
- * Catalog group name declared under the top-level `catalogs:` map.
+ * Catalog group name declared under the `catalogs` map.
  */
 catalog_name: string
 /**
- * Path to `pnpm-workspace.yaml`, relative to the analyzed root.
+ * Path to the catalog source file, relative to the analyzed root.
  */
 path: string
 /**
- * 1-based line number of the empty group header within `pnpm-workspace.yaml`.
+ * 1-based line number of the empty group header within the source file.
  */
 line: number
 /**
@@ -2531,10 +2551,10 @@ path: string
  */
 line: number
 /**
- * Other catalogs (in the same `pnpm-workspace.yaml`) that DO declare this
- * package. Empty when no catalog has the package. Sorted lexicographically.
- * Lets agents and humans decide whether to switch the reference to a
- * different catalog or to add the entry to the named catalog.
+ * Other catalogs in the same catalog source that DO declare this package.
+ * Empty when no catalog has the package. Sorted lexicographically. Lets
+ * agents and humans decide whether to switch the reference to a different
+ * catalog or to add the entry to the named catalog.
  */
 available_in_catalogs?: string[]
 /**
@@ -7117,24 +7137,25 @@ policy_violations?: PolicyViolationFinding[]
  */
 stale_suppressions?: StaleSuppression[]
 /**
- * Entries in pnpm-workspace.yaml's catalog: or catalogs: sections not
- * referenced by any workspace package via the catalog: protocol. Wrapped
- * in [`UnusedCatalogEntryFinding`] so each entry carries a typed
+ * Entries in package manager catalog sections not referenced by any
+ * workspace package via the catalog: protocol. Supports
+ * `pnpm-workspace.yaml` catalogs and Bun root `package.json` catalogs.
+ * Wrapped in [`UnusedCatalogEntryFinding`] so each entry carries a typed
  * `actions` array natively, with per-instance `auto_fixable` derived
- * from `hardcoded_consumers`.
+ * from `hardcoded_consumers` and the catalog source file.
  */
 unused_catalog_entries?: UnusedCatalogEntryFinding[]
 /**
- * Named groups under pnpm-workspace.yaml's catalogs: section that declare
- * no package entries. The top-level catalog: map is not reported. Wrapped
- * in [`EmptyCatalogGroupFinding`].
+ * Named groups under package manager catalogs sections that declare no
+ * package entries. The top-level catalog: map is not reported. Wrapped in
+ * [`EmptyCatalogGroupFinding`].
  */
 empty_catalog_groups?: EmptyCatalogGroupFinding[]
 /**
  * Workspace package.json references to catalogs (`catalog:` or
- * `catalog:<name>`) that do not declare the consumed package. pnpm install
- * will error until the named catalog grows to include the package or the
- * reference is switched / removed. Wrapped in
+ * `catalog:<name>`) that do not declare the consumed package. The package
+ * manager install will error until the named catalog grows to include the
+ * package or the reference is switched / removed. Wrapped in
  * [`UnresolvedCatalogReferenceFinding`] with the discriminated
  * `add-catalog-entry` / `update-catalog-reference` primary at position 0.
  */