fallow 2.93.0 → 2.95.0

package/skills/fallow/references/node-bindings.md

@@ -0,0 +1,21 @@
+# Node.js Bindings
+
+When embedding fallow inside a Node.js process (editor extensions, long-running servers, custom tooling), prefer the NAPI bindings over spawning the CLI. Same analysis engine, same JSON envelopes, no subprocess or JSON parsing overhead.
+
+```bash
+npm install @fallow-cli/fallow-node
+```
+
+```ts
+import { detectDeadCode, detectDuplication, computeHealth } from '@fallow-cli/fallow-node';
+
+const deadCode = await detectDeadCode({ root: process.cwd(), explain: true });
+const dupes = await detectDuplication({ root: process.cwd(), mode: 'mild', minTokens: 30 });
+const health = await computeHealth({ root: process.cwd(), score: true, ownershipEmails: 'handle' });
+```
+
+Six async functions: `detectDeadCode`, `detectCircularDependencies`, `detectBoundaryViolations`, `detectDuplication`, `computeComplexity`, `computeHealth`. Each returns the same JSON envelope the CLI emits for `--format json`. Rejected promises throw a `FallowNodeError` with `message`, `exitCode`, and optional `code`, `help`, `context` fields that mirror the CLI's structured error surface.
+
+Enum-like fields take lowercase CLI-style literals (`"mild"`, `"cyclomatic"`, `"handle"`, `"low"`). Write-path commands (`fix`, `init`, `hooks install`, `hooks uninstall`, `license activate`, `coverage setup`) are not exposed; use the CLI for those.
+
+See <https://docs.fallow.tools/integrations/node-bindings> for the full field reference.

package/skills/fallow/references/patterns.md

@@ -723,7 +723,7 @@ Use this when Claude Code is allowed to run Git commands in a repository that al
 The pattern is a local agent gate, not a Git hook. Claude Code intercepts its own `Bash` tool calls before execution. When Claude tries `git commit` or `git push`, the hook runs:
 
 ```bash
-fallow audit --format json --quiet --explain
+fallow audit --format json --quiet --explain --gate-marker agent
 ```
 
 Behavior:
@@ -777,14 +777,14 @@ Prefer `fallow hooks install --target agent` to install this file. The script is
 Behavior you can rely on:
 - Runs only when the intercepted command matches `git commit` or `git push`; otherwise exits 0.
 - Resolves `fallow` from PATH first, then `npx --no-install fallow` as a fallback. Skips with a stderr notice if neither is available or if `jq` is missing.
-- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.46.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
-- Runs `fallow audit --format json --quiet --explain` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable.
+- Enforces a version floor via `FALLOW_GATE_MIN_VERSION` (default `2.85.0`). Binaries below the floor are blocked with an upgrade hint. Set the env var to the empty string to disable the check.
+- Runs `fallow audit --format json --quiet --explain --gate-marker agent` and, on verdict=`fail`, writes the full JSON envelope to stderr preceded by `fallow-gate: blocked by fallow <version> at <binary>` so the responsible binary is always identifiable. The gate marker lets local Impact record blocked-then-cleared agent gate events when Impact is enabled.
 - On runtime error (`{"error": true, ...}`) or unexpected non-zero exit, fails open with a one-line stderr notice; warn verdicts pass through silently.
 
 Codex fallback (add to repo root `AGENTS.md`):
 
 ```md
-Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
+Before any `git commit` or `git push`, run `fallow audit --format json --quiet --explain --gate-marker agent`. If the verdict is `fail`, fix the reported findings before retrying. Treat JSON runtime errors like `{ "error": true, ... }` as non-blocking.
 ```
 
 Keep `fallow audit` in CI alongside this local gate. The hook only runs for Claude Code, not for human pushes or other agents, so it is a reinforcement layer rather than a replacement for server-side enforcement.

package/types/output-contract.d.ts

@@ -390,6 +390,10 @@ export type ComplexityMetric = ("cyclomatic" | "cognitive")
  * 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")
+/**
+ * Source for a finding's effective thresholds.
+ */
+export type ThresholdSource = "override"
 /**
  * Discriminant for [`HealthFindingAction::kind`]. Mirrors the action types
  * emitted by `build_health_finding_actions`. A single finding's `actions`
@@ -407,6 +411,10 @@ export type CoverageModel = ("static_binary" | "static_estimated" | "istanbul")
  * Whether CRAP findings in the report used one coverage-source kind or a mix.
  */
 export type CoverageSourceConsistency = ("uniform" | "mixed")
