fallow 2.86.0 → 2.87.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fallow",
-  "version": "2.86.0",
+  "version": "2.87.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.86.0",
-    "@fallow-cli/darwin-x64": "2.86.0",
-    "@fallow-cli/linux-x64-gnu": "2.86.0",
-    "@fallow-cli/linux-arm64-gnu": "2.86.0",
-    "@fallow-cli/linux-x64-musl": "2.86.0",
-    "@fallow-cli/linux-arm64-musl": "2.86.0",
-    "@fallow-cli/win32-arm64-msvc": "2.86.0",
-    "@fallow-cli/win32-x64-msvc": "2.86.0"
+    "@fallow-cli/darwin-arm64": "2.87.0",
+    "@fallow-cli/darwin-x64": "2.87.0",
+    "@fallow-cli/linux-x64-gnu": "2.87.0",
+    "@fallow-cli/linux-arm64-gnu": "2.87.0",
+    "@fallow-cli/linux-x64-musl": "2.87.0",
+    "@fallow-cli/linux-arm64-musl": "2.87.0",
+    "@fallow-cli/win32-arm64-msvc": "2.87.0",
+    "@fallow-cli/win32-x64-msvc": "2.87.0"
   }
 }

package/skills/fallow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fallow
-description: Codebase intelligence for JavaScript and TypeScript. Free static layer reports quality, changed-code risk, cleanup opportunities (unused files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 114 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, audit PR risk, find cleanup opportunities or unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, surface security candidates, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
+description: Codebase intelligence for JavaScript and TypeScript. Free static layer reports quality, changed-code risk, cleanup opportunities (unused files, exports, types, dependencies), code duplication, circular dependencies, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same health report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 118 framework plugins, zero configuration, sub-second static analysis. Use when asked to analyze code health, audit PR risk, find cleanup opportunities or unused code, detect duplicates, check circular dependencies, audit complexity, check architecture boundaries, detect feature flags, surface security candidates, clean up the codebase, auto-fix issues, merge runtime coverage, or run fallow.
 license: MIT
 metadata:
   author: Bart Waardenburg
@@ -10,7 +10,7 @@ metadata:
 
 # Fallow: codebase intelligence for JavaScript and TypeScript
 
-Codebase intelligence for JavaScript and TypeScript. The free static layer reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 114 framework plugins, zero configuration, sub-second static analysis.
+Codebase intelligence for JavaScript and TypeScript. The free static layer reports quality, changed-code risk, cleanup opportunities, circular dependencies, code duplication, complexity hotspots, architecture boundary violations, feature flag patterns, and opt-in security candidates. Runtime coverage merges production execution data into the same `fallow health` report for hot-path review, cold-path deletion confidence, and stale-flag evidence, with a single local capture available by default and continuous/cloud runtime monitoring available as an optional mode. 118 framework plugins, zero configuration, sub-second static analysis.
 
 ## When to Use
 
@@ -30,7 +30,7 @@ Codebase intelligence for JavaScript and TypeScript. The free static layer repor
 - Runtime error analysis or debugging
 - Type checking (use `tsc` for that)
 - Linting style or formatting issues (use ESLint, Biome, Prettier)
-- Security vulnerability scanning
+- Verified security vulnerability scanning or SAST. `fallow security` surfaces local, deterministic security *candidates* for a downstream agent to verify; it does not prove exploitability. Use Snyk, CodeQL, or Semgrep for verified scanning, and an SCA tool for dependency CVEs.
 - Bundle size analysis
 - Projects that are not JavaScript or TypeScript
 
@@ -75,7 +75,7 @@ cargo install fallow-cli        # build from source
 | `health` | Function complexity analysis (also covers Angular templates as synthetic `<template>` findings: external `.html` files via `templateUrl` AND inline `@Component({ template: \`...\` })` literals; suppress external with `<!-- fallow-ignore-file complexity -->` at the top of the `.html` file, suppress inline with `// fallow-ignore-next-line complexity` directly above the `@Component` decorator) | `--complexity`, `--max-cyclomatic`, `--max-cognitive`, `--max-crap`, `--top`, `--sort`, `--file-scores`, `--hotspots`, `--ownership`, `--ownership-emails`, `--targets`, `--effort`, `--score`, `--min-score`, `--since`, `--min-commits`, `--save-snapshot`, `--trend`, `--coverage-gaps`, `--coverage`, `--coverage-root`, `--runtime-coverage`, `--min-invocations-hot`, `--min-observation-volume`, `--low-traffic-threshold`, `--workspace`, `--changed-workspaces`, `--baseline`, `--save-baseline` |
 | `audit` | Combined dead-code + complexity + duplication for changed files | `--base`, `--gate`, `--production`, `--production-dead-code`, `--production-health`, `--production-dupes`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--explain`, `--explain-skipped`, `--dead-code-baseline`, `--health-baseline`, `--dupes-baseline`, `--max-crap`, `--coverage`, `--coverage-root`, `--include-entry-exports` |
 | `flags` | Detect feature flag patterns (env vars, SDK calls, config objects) | `--top` |
-| `security` | Surface opt-in local security candidates for verification. First rule: `"use client"` file reaches a non-public `process.env` secret source. Findings are candidates, not confirmed vulnerabilities. | `--format human|json|sarif`, `--changed-since`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
+| `security` | Surface opt-in local security candidates for agent verification (not confirmed vulnerabilities). Two rule families: the graph rule `client-server-leak` (a `"use client"` file reaching a non-public `process.env` secret) and a data-driven `tainted-sink` catalogue across 9 CWE categories (dangerous-html, command-injection, code-injection, sql-injection, ssrf, path-traversal, open-redirect, weak-crypto, unsafe-deserialization). Conservative non-literal trigger; parameterized SQL not flagged. Rules default off; suppress a file with `// fallow-ignore-file security-sink`; scope categories with `security.categories`. | `--format human|json|sarif`, `--changed-since`, `--diff-file`, `--workspace`, `--changed-workspaces`, `--ci`, `--fail-on-issues`, `--sarif-file`, `--summary` |
 | `explain` | Explain one issue type without running analysis | `<issue-type>`, `--format json` |
 | `license` | Manage the local license JWT for continuous/cloud runtime monitoring (activate, status, refresh, deactivate) | `activate --trial --email <addr>`, `activate --from-file`, `activate --stdin`, `status`, `refresh`, `deactivate` |
 | `telemetry` | Manage opt-in, off-by-default product telemetry (never collects code, paths, or names). Agents must not enable it; only the user may | `status`, `enable`, `disable`, `inspect --example` |
@@ -118,6 +118,7 @@ When using fallow via MCP (`fallow-mcp`), the following tools are available:
 |------|-------------|
 | `analyze` | Full dead code analysis (unused files/exports/types/dependencies/members + circular dependencies + re-export cycles (barrel files that form a structural loop, silently breaking re-exports) + boundary violations + stale suppressions). Private type leaks are an opt-in API hygiene check via `issue_types: ["private-type-leaks"]`. Set `boundary_violations: true` as a convenience alias for `issue_types: ["boundary-violations"]`. Set `group_by` to `"owner"`, `"directory"`, `"package"`, or `"section"` to partition results. The `section` mode reads GitLab CODEOWNERS `[Section]` headers and emits `owners` metadata per group |
 | `check_changed` | Incremental analysis of files changed since a git ref |
+| `security_candidates` | Unverified local security candidates, not confirmed vulnerabilities (`fallow security --format json`). Read `security_findings[]` for category, CWE, evidence, and trace; verify trace and evidence before editing code. Supports `root`, `config`, `workspace`, `changed_since`, `changed_workspaces`, `no_cache`, and `threads`; inherits `FALLOW_DIFF_FILE` from the server environment for line-level diff scoping; raise `FALLOW_TIMEOUT_SECS` for large repos. |
 | `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) |
@@ -234,7 +235,7 @@ fallow list --entry-points --format json --quiet
 fallow list --plugins --format json --quiet
 ```
 
-Shows detected entry points and active framework plugins (114 built-in: Next.js, Vite, Ember, Wuchale, Jest, Storybook, Tailwind, PandaCSS, Contentlayer, tap, tsd, etc.).
+Shows detected entry points and active framework plugins (118 built-in: Next.js, Vite, Ember, Wuchale, Jest, Storybook, Tailwind, PandaCSS, Contentlayer, tap, tsd, etc.).
 
 ### Production-only analysis
 
@@ -339,7 +340,7 @@ When `--format json` is active and exit code is 2, errors are emitted as JSON on
 
 ## Configuration
 
-Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to 114 auto-detecting framework plugins.
+Fallow reads config from project root: `.fallowrc.json` > `.fallowrc.jsonc` > `fallow.toml` > `.fallow.toml`. Both `.fallowrc.json` and `.fallowrc.jsonc` accept JSON-with-comments syntax (same parser); the `.jsonc` extension lets editors auto-detect JSONC syntax highlighting. Most projects work with zero configuration thanks to 118 auto-detecting framework plugins.
 
 ```jsonc
 {
@@ -388,7 +389,7 @@ export const deprecatedHelper = () => {};
 ## Key Gotchas
 
 - **`fix --yes` is required** in non-TTY (agent) environments. Without it, `fix` exits with code 2
-- **Zero config by default.** 114 framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Don't create config unless customization is needed
+- **Zero config by default.** 118 framework plugins auto-detect, including Wuchale config, Contentlayer content roots, tap and tsd test entry points. Don't create config unless customization is needed
 - **Syntactic analysis only.** No TypeScript compiler, so fully dynamic `import(variable)` is not resolved
 - **Function overloads are deduplicated.** TypeScript function overload signatures are merged into a single export (not reported as separate unused exports)
 - **Re-export chains are resolved.** Exports through barrel files are tracked, not falsely flagged

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

@@ -485,7 +485,7 @@ fallow health --format json --quiet --trend
 {
   "kind": "health",
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "elapsed_ms": 32,
   "summary": {
     "files_analyzed": 482,
@@ -875,7 +875,7 @@ fallow audit \
 {
   "kind": "audit",
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "command": "audit",
   "verdict": "fail",
   "changed_files_count": 12,
@@ -948,7 +948,7 @@ fallow flags --format json --quiet --workspace my-package
 ```json
 {
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "elapsed_ms": 116,
   "feature_flags": [],
   "total_flags": 0
@@ -963,6 +963,22 @@ Surfaces local security candidates for agent or human verification. The first ru
 
 Findings are not confirmed vulnerabilities. Use the structural trace to verify whether the value can actually reach client-bundled code. Public env conventions (`NODE_ENV`, `NEXT_PUBLIC_*`, `VITE_*`, `NUXT_PUBLIC_*`, `REACT_APP_*`, `PUBLIC_*`, `GATSBY_*`, `EXPO_PUBLIC_*`, `STORYBOOK_*`) are excluded.
 
+The second rule family is a data-driven `tainted-sink` catalogue: syntactic dangerous-sink candidates across 9 CWE categories. A candidate fires only when the relevant argument is non-literal, so a fully-literal value (`el.innerHTML = "<b>x</b>"`, `child_process.exec("ls")`) never fires; fallow prefers false-negatives over false-positives.
+
+| Category | CWE | Sink |
+|----------|-----|------|
+| `dangerous-html` | 79 | `innerHTML` / `outerHTML` / `insertAdjacentHTML` / `dangerouslySetInnerHTML` |
+| `command-injection` | 78 | `child_process` `exec` / `execSync` / `spawn` / `spawnSync` (provenance-gated to `node:child_process`) |
+| `code-injection` | 94 | `eval` / `vm.runInNewContext` |
+| `sql-injection` | 89 | string concat or interpolated template into `.query()` / `.execute()`, and `sql.raw(...)`. Parameterized `` sql`${x}` `` and the object form `.execute({ sql, args })` are NOT flagged |
+| `ssrf` | 918 | `fetch` / `axios` / `http(s).request` |
+| `path-traversal` | 22 | `fs.*` / `path.join` / `path.resolve` |
+| `open-redirect` | 601 | `res.redirect` |
+| `weak-crypto` | 327 | runtime-selectable hash / cipher algorithm |
+| `unsafe-deserialization` | 502 | `js-yaml` `load` / `node-serialize` |
+
+Build-config and test files are excluded from candidate generation. Both rule families default to `off` and are surfaced only by `fallow security`, never under bare `fallow` or the `audit` gate. Scope which catalogue categories run with `security.categories` include / exclude lists in config.
+
 ### Flags
 
 | Flag | Type | Default | Description |
@@ -993,11 +1009,12 @@ git diff --unified=0 origin/main...HEAD | fallow security --diff-file -
   "kind": "security",
   "schema_version": "1",
   "security_findings": [],
-  "unresolved_edge_files": 0
+  "unresolved_edge_files": 0,
+  "unresolved_callee_sites": 0
 }
 ```
 
-Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, and `actions`. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak`.
+Each finding includes `kind`, `path`, `line`, `col`, `evidence`, `trace`, and `actions`. `tainted-sink` findings additionally carry `category` (the catalogue id, e.g. `"dangerous-html"`) and `cwe`; `client-server-leak` findings omit both. `unresolved_edge_files` (client-server-leak) and `unresolved_callee_sites` (tainted-sink) are in-band blind-spot counters: a zero finding count with a non-zero counter is not a clean bill. Suppress a verified false positive with `// fallow-ignore-file security-client-server-leak` (client-server-leak) or `// fallow-ignore-file security-sink` (any tainted-sink category).
 
 ---
 
@@ -1470,7 +1487,7 @@ The HTTP layer mirrors the bash `gh_api_retry` / `curl_retry` helpers: `FALLOW_A
 {
   "kind": "dead-code",
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "elapsed_ms": 45,
   "total_issues": 12,
   "entry_points": {
@@ -1630,7 +1647,7 @@ When `--baseline` is used in combined output, the JSON includes a `baseline_delt
 {
   "kind": "dupes",
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "elapsed_ms": 82,
   "total_clones": 15,
   "total_lines_duplicated": 230,
@@ -1674,11 +1691,11 @@ When running `fallow` with no subcommand (all analyses), the JSON output combine
 {
   "kind": "combined",
   "schema_version": 7,
-  "version": "2.86.0",
+  "version": "2.87.0",
   "elapsed_ms": 159,
   "check": {
     "schema_version": 7,
-    "version": "2.86.0",
+    "version": "2.87.0",
     "elapsed_ms": 45,
     "total_issues": 12,
     "unused_files": [],

package/skills/fallow/references/gotchas.md

@@ -23,7 +23,7 @@ Always preview with `--dry-run` before applying. This is a destructive operation
 
 ## Don't Create Config Unless Needed
 
-Fallow works with zero configuration for most projects thanks to 114 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
+Fallow works with zero configuration for most projects thanks to 118 auto-detecting framework plugins. Creating an unnecessary config file can mask issues or override detection behavior.
 
 ```bash
 # WRONG: creating config for a standard Next.js project

package/skills/fallow/references/patterns.md

@@ -627,7 +627,7 @@ Focus on findings that are BOTH dead code and duplicated:
 
 ## Custom Plugin Setup
 
-For frameworks not covered by the 114 built-in plugins.
+For frameworks not covered by the 118 built-in plugins.
 
 ### Option 1: Inline framework config
 

package/types/output-contract.d.ts

@@ -4756,6 +4756,17 @@ col: number
  * Agent/human-readable evidence (e.g. the named env var the chain reaches).
  */
 evidence: string
+/**
+ * Whether the sink argument was associated with a known untrusted source by
+ * the intra-module source-to-sink back-trace (issue #859): a local binding
+ * referenced in the argument was sourced from a catalogue source path
+ * (`req.query`, `process.argv`, message-event `data`, etc.). `true` ranks
+ * the candidate higher and annotates the evidence; `false` does NOT
+ * suppress the finding (the association is conservative, never a proof, and
+ * fallow prefers false-negatives over false-positives). Always `false` for
+ * `ClientServerLeak`. Skipped from JSON when `false` for output stability.
+ */
+source_backed?: boolean
 /**
  * Structural import-hop trace from the client boundary to the secret source.
  * The hop count is the uncalibrated signal; fallow does not prove the path
@@ -4769,6 +4780,13 @@ trace: TraceHop[]
  * verification is the agent's job, not fallow's.
  */
 actions: IssueAction[]
+/**
+ * Graph-derived reachability ranking signal (issue #860). `None` until the
+ * post-detection ranking pass fills it; additive on the wire (skipped when
+ * absent). Drives the order findings are emitted in: candidates reachable
+ * from a runtime entry point with a wider blast radius sort first.
+ */
+reachability?: (SecurityReachability | null)
 }
 /**
  * One hop in a security finding's structural trace. Stored as an absolute path
@@ -4792,6 +4810,37 @@ line: number
 col: number
 role: TraceHopRole
 }
+/**
+ * Graph-derived reachability ranking signal for a security candidate. Computed
+ * from the EXISTING module graph (runtime reachability + reverse-dep fan-in)
+ * after detection, never proven exploitable. Used to surface candidates that
+ * sit on a request/runtime-reachable surface above isolated helpers or scripts.
+ *
+ * This is a relative-ordering signal, NOT a `confidence` or `signal_strength`
+ * score: fallow does not prove the path is exploitable.
+ */
+export interface SecurityReachability {
+/**
+ * Whether the anchor module is reachable from a runtime/application entry
+ * point (route handlers, server entry, framework runtime roots), the
+ * closest graph proxy for an external/request input surface. Code reachable
+ * only from test entry points does not count.
+ */
+reachable_from_entry: boolean
+/**
+ * Number of distinct modules that transitively depend on the anchor module
+ * (fan-in via the graph's reverse-dependency index). A higher value means a
+ * wider surface: more call sites could route untrusted input into the sink.
+ */
+blast_radius: number
+/**
+ * Whether the anchor module participates in an architecture-boundary
+ * violation found in the same run (as the importing or imported file).
+ * Optional pairing: a candidate that also crosses a declared boundary is a
+ * stronger review target.
+ */
+crosses_boundary: boolean
+}
 /**
  * Bare `fallow --format json` envelope.
  */