fallow 2.88.3 → 2.89.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.88.3",
+  "version": "2.89.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, 96 framework plugins.",
   "license": "MIT",
   "repository": {
@@ -83,13 +83,13 @@
     "@tanstack/intent": "0.0.41"
   },
   "optionalDependencies": {
-    "@fallow-cli/darwin-arm64": "2.88.3",
-    "@fallow-cli/darwin-x64": "2.88.3",
-    "@fallow-cli/linux-x64-gnu": "2.88.3",
-    "@fallow-cli/linux-arm64-gnu": "2.88.3",
-    "@fallow-cli/linux-x64-musl": "2.88.3",
-    "@fallow-cli/linux-arm64-musl": "2.88.3",
-    "@fallow-cli/win32-arm64-msvc": "2.88.3",
-    "@fallow-cli/win32-x64-msvc": "2.88.3"
+    "@fallow-cli/darwin-arm64": "2.89.0",
+    "@fallow-cli/darwin-x64": "2.89.0",
+    "@fallow-cli/linux-x64-gnu": "2.89.0",
+    "@fallow-cli/linux-arm64-gnu": "2.89.0",
+    "@fallow-cli/linux-x64-musl": "2.89.0",
+    "@fallow-cli/linux-arm64-musl": "2.89.0",
+    "@fallow-cli/win32-arm64-msvc": "2.89.0",
+    "@fallow-cli/win32-x64-msvc": "2.89.0"
   }
 }

package/skills/fallow/SKILL.md

@@ -122,7 +122,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 | `find_dupes` | Code duplication detection. Set `changed_since` to scope to changed files since a git ref. Set `min_occurrences` (≥ 2, default 2) to hide pair-only clones and focus on widespread copy-paste; JSON gains `stats.clone_groups_below_min_occurrences` when the filter hides anything. Each `clone_groups[]` entry carries a stable `fingerprint`, usually `dup:<8hex>` and widened only on rare report collisions; pass it to `trace_clone` to deep-dive that group |
 | `fix_preview` | Dry-run auto-fix preview |
 | `fix_apply` | Apply auto-fixes (destructive) |
-| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
+| `check_health` | Complexity metrics, health scores, hotspots, and refactoring targets. Set `complexity_breakdown: true` to add a per-decision-point `contributions[]` array to each complexity finding (each `else-if`, nested `if`, boolean operator, loop, `case`, etc. with its source line and cyclomatic/cognitive weight) so you can explain WHY a function scored high and pinpoint refactor targets. Optional `runtime_coverage` merges a V8 or Istanbul dump; tune it with `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), and `low_traffic_threshold` (default 0.001). When runtime evidence combines with static usage, test coverage, CRAP/complexity, ownership, or change scope, read `coverage_intelligence` for stable `fallow:coverage-intel:<hash>` recommendations. Set `group_by` to `owner`, `directory`, `package`, or `section` for per-group `vital_signs` / `health_score`; SARIF results gain `properties.group`, CodeClimate issues gain a top-level `group` field |
 | `check_runtime_coverage` | Merge V8 or Istanbul runtime-coverage data into the health report. One local capture is free; continuous/cloud or multi-capture runtime monitoring is paid. Required `coverage` param (V8 dir, V8 JSON, or Istanbul `coverage-final.json`). Tuning knobs: `min_invocations_hot` (default 100), `min_observation_volume` (default 5000), `low_traffic_threshold` (default 0.001), `max_crap` (default 30.0), `top`, `group_by`. Cloud runtime rows can expose `resolutionStatus` / `mappingQuality` on function-list JSON and `resolution_status` / `mapping_quality` in runtime-context JSON. Use `coverage_intelligence` and the confidence table below before acting on file-level runtime signals. Long dumps may exceed the 120s MCP timeout; raise `FALLOW_TIMEOUT_SECS`. Pick this over `check_health` when you have a coverage dump. |
 | `get_hot_paths` | Runtime-context slice over the same runtime coverage pipeline. Same params as `check_runtime_coverage`; read `runtime_coverage.hot_paths` for production hot paths. |
 | `get_blast_radius` | Runtime-context slice for blast-radius review. Same params as `check_runtime_coverage`; read `runtime_coverage.blast_radius` for stable `fallow:blast:<hash>` IDs, caller counts, traffic-weighted caller reach, optional cloud deploy touch counts, and low/medium/high risk bands. |

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

@@ -51,7 +51,14 @@ Analyzes the project for unused files, exports, dependencies, types, members, an
 | `--workspace` | string | — | Scope to one or more workspaces. Comma-separated values, globs (`apps/*`, `@scope/*`), and `!`-prefixed negation (`!apps/legacy`) supported. Matched against package name AND workspace path relative to repo root. |
 | `--changed-workspaces` | string (git ref) | — | Git-derived monorepo CI scoping: scope to workspaces containing any file changed since `REF` (e.g. `origin/main`). Auto-derives the workspace set from `git diff`. Mutually exclusive with `--workspace`. Missing ref is a hard error (exit 2), not silent full-scope fallback. |
 | `--include-dupes` | bool | `false` | Cross-reference with duplication findings |
+| `--dupes-mode` | enum | `config` | Override duplicate detection mode in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --mode`. |
+| `--dupes-threshold` | number | `config` | Override the duplication percentage failure threshold in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --threshold`. |
+| `--dupes-min-tokens` | number | `config` | Override the minimum token count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-tokens`. |
+| `--dupes-min-lines` | number | `config` | Override the minimum line count for clone detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --min-lines`. |
 | `--dupes-min-occurrences` | number | `config` | Override the minimum clone occurrences in combined mode (must be >= 2). Falls back to the config value when unset. Mirrors the standalone `dupes --min-occurrences`. |
+| `--dupes-skip-local` | bool | `config` | Only report cross-directory duplicates in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --skip-local`. |
+| `--dupes-cross-language` | bool | `config` | Enable TypeScript to JavaScript duplicate matching in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --cross-language`. |
+| `--dupes-ignore-imports` | bool | `config` | Exclude import declarations from duplicate detection in combined mode. Falls back to the config value when unset. Mirrors the standalone `dupes --ignore-imports`. |
 | `--file` | path (multiple) | — | Scope output to specific files. Only issues in the specified files are reported. Project-wide dependency issues are suppressed. Warns on non-existent paths. Useful for lint-staged |
 | `--include-entry-exports` | bool | `false` | Report unused exports in entry files (package.json `main`/`exports`, framework pages). Catches typos like `meatdata` vs `metadata`. Global flag, also accepted on combined mode (`fallow --include-entry-exports`) and `fallow audit`. Also configurable as `includeEntryExports: true` in fallow config |
 | `--trace` | `FILE:EXPORT` | — | Trace export usage chain |
@@ -368,6 +375,7 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--top` | number | — | Only show the top N most complex functions (and file scores/hotspots/targets) |
 | `--sort` | `cyclomatic\|cognitive\|lines\|severity` | `cyclomatic` | Sort order for complexity findings |
 | `--complexity` | bool | `false` | Show only function complexity findings. When no section flags are set, all sections are shown by default. |
+| `--complexity-breakdown` | bool | `false` | Add a per-decision-point `contributions[]` array to each complexity finding in `--format json`. Each entry names the construct (`if`, `else-if`, `ternary`, boolean operator, loop, `case`, `catch`, `optional-chain`, ...) and carries its source line, the metric it adds to (`cyclomatic` or `cognitive`), its weight, and the nesting depth, so a consumer can explain WHY a function scored high. Off by default (no change to existing JSON/SARIF/markdown). Used by the VS Code inline editor breakdown and the MCP `check_health` `complexity_breakdown` param. |
 | `--file-scores` | bool | `false` | Show only per-file health scores (maintainability index, LOC, fan-in, fan-out, dead code ratio, complexity density, CRAP risk). Runs the full analysis pipeline. Sorted by risk-aware triage concern: lower maintainability index and higher CRAP risk first. When no section flags are set, all sections are shown by default. |
 | `--hotspots` | bool | `false` | Show only hotspots: files that are both complex and frequently changing. Combines git churn history with complexity data. Requires a git repository. When no section flags are set, all sections are shown by default. |
 | `--targets` | bool | `false` | Show only refactoring targets: ranked recommendations based on complexity, coupling, churn, and dead code signals. Categories: churn+complexity, circular dep, high impact, dead code, complexity, coupling. When no section flags are set, all sections are shown by default. |
@@ -376,8 +384,9 @@ Angular templates contribute synthetic `<template>` complexity findings whenever
 | `--min-score` | number | — | Fail (exit 1) only when the health score is below this threshold. Implies `--score`. Authoritative CI quality gate: when set, complexity findings are demoted to informational and the exit code is driven solely by the score, so `--min-score 0` always exits 0. Composes with `--min-severity`. |
 | `--min-severity` | `moderate\|high\|critical` | — | Only exit with an error for findings at or above this severity. Composes with `--min-score` (the run fails if either gate trips). |
 | `--report-only` | bool | `false` | Print the score and findings but never fail CI (always exit 0). Advisory mode. Mutually exclusive with `--min-score` and `--min-severity`. |
-| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). |
+| `--since` | string | `6m` | Git history window for hotspot analysis. Accepts durations (`6m`, `90d`, `1y`, `2w`) or ISO dates (`2025-06-01`). Ignored when `--churn-file` is set. |
 | `--min-commits` | number | `3` | Minimum number of commits for a file to be included in hotspot ranking. |
+| `--churn-file` | string | (none) | Import change history from a `fallow-churn/v1` JSON file (`{schema, events:[{path, timestamp, author, added, deleted}]}`, one entry per changed file per commit) instead of `git log`, so `--hotspots`/`--ownership`/`--targets` work on non-git VCS (Yandex Arc, Mercurial, Perforce). Resolved relative to `--root`; wins over git. Authoritative for the window, so `--since` then only labels output. Malformed file exits 2; `audit`/`impact`/`--changed-since` still require git. |
 | `--ownership` | bool | `false` | Attach ownership signals to hotspot entries: bus factor (Avelino truck factor), contributor count, top contributor with stale-days, recent contributors (top-3), `suggested_reviewers`, declared CODEOWNERS owner, `ownership_state`, ownership drift, unowned-hotspot detection. Human output gains a project-level summary line. JSON adds `low-bus-factor`, `unowned-hotspot`, `ownership-drift` action types. Test files get a `[test]` tag. Implies `--hotspots`. Requires git. |
 | `--ownership-emails` | `raw\|handle\|anonymized\|hash` | `handle` | Privacy mode for author emails. `handle` shows the local-part only (default, with GitHub noreply unwrap and deterministic same-handle disambiguation). `anonymized` emits stable `xxh3:` pseudonyms; `hash` remains accepted as the legacy spelling. `raw` shows full addresses. Use `anonymized` in regulated environments. Implies `--ownership`. Configure default via `health.ownership.emailMode`. |
 | `--changed-since` | string | — | Only analyze files changed since a git ref |
@@ -486,7 +495,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -876,7 +885,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -949,7 +958,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -1389,6 +1398,7 @@ Available on all commands:
 | `FALLOW_EXTENDS_TIMEOUT_SECS` | Timeout for fetching remote config inheritance in seconds (default: `5`). Do not raise this for untrusted sources. |
 | `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_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. |
 | `FALLOW_COMMAND` | GitLab CI: command to run (default: `dead-code`). |
 | `FALLOW_FAIL_ON_ISSUES` | GitLab CI: set to `true` to exit 1 if issues found. |
 | `FALLOW_CHANGED_SINCE` | GitLab CI: git ref for incremental analysis. Auto-detected in MR pipelines. |
@@ -1488,7 +1498,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1648,7 +1658,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1692,11 +1702,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.88.3",
+  "version": "2.89.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.88.3",
+    "version": "2.89.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/types/output-contract.d.ts

@@ -353,6 +353,18 @@ export type CoverageTier = ("none" | "partial" | "high")
  * Provenance of a CRAP finding's coverage signal.
  */
 export type CoverageSource = ("istanbul" | "estimated" | "estimated_component_inherited")