+/**
+ * Lifecycle state for a configured threshold override.
+ */
+export type ThresholdOverrideStatus = ("active" | "stale" | "no_match")
 /**
  * Discriminant for [`UntestedFileAction::kind`]. Mirrors the action types
  * emitted by `build_untested_file_actions`.
@@ -2080,8 +2088,8 @@ introduced?: (AuditIntroduced | null)
 }
 /**
  * Wire-shape envelope for a [`PolicyViolation`] finding. Carries actions for
- * replacing the banned call or import, or suppressing it with the
- * `policy-violation` token.
+ * replacing the banned call or import, or suppressing it with a scoped
+ * `policy-violation:<pack>/<rule-id>` token.
  */
 export interface PolicyViolationFinding {
 /**
@@ -2816,6 +2824,11 @@ export interface HealthReport {
  */
 findings: HealthFinding[]
 summary: HealthSummary
+/**
+ * Configured threshold override states. Entries are emitted for active
+ * exceptions, stale exceptions, and full-run no-match cleanup hints.
+ */
+threshold_overrides?: ThresholdOverrideState[]
 /**
  * Project-wide vital signs (always computed from available data).
  */
@@ -2915,6 +2928,15 @@ component_rollup?: (ComponentRollup | null)
  * otherwise so default and CI output stay lean.
  */
 contributions?: ComplexityContribution[]
+/**
+ * Resolved thresholds used for this finding when a config override changed
+ * at least one ceiling. Omitted for findings using global thresholds.
+ */
+effective_thresholds?: (HealthEffectiveThresholds | null)
+/**
+ * Source of the effective thresholds. Omitted when thresholds are global.
+ */
+threshold_source?: (ThresholdSource | null)
 /**
  * Machine-actionable fix and suppress hints.
  */
@@ -2964,6 +2986,14 @@ weight: number
  */
 nesting: number
 }
+/**
+ * Resolved thresholds used to evaluate a health finding.
+ */
+export interface HealthEffectiveThresholds {
+max_cyclomatic: number
+max_cognitive: number
+max_crap: number
+}
 /**
  * Suggested action attached to a [`ComplexityViolation`].
  *
@@ -3046,6 +3076,36 @@ severity_critical_count: number
 severity_high_count: number
 severity_moderate_count: number
 }
+/**
+ * Report entry describing whether a threshold override is active, stale, or
+ * no longer matching any analyzed file or function.
+ */
+export interface ThresholdOverrideState {
+status: ThresholdOverrideStatus
+override_index: number
+path?: (string | null)
+function?: (string | null)
+configured_thresholds: HealthConfiguredThresholds
+effective_thresholds: HealthEffectiveThresholds
+metrics?: (ThresholdOverrideMetrics | null)
+reason?: (string | null)
+}
+/**
+ * Threshold values configured by a single override entry.
+ */
+export interface HealthConfiguredThresholds {
+max_cyclomatic?: (number | null)
+max_cognitive?: (number | null)
+max_crap?: (number | null)
+}
+/**
+ * Current complexity metrics for a matched threshold override entry.
+ */
+export interface ThresholdOverrideMetrics {
+cyclomatic: number
+cognitive: number
+crap?: (number | null)
+}
 /**
  * Project-wide vital signs , a fixed set of metrics for trend tracking.
  *
@@ -4609,6 +4669,11 @@ elapsed_ms: ElapsedMs
  */
 findings: HealthFinding[]
 summary: HealthSummary
+/**
+ * Configured threshold override states. Entries are emitted for active
+ * exceptions, stale exceptions, and full-run no-match cleanup hints.
+ */
+threshold_overrides?: ThresholdOverrideState[]
 /**
  * Project-wide vital signs (always computed from available data).
  */
@@ -5205,6 +5270,18 @@ recent_resolved: ResolutionEvent[]
  * "resolution tracking starts from your next run" instead of a bare zero.
  */
 attribution_active: boolean
+/**
+ * Whether the local agent onboarding prompt has been explicitly declined.
+ * Stored under `.fallow/` so agents can avoid cross-session nags.
+ */
+onboarding_declined: boolean
+/**
+ * Whether the user ever made an explicit enable/disable decision for
+ * Impact tracking. `enabled: false` with `explicit_decision: false` means
+ * "never asked"; with `true` it means "asked and declined". Agents use
+ * this to offer the impact opt-in exactly once per project.
+ */
+explicit_decision: boolean
 }
 /**
  * Per-category issue counts captured at a recorded run.