fallow 3.15.0 → 3.16.0

package/capabilities.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "manifest_version": "1",
   "description": "Codebase analyzer for TypeScript/JavaScript: unused code, circular dependencies, code duplication, complexity hotspots, and architecture boundary violations",
   "global_flags": [
@@ -6006,9 +6006,9 @@
     "rule_pack_schema_command": "fallow rule-pack-schema",
     "rule_pack_schema_note": "JSON Schema for a declarative rule pack referenced from rulePacks.",
     "plugin_schema_command": "fallow plugin-schema",
-    "plugin_schema_note": "JSON Schema for a user-authored external plugin (fallow-plugin-*.jsonc). Teach fallow about an unsupported framework declaratively: detection, entryPoints, alwaysUsed, usedExports, usedClassMembers, and manifestEntries (derive entry points from per-package manifest files).",
+    "plugin_schema_note": "JSON Schema for a user-authored external plugin (fallow-plugin-*.jsonc). Teach fallow about an unsupported framework declaratively: detection, entryPoints, alwaysUsed, usedExports, usedClassMembers, and manifestEntries (derive entry points from per-package manifest files, including typed [*] traversal and exists predicates).",
     "plugin_check_command": "fallow plugin-check",
-    "plugin_check_note": "Read-only dry-run of your external plugins: reports which activated, which manifests each manifestEntries rule matched, what it seeded (with path-exists), and typed warnings (manifests-matched-none, when-excluded-all, field-path-unresolved, entries-empty, manifest-parse-failed, entry-outside-root, seeded-paths-missing). Run it after authoring a fallow-plugin-*.jsonc to verify it before a full analysis.",
+    "plugin_check_note": "Read-only dry-run of your external plugins: reports which activated, which manifests each manifestEntries rule matched, what it seeded (with path-exists), and typed warnings (manifests-matched-none, when-excluded-all, field-path-unresolved, entries-empty, manifest-parse-failed, field-values-limit-exceeded, entry-expansion-limit-exceeded, entry-outside-root, seeded-paths-missing). Run it after authoring a fallow-plugin-*.jsonc to verify it before a full analysis.",
     "config_files": [
       ".fallowrc.json",
       ".fallowrc.jsonc",

package/package.json

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

package/schema.json

@@ -569,9 +569,11 @@
           "default": "jsonc"
         },
         "when": {
-          "description": "Manifest-level gate: a map of dotted field path to an expected scalar\nvalue. ALL entries must match by STRICT EQUALITY for the manifest to be\nprocessed. An empty map matches every manifest.",
+          "description": "Manifest-level gate: a map of field path to an equality expectation or\nan explicit `exists` predicate. Paths use dotted object keys and may\ntraverse arrays with `[*]`. ALL entries must match; a wildcard equality\nmatches when any yielded value equals the expectation. An empty map\nmatches every manifest.",
           "type": "object",
-          "additionalProperties": true,
+          "additionalProperties": {
+            "$ref": "#/$defs/ManifestCondition"
+          },
           "default": {}
         },
         "entries": {
@@ -602,18 +604,46 @@
         }
       ]
     },