+/**
+ * Which complexity metric a [`ComplexityContribution`] adds to.
+ */
+export type ComplexityMetric = ("cyclomatic" | "cognitive")
+/**
+ * The syntactic construct that produced a single complexity increment.
+ *
+ * Mirrors `SonarSource` cognitive-complexity vocabulary where it overlaps.
+ * `Case` means a `case` label carrying a test; a bare `default` adds nothing
+ * to cyclomatic complexity and so produces no contribution.
+ */
+export type ComplexityContributionKind = ("if" | "else" | "else-if" | "ternary" | "logical-and" | "logical-or" | "nullish-coalescing" | "logical-assignment" | "optional-chain" | "for" | "for-in" | "for-of" | "while" | "do-while" | "switch" | "case" | "catch" | "labeled-break" | "labeled-continue")
 /**
  * Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
  * emitted by `build_health_finding_actions`. A single finding's `actions`
@@ -1654,6 +1666,15 @@ line: number
  * 0-based byte column offset of the import that starts the cycle.
  */
 col: number
+/**
+ * Per-file import anchors, one entry per hop in cycle order: `edges[i]`
+ * is the import in `files[i]` pointing to `files[(i + 1) % len]`. Always
+ * the same length as `files`. Drives the per-file LSP diagnostic
+ * squiggly. `#[serde(default)]` so pre-`edges` baselines deserialize;
+ * always emitted on output but intentionally not in the schema's
+ * `required` set (see the struct doc).
+ */
+edges?: CircularDependencyEdge[]
 /**
  * Whether this cycle crosses workspace package boundaries.
  */
@@ -1669,6 +1690,34 @@ actions: IssueAction[]
  */
 introduced?: (AuditIntroduced | null)
 }
+/**
+ * One import hop in a circular dependency: the file containing the import
+ * and where that import statement sits.
+ *
+ * `edges[i]` is the import IN `path` (the hop SOURCE, equal to the cycle's
+ * `files[i]`) that points to the NEXT file in the cycle
+ * (`files[(i + 1) % files.len()]`); the target is not repeated here to keep
+ * the wire compact. Enables a per-file diagnostic squiggly anchored under
+ * the offending import rather than a single squiggly on the first file.
+ *
+ * `col` is a 0-based BYTE column, matching the cycle's top-level `col`;
+ * converting it to a UTF-16 code-unit column for LSP clients is a tracked
+ * follow-up shared with the existing field.
+ */
+export interface CircularDependencyEdge {
+/**
+ * The file containing the import (the hop SOURCE; equal to `files[i]`).
+ */
+path: string
+/**
+ * 1-based line number of the import statement pointing to the next file.
+ */
+line: number
+/**
+ * 0-based byte column offset of the import statement.
+ */
+col: number
+}
 /**
  * Wire-shape envelope for a [`ReExportCycle`] finding. Mirrors
  * [`CircularDependencyFinding`]: flattens the bare finding and carries a
@@ -2200,6 +2249,15 @@ line_count: number
  * each group in the human listing.
  */
 fingerprint: string
+/**
+ * Best-effort human-readable name for the clone: the dominant repeated
+ * identifier across the duplicated fragment (e.g. a shared `parseCsv`
+ * function). `None` when the clone has no clear dominant name (generic or
+ * tied identifiers); consumers then fall back to a file-based label. Lets
+ * editors and agents label a clone by what it is rather than an opaque
+ * ordinal.
+ */
+suggested_name?: (string | null)
 /**
  * Suggested next steps: an `extract-shared` primary and a
  * `suppress-line` secondary. Always emitted (possibly empty for
@@ -2534,6 +2592,13 @@ coverage_tier?: (CoverageTier | null)
 coverage_source?: (CoverageSource | null)
 inherited_from?: (string | null)
 component_rollup?: (ComponentRollup | null)
+/**
+ * Per-decision-point complexity breakdown explaining WHICH constructs drove
+ * the cyclomatic and cognitive scores. Populated only when the caller opts
+ * in via `health --complexity-breakdown`; empty (and omitted from JSON)
+ * otherwise so default and CI output stay lean.
+ */
+contributions?: ComplexityContribution[]
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -2553,6 +2618,36 @@ template_path: string
 template_cyclomatic: number
 template_cognitive: number
 }
+/**
+ * A single complexity increment, located at its source line/column.
+ *
+ * `weight` is the amount this construct added to `metric`; for nested
+ * cognitive increments `weight == 1 + nesting`. Consumers that render inline
+ * (the VS Code editor breakdown) group contributions by `line` and sum the
+ * weights, deferring the per-kind list to a hover.
+ */
+export interface ComplexityContribution {
+/**
+ * 1-based line number where the construct begins.
+ */
+line: number
+/**
+ * 0-based byte column where the construct begins.
+ */
+col: number
+metric: ComplexityMetric
+kind: ComplexityContributionKind
+/**
+ * The amount added to `metric` at this site (`1 + nesting` for nested
+ * cognitive increments, otherwise `1`).
+ */
+weight: number
+/**
+ * The nesting depth at the increment site (`0` when not nested). Lets a
+ * consumer explain a cognitive `+3` as "+1 base, +2 nesting".
+ */
+nesting: number
+}
 /**
  * Suggested action attached to a [`ComplexityViolation`].
  *