+    "ManifestCondition": {
+      "description": "A typed condition used by a manifest entry gate.\n\nPlain JSON values retain strict equality semantics. The reserved\n`{ \"exists\": bool }` object tests field presence without truthiness.",
+      "anyOf": [
+        {
+          "description": "Require the field path to resolve (`true`) or not resolve (`false`).",
+          "$ref": "#/$defs/ManifestExistsPredicate"
+        },
+        {
+          "description": "Require at least one yielded value to equal this JSON value exactly."
+        }
+      ]
+    },
+    "ManifestExistsPredicate": {
+      "description": "The explicit field-presence predicate accepted by [`ManifestCondition`].",
+      "type": "object",
+      "properties": {
+        "exists": {
+          "description": "Whether the field path must resolve to at least one value.",
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": [
+        "exists"
+      ]
+    },
     "ManifestSeedRule": {
       "description": "A single entry seeded by a [`ManifestEntryRule`], resolved relative to the\nmanifest's directory.",
       "type": "object",
       "properties": {
         "path": {
-          "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values (a missing or empty field seeds nothing). The glob\nmust encode its own extension (e.g. `public/index.{ts,tsx}`); glob entry\npatterns are matched literally against discovered files without\nsource-extension probing.",
+          "description": "Entry glob relative to the manifest directory. May contain\n`${dotted.field}` interpolation that fans out over string / array\nmanifest field values; `[*]` traverses object arrays. A missing or empty\nfield seeds nothing. The glob must encode its own extension, such as\n`public/index.{ts,tsx}`. Glob entry patterns are matched literally\nagainst discovered files without\nsource-extension probing.",
           "type": "string"
         },
         "when": {
-          "description": "Per-entry gate (strict equality), evaluated against the same manifest.\nAn empty map always passes.",
+          "description": "Per-entry gate, using the same strict equality and `[*]` traversal as the\nmanifest-level gate. An empty map always passes.",
           "type": "object",
-          "additionalProperties": true,
+          "additionalProperties": {
+            "$ref": "#/$defs/ManifestCondition"
+          },
           "default": {}
         }
       },
@@ -977,7 +1007,7 @@
           "default": 15
         },
         "maxCrap": {
-          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings only, never the health score.",
+          "description": "Maximum allowed CRAP (Change Risk Anti-Patterns) score per function\n(default: 30.0). CRAP combines cyclomatic complexity with test\ncoverage: high complexity plus low coverage produces a high CRAP\nscore. Functions meeting or exceeding this threshold are reported.\nUse `--coverage` with Istanbul data for accurate per-function CRAP;\notherwise fallow estimates coverage from the module graph. Governs\nfindings and the threshold-relative file-score signals\n(`crap_above_threshold`, the `risk` triage tag, and the\n`add_test_coverage` refactoring target); measured values such as\n`crap_max` and the overall health score never move with it. Set to\n`0` to disable CRAP enforcement entirely: no findings, nothing counts\nabove threshold, and file-score rows disclose baseline breaches as\nexempt instead.",
           "type": "number",
           "format": "double",
           "default": 30.0

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

@@ -521,7 +521,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -595,7 +595,7 @@ With `--file-scores`, the JSON output also includes `file_scores` array and `sum
 
 The `file_scores` array is sorted by risk-aware triage concern: the larger of low-MI concern and CRAP risk. This keeps files with very high untested complexity near the top even when their Maintainability Index is not the lowest.
 
-The `crap_max` field is the highest CRAP (Change Risk Anti-Patterns) score among functions in the file, using the canonical formula `CC^2 * (1 - cov/100)^3 + CC`. The default model (`static_estimated`) estimates per-function coverage from export references: directly test-referenced = 85%, indirectly test-reachable = 40%, untested = 0%. Provide `--coverage <path>` with Istanbul-format `coverage-final.json` for exact scores (`istanbul` model). The `crap_above_threshold` field counts functions with CRAP >= 30. When `--file-scores` is active, `summary.coverage_model` indicates the model used (`"static_estimated"` or `"istanbul"`). When CRAP findings carry `coverage_source`, `summary.coverage_source_consistency` is `uniform` or `mixed`; grouped health JSON mirrors this as `groups[].coverage_source_consistency`.
+The `crap_max` field is the highest CRAP (Change Risk Anti-Patterns) score among functions in the file, using the canonical formula `CC^2 * (1 - cov/100)^3 + CC`. It is always the raw measured value. The default model (`static_estimated`) estimates per-function coverage from export references: directly test-referenced = 85%, indirectly test-reachable = 40%, untested = 0%. Provide `--coverage <path>` with Istanbul-format `coverage-final.json` for exact scores (`istanbul` model). The `crap_above_threshold` field counts functions whose rounded CRAP meets or exceeds their effective ceiling, resolved from `health.thresholdOverrides` over the global `maxCrap` / `--max-crap` value (default 30); it is 0 when CRAP enforcement is disabled (`maxCrap: 0`). Rows whose breaches were let through by configuration carry two additional fields: `crap_exempted` (functions at or above the canonical 30 baseline but below their effective ceiling; omitted when 0) and `crap_effective_threshold` (the lowest effective ceiling among the file's functions, present only when it differs from `summary.max_crap_threshold`). When `--file-scores` is active, `summary.coverage_model` indicates the model used (`"static_estimated"` or `"istanbul"`). When CRAP findings carry `coverage_source`, `summary.coverage_source_consistency` is `uniform` or `mixed`; grouped health JSON mirrors this as `groups[].coverage_source_consistency`.
 
 Maintainability index formula: `100 - (complexity_density × 30) - (dead_code_ratio × 20) - min(ln(fan_out+1) × 4, 15)`, clamped to 0–100. Higher is better. Type-only exports are excluded from dead_code_ratio. Zero-function files (barrels) are excluded by default.
 
@@ -668,7 +668,7 @@ With `--targets`, the JSON output includes a `targets` array with ranked refacto
 
 Targets are sorted by `efficiency` (priority / effort_numeric) descending, surfacing quick wins first. The `target_thresholds` object exposes the adaptive percentile-based thresholds used for scoring. Priority formula: `min(complexity_density, 1) x 30 + hotspot_boost x 25 + dead_code_ratio x 20 + fan_in_norm x 15 + fan_out_norm x 10`, clamped to 0-100. Fan-in and fan-out normalization uses the project's p95 values (with floors). Categories: `urgent_churn_complexity`, `break_circular_dependency`, `split_high_impact`, `remove_dead_code`, `extract_complex_functions`, `extract_dependencies`, `add_test_coverage`. Each target includes `efficiency`, `effort` (low/medium/high), `confidence` (high/medium/low, data source reliability), and contributing `factors`.
 
-The `add_test_coverage` category fires when a file has 2+ functions with CRAP scores >= 30 and complexity density > 0.3. The `crap_max` metric appears in contributing factors for these targets.
+The `add_test_coverage` category fires when a file has 2+ functions whose rounded CRAP meets or exceeds their effective ceiling (`health.thresholdOverrides` over the global `maxCrap` / `--max-crap`, default 30) and complexity density > 0.3. A file whose breaching functions are all exempted by configuration produces no target. The `crap_max` metric appears in contributing factors for these targets, with `threshold` set to the file's lowest effective ceiling (the run global when no override applies).
 
 ### Vital Signs
 
@@ -919,7 +919,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -996,7 +996,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1097,7 +1097,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1126,7 +1126,7 @@ fallow security --gate newly-reachable --changed-since origin/main
 {
   "kind": "security",
   "schema_version": "4",
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 42,
   "config": {
     "rules": {
@@ -1361,7 +1361,7 @@ fallow plugin-schema > plugin-schema.json
 
 ## `plugin-check`: Verify external plugins
 
-Read-only dry-run of your external plugins. Reports, per plugin, whether it activated (with the unmet `detection`/`enabler` requirement when inactive), and for `manifestEntries` rules which manifests each matched, what it seeded (with `path_exists`), and typed warnings (`manifests-matched-none`, `when-excluded-all`, `field-path-unresolved`, `entries-empty`, `manifest-parse-failed`, `entry-outside-root`, `seeded-paths-missing`). Run it after authoring a `fallow-plugin-*.jsonc` to verify it before a full analysis. Deterministic output; always exits 0 (advisory, never a gate).
+Read-only dry-run of your external plugins. Reports, per plugin, whether it activated (with the unmet `detection`/`enabler` requirement when inactive), and for `manifestEntries` rules which manifests each matched, what it seeded (with `path_exists`), and typed warnings (`manifests-matched-none`, `when-excluded-all`, `field-path-unresolved`, `entries-empty`, `manifest-parse-failed`, `field-values-limit-exceeded`, `entry-expansion-limit-exceeded`, `entry-outside-root`, `seeded-paths-missing`). Run it after authoring a `fallow-plugin-*.jsonc` to verify it before a full analysis. Deterministic output; always exits 0 (advisory, never a gate).
 
 ```bash
 fallow plugin-check --format json
@@ -1891,7 +1891,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -2051,7 +2051,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -2095,11 +2095,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "3.15.0",
+  "version": "3.16.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "3.15.0",
+    "version": "3.16.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -273,7 +273,9 @@ export type AddToConfigValue = (string | IgnoreExportsRule[] | {
  * means it was inherited. Duplication findings carry one carve-out: a clone
  * group whose structural key is new but whose instances contain no added line
  * from the diff (a group re-shaped by removing duplication elsewhere) is
- * demoted to inherited and serializes `false` (issue #2164).
+ * demoted to inherited and serializes `false` (issue #2164). Such demoted
+ * groups additionally carry a `demotion_reason` field naming the rule, and
+ * are counted in `attribution.duplication_demoted` (issue #2220).
  *
  * Outside of audit sub-results the field is omitted, so call sites typically
  * hold `Option<AuditIntroduced>`. Renders to the JSON wire as a bare boolean.
@@ -445,6 +447,15 @@ kind: "source-read-failure"
  * emitted by the legacy `build_clone_group_actions` walker.
  */
 export type CloneGroupActionType = ("extract-shared" | "suppress-line")
+/**
+ * Why the audit new-only gate demoted an introduced clone group to
+ * inherited. Serializes as a kebab-case string on the wire (for example
+ * `"no-added-lines"`).
+ *
+ * Further variants may be added in later releases; consumers should treat an
+ * unknown value as "some demotion reason" rather than failing.
+ */
+export type CloneDemotionReason = "no-added-lines"
 /**
  * The kind of refactoring suggested for a clone family.
  */
@@ -1157,6 +1168,7 @@ duplication_introduced: number
 duplication_inherited: number
 styling_introduced: number
 styling_inherited: number
+duplication_demoted: number
 }
 /**
  * Metric and rule definitions emitted under `_meta` when `--explain` is
@@ -4891,6 +4903,13 @@ actions: CloneGroupAction[]
  * to the merge-base. `None` when serialized directly from Rust.
  */
 introduced?: (AuditIntroduced | null)
+/**
+ * Set only by `fallow audit` under `--gate new-only`, on groups whose
+ * `introduced` flag the gate demoted to `false`: why the demotion
+ * happened. `None` everywhere else, including `fallow dupes
+ * --format json` (issue #2220).
+ */
+demotion_reason?: (CloneDemotionReason | null)
 }
 /**
  * A single instance of duplicated code at a specific location.
@@ -5759,6 +5778,12 @@ cognitive: number
  * Current CRAP score, when coverage data exists.
  */
 crap?: (number | null)
+/**
+ * Measured line count of the matched unit. Present on complexity rows,
+ * where `maxUnitSize` participates in the dimension; absent on CRAP rows
+ * and `<component>` rollup rows, which are never scored on unit size.
+ */
+line_count?: (number | null)
 }
 /**
  * Project-wide vital signs: a fixed set of metrics for trend tracking.
@@ -6134,13 +6159,31 @@ function_count: number
  */
 lines: number
 /**
- * Highest CRAP score among the file's functions.
+ * Highest CRAP score among the file's functions. Always the raw measured
+ * value; threshold overrides never rewrite it.
  */
 crap_max: number
 /**
- * Functions whose CRAP score exceeds the threshold.
+ * Functions whose rounded CRAP score meets or exceeds their effective
+ * ceiling, resolved from `health.thresholdOverrides` over the global
+ * `maxCrap` / `--max-crap` value. Zero when CRAP enforcement is disabled
+ * (global ceiling `0`).
  */
 crap_above_threshold: number
+/**
+ * Functions whose rounded CRAP score is at or above the canonical 30.0
+ * baseline but below their effective ceiling: the count the configuration
+ * let through. Stays `0` when the effective ceiling is stricter than 30.
+ * When CRAP enforcement is disabled (global ceiling `0`), counts every
+ * function at or above the canonical baseline. Omitted when zero.
+ */
+crap_exempted?: number
+/**
+ * Lowest effective CRAP ceiling among the file's functions, present only
+ * when it differs from the run global (`summary.max_crap_threshold`).
+ * Consumers fall back to `summary.max_crap_threshold` when absent.
+ */
+crap_effective_threshold?: (number | null)
 }
 /**
  * Static test coverage gaps derived from the module graph. Shows runtime files
@@ -8971,6 +9014,7 @@ file: string
  * The export name being traced.
  */
 export_name: string
+namespace?: SemanticNamespace
 /**
  * Whether the file is reachable from an entry point.
  */