fallow 3.4.2 → 3.5.1

package/types/output-contract.d.ts

@@ -7,9 +7,9 @@
  * `npm/fallow/types/output-contract.d.ts` (published as `fallow/types`).
  *
  * To change a shape:
- *   1. Edit the Rust struct in `crates/types/src/results.rs` (or the
- *      duplicates crate at `crates/core/src/duplicates/types.rs`). The Rust
- *      side is the runtime source of truth for the JSON output.
+ *   1. Find the Rust owner through `derived_definition_names()` and its
+ *      imports in `crates/cli/src/bin/schema_emit.rs`, then edit that type.
+ *      Rust is the runtime source of truth for the JSON output.
  *   2. Regenerate `docs/output-schema.json` with
  *      `cargo run -p fallow-cli --features schema-emit --bin fallow-schema-emit`.
  *      The schema-emit drift tests compare the committed schema against the
@@ -24,9 +24,9 @@
 
 
 /**
- * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array.
+ * Schemas for the JSON output of fallow commands. Object-shaped envelopes covered by the `FallowOutput` contract carry a top-level `kind` discriminator. Current kind values: `audit`, `explain`, `inspect_target`, `trace`, `review-envelope`, `review-reconcile`, `coverage-setup`, `coverage-analyze`, `list-boundaries`, `list-workspaces`, `health`, `dupes`, `dead-code-grouped`, `impact`, `impact-cross-repo`, `security`, `security-survivors`, `security-blind-spots`, `dead-code`, `combined`, `feature-flags`, `audit-brief`, `decision-surface`, `review-walkthrough-guide`, `review-walkthrough-validation`, `suppression-inventory`. Consumers should branch on `kind` instead of probing for unique field presence. `CodeClimateOutput` is a bare JSON array (per the Code Climate / GitLab Code Quality spec) and stays a sibling root branch discriminated by checking whether the document root is an array. `ErrorOutput` is the `--format json` failure document, emitted on stdout with a non-zero exit; it carries no `kind` and is discriminated by the `error: true` field.
  */
-export type FallowJsonOutput = (FallowOutput | CodeClimateOutput)
+export type FallowJsonOutput = (FallowOutput | CodeClimateOutput | ErrorOutput)
 /**
  * Typed root of every fallow JSON envelope shape that serializes as a JSON
  * object and participates in the documented `FallowOutput` contract. The
@@ -86,7 +86,7 @@ kind: "dead-code"
 kind: "combined"
 }) | (FeatureFlagsOutput & {
 kind: "feature-flags"
-}) | (ReviewBriefOutput & {
+}) | (ReviewBriefWireOutput & {
 kind: "audit-brief"
 }) | (DecisionSurfaceOutput & {
 kind: "decision-surface"
@@ -651,7 +651,7 @@ export_name: string
 type: "symbol"
 })
 export type InspectIdentity = (InspectFileIdentity | InspectSymbolIdentity)
-export type InspectSectionStatus = ("ok" | "error")
+export type InspectSectionStatus = ("ok" | "unavailable" | "error")
 export type InspectEvidenceScope = ("symbol" | "file" | "project_filtered_to_file")
 /**
  * Best-effort classification of why a callee did not resolve to an edge.
@@ -835,6 +835,12 @@ export type FeatureFlagActionType = ("investigate-flag" | "suppress-line")
  * Serializes as the integer `REVIEW_BRIEF_SCHEMA_VERSION`.
  */
 export type ReviewBriefSchemaVersion = number
+/**
+ * The exactly-three shippable decision categories (the SOLID-3). No cut category
+ * (abstraction / deletion / convention / irreversibility) is representable: this
+ * enum is the structural guarantee that confirmed-noise categories never ship.
+ */
+export type DecisionCategory = ("coupling-boundary" | "public-api-contract" | "dependency")
 /**
  * Coarse risk classification for a changeset, a pure function of the change
  * size (file count plus, once threaded, net lines).
@@ -864,12 +870,6 @@ export type ConfidenceFlag = ("dynamic-dispatch" | "re-export-indirection")
  * The category of a single weakening signal.
  */
 export type WeakeningKind = ("test-weakened" | "threshold-lowered" | "suppression-added" | "security-check-removed")
-/**
- * The exactly-three shippable decision categories (the SOLID-3). No cut category
- * (abstraction / deletion / convention / irreversibility) is representable: this
- * enum is the structural guarantee that confirmed-noise categories never ship.
- */
-export type DecisionCategory = ("coupling-boundary" | "public-api-contract" | "dependency")
 /**
  * Independently-versioned wire-version newtype. Serializes as the integer
  * [`DECISION_SURFACE_SCHEMA_VERSION`].
@@ -7206,6 +7206,11 @@ duplication: InspectEvidenceSection
 complexity: InspectEvidenceSection
 security: InspectEvidenceSection
 impact_closure: InspectEvidenceSection
+/**
+ * OPT-IN target-level git churn. Omitted unless historical evidence was
+ * explicitly requested by the caller.
+ */
+churn?: (InspectEvidenceSection | null)
 /**
  * OPT-IN symbol-level call chain. Present only when `--symbol-chain` was
  * requested AND the target is a SYMBOL (best-effort, syntactic, OFF the
@@ -9347,10 +9352,22 @@ dead_export_count: number
 dead_exports: string[]
 }
 /**
- * `_meta.feature_flags` details emitted with `--explain`.
+ * Optional `_meta` block for [`FeatureFlagsOutput`]. Both fields are optional
+ * because the two contributors are independent: `feature_flags` details are
+ * present only with `--explain`, and `telemetry` is injected post-pass by
+ * [`attach_telemetry_meta`] whenever an analysis run id is available (which is
+ * the default path). Mirrors `Meta` / `CombinedMeta`, which also model
+ * `telemetry` as an optional, never-required property.
  */
 export interface FeatureFlagsMeta {
-feature_flags: FeatureFlagsMetaDetails
+/**
+ * Feature-flag detection explanations, emitted only with `--explain`.
+ */
+feature_flags?: (FeatureFlagsMetaDetails | null)
+/**
+ * Local telemetry correlation metadata for agent follow-up runs.
+ */
+telemetry?: (TelemetryMeta | null)
 }
 /**
  * Feature flag explanatory metadata.
@@ -9378,21 +9395,48 @@ medium: string
 low: string
 }
 /**
- * The full `fallow audit --brief --format json` envelope. Carries the
- * informational verdict, the triage and graph-facts orientation stages, plus
- * the reused "subtract" section (the same dead-code / duplication / complexity
- * payload `fallow audit --format json` emits).
+ * Complete `fallow audit --brief --format json` wire envelope.
+ *
+ * This is distinct from [`ReviewBriefOutput`], which is the reusable review
+ * digest embedded in walkthrough output. The wire envelope also carries audit
+ * metadata, optional telemetry, and the subtract-style analysis subreports.
  */
-export interface ReviewBriefOutput {
+export interface ReviewBriefWireOutput {
 schema_version: ReviewBriefSchemaVersion
-/**
- * Fallow CLI version that produced this output.
- */
-version: string
+version: ToolVersion
 /**
  * Command discriminator singleton: always `"audit-brief"`.
  */
 command: string
+verdict: AuditVerdict
+/**
+ * Number of changed files in the audit scope.
+ */
+changed_files_count: number
+/**
+ * Base ref used to determine the changeset.
+ */
+base_ref: string
+/**
+ * Human-readable description of the resolved base, when available.
+ */
+base_description?: (string | null)
+/**
+ * Head commit SHA, when available.
+ */
+head_sha?: (string | null)
+elapsed_ms: ElapsedMs
+/**
+ * Whether base-snapshot analysis was skipped for this run.
+ */
+base_snapshot_skipped?: (boolean | null)
+summary: AuditSummary
+attribution: AuditAttribution
+/**
+ * Optional metric definitions and local telemetry correlation metadata.
+ */
+_meta?: (Meta | null)
+decisions: DecisionSurface
 triage: DiffTriage
 graph_facts: GraphFacts
 partition: PartitionFacts
@@ -9400,20 +9444,130 @@ impact_closure: ImpactClosureFacts
 focus: FocusMap
 deltas: ReviewDeltas
 /**
- * 6.F, headline: reviewer-private weakening signals (tests
- * removed/skipped, thresholds lowered, suppressions added, security steps
- * removed). Advisory, never gates, never auto-posted.
+ * Reviewer-private weakening signals.
  */
 weakening: WeakeningSignal[]
 routing: RoutingFacts
-decisions: DecisionSurface
+/**
+ * Dead-code findings scoped to the audit changeset.
+ */
+dead_code?: (CheckOutput | null)
+/**
+ * Duplication findings scoped to the audit changeset.
+ */
+duplication?: (DupesReportPayload | null)
+/**
+ * Complexity findings scoped to the audit changeset.
+ */
+complexity?: (HealthReport | null)
+}
+/**
+ * The ranked, capped decision surface plus the set of signal_ids the
+ * deterministic layer emitted (the anti-hallucination allowlist).
+ */
+export interface DecisionSurface {
+/**
+ * Ranked decisions, highest consequence first.
+ */
+decisions: Decision[]
+/**
+ * Present when more than the cap were extracted.
+ */
+truncated?: (TruncationNote | null)
+/**
+ * Every signal_id the deterministic layer emitted, INCLUDING those whose
+ * decision was collapsed below the cap or suppressed. The anti-hallucination
+ * allowlist: an agent decision whose id is absent is rejected.
+ */
+emitted_signal_ids: string[]
+}
+/**
+ * One consequential structural decision, framed as a judgment question for a
+ * human with taste, anchored to a fallow-emitted signal.
+ */
+export interface Decision {
+/**
+ * Deterministic anchor to the fallow-emitted candidate this decision frames.
+ * `accept_signal_id` rejects any id not in the emitted set.
+ */
+signal_id: string
+category: DecisionCategory
+/**
+ * The decision framed as a judgment question for the human.
+ */
+question: string
+/**
+ * Root-relative file the decision is anchored at.
+ */
+anchor_file: string
+/**
+ * 1-based anchor line, when the underlying signal carries one (0 = file head).
+ */
+anchor_line: number
+/**
+ * The raw fallow-emitted candidate key the `signal_id` hashes.
+ */
+signal_key: string
+/**
+ * The `signal_id` this decision WOULD have had before any rename in this
+ * change (the anchor file's pre-rename path). Present only when the anchor was
+ * renamed. A review-memory layer carries a dismissal across a `git mv`: if
+ * `previous_signal_id` was dismissed in an earlier PR, treat this decision as
+ * dismissed too. Keeps `signal_id` itself exact + deterministic.
+ */
+previous_signal_id?: (string | null)
+/**
+ * Blast radius: count of modules affected beyond the diff by this decision.
+ */
+blast: number
+/**
+ * `blast * reversibility_weight`: the rank key (sorted descending).
+ */
+consequence: number
+/**
+ * The routed expert(s) to ask, from ownership routing. Empty when no
+ * ownership signal is available for the anchor file.
+ */
+expert: string[]
+/**
+ * Whether the anchor file's only qualified owner is one person.
+ */
+bus_factor_one?: boolean
+/**
+ * Honest per-decision count: in-repo modules OUTSIDE the diff that already
+ * depend on this decision's anchor. This is the DISPLAY number (taste
+ * ownership: the human reads reversibility from the count itself), distinct
+ * from `blast` (the project-wide proxy used only for ranking). Never a door
+ * label. Internal-only by construction, so it cannot see a published library's
+ * external consumers; the public-API trade-off clause names that risk in prose.
+ */
+internal_consumer_count: number
+/**
+ * The named structural sacrifice this change makes, stated as a fact, never a
+ * recommendation (e.g. "Couples `app` to `infra`; 4 in-repo modules already
+ * depend on this anchor."). A sibling fact to `question`; it never tells the
+ * human what to choose.
+ */
+tradeoff: string
+}
+/**
+ * A note for decisions collapsed below the cap.
+ */
+export interface TruncationNote {
+/**
+ * How many decisions were collapsed below the cap.
+ */
+collapsed: number
+/**
+ * Human-readable collapse reason.
+ */
+reason: string
 }
 /**
  * Stage 0 of the brief: triage facts derived purely from the diff size.
  *
- * `hunks` and `net_lines` are `None` in v1: the file-level audit does not yet
- * thread a `DiffIndex` (from `report/ci/diff_filter.rs`). They populate later,
- * on `--diff-file` / `--diff-stdin`, without a schema bump.
+ * `hunks` and `net_lines` are populated when the caller supplies parsed diff
+ * evidence. They remain absent when no diff is available.
  */
 export interface DiffTriage {
 /**
@@ -9421,11 +9575,11 @@ export interface DiffTriage {
  */
 files: number
 /**
- * Number of diff hunks. `None` in v1 (no diff index threaded yet).
+ * Number of diff hunks, or `None` when no diff evidence was supplied.
  */
 hunks?: (number | null)
 /**
- * Net added-minus-removed lines. `None` in v1 (no diff index threaded yet).
+ * Net added-minus-removed lines, or `None` without diff evidence.
  */
 net_lines?: (number | null)
 risk_class: RiskClass
@@ -9437,18 +9591,20 @@ review_effort: ReviewEffort
  * `boundaries_touched` is derived from the run's boundary-violation zones;
  * `reachable_from` is populated by the impact closure (the affected-not-shown
  * set: modules the changed code is reachable from / affects, none in the diff).
- * `exports_added` / `api_width_delta` stay honestly stubbed (`0`) until the
- * export-surface delta lands. The fields are present and correctly typed so
- * values fill in later without a schema bump.
+ * `exports_added` and `api_width_delta` both report the exports-aware public API
+ * widening count. Removed exports are not represented in this widening-only
+ * signal.
  */
 export interface GraphFacts {
 /**
- * Number of exports added by the changeset. Stubbed to `0` in v1.
+ * Number of public API exports added by the changeset. Zero means the
+ * changeset adds no public API exports.
  */
 exports_added: number
 /**
- * Change in public API width (added minus removed exports). Stubbed to `0`
- * in v1.
+ * Widening-only public API delta, currently equal to `exports_added`.
+ * Removed exports are not represented, so zero means no public API exports
+ * were added.
  */
 api_width_delta: number
 /**
@@ -9696,108 +9852,6 @@ expert: string[]
  */
 bus_factor_one?: boolean
 }
-/**
- * The ranked, capped decision surface plus the set of signal_ids the
- * deterministic layer emitted (the anti-hallucination allowlist).
- */
-export interface DecisionSurface {
-/**
- * Ranked decisions, highest consequence first.
- */
-decisions: Decision[]
-/**
- * Present when more than the cap were extracted.
- */
-truncated?: (TruncationNote | null)
-/**
- * Every signal_id the deterministic layer emitted, INCLUDING those whose
- * decision was collapsed below the cap or suppressed. The anti-hallucination
- * allowlist: an agent decision whose id is absent is rejected.
- */
-emitted_signal_ids: string[]
-}
-/**
- * One consequential structural decision, framed as a judgment question for a
- * human with taste, anchored to a fallow-emitted signal.
- */
-export interface Decision {
-/**
- * Deterministic anchor to the fallow-emitted candidate this decision frames.
- * `accept_signal_id` rejects any id not in the emitted set.
- */
-signal_id: string
-category: DecisionCategory
-/**
- * The decision framed as a judgment question for the human.
- */
-question: string
-/**
- * Root-relative file the decision is anchored at.
- */
-anchor_file: string
-/**
- * 1-based anchor line, when the underlying signal carries one (0 = file head).
- */
-anchor_line: number
-/**
- * The raw fallow-emitted candidate key the `signal_id` hashes.
- */
-signal_key: string
-/**
- * The `signal_id` this decision WOULD have had before any rename in this
- * change (the anchor file's pre-rename path). Present only when the anchor was
- * renamed. A review-memory layer carries a dismissal across a `git mv`: if
- * `previous_signal_id` was dismissed in an earlier PR, treat this decision as
- * dismissed too. Keeps `signal_id` itself exact + deterministic.
- */
-previous_signal_id?: (string | null)
-/**
- * Blast radius: count of modules affected beyond the diff by this decision.
- */
-blast: number
-/**
- * `blast * reversibility_weight`: the rank key (sorted descending).
- */
-consequence: number
-/**
- * The routed expert(s) to ask, from ownership routing. Empty when no
- * ownership signal is available for the anchor file.
- */
-expert: string[]
-/**
- * Whether the anchor file's only qualified owner is one person.
- */
-bus_factor_one?: boolean
-/**
- * Honest per-decision count: in-repo modules OUTSIDE the diff that already
- * depend on this decision's anchor. This is the DISPLAY number (taste
- * ownership: the human reads reversibility from the count itself), distinct
- * from `blast` (the project-wide proxy used only for ranking). Never a door
- * label. Internal-only by construction, so it cannot see a published library's
- * external consumers; the public-API trade-off clause names that risk in prose.
- */
-internal_consumer_count: number
-/**
- * The named structural sacrifice this change makes, stated as a fact, never a
- * recommendation (e.g. "Couples `app` to `infra`; 4 in-repo modules already
- * depend on this anchor."). A sibling fact to `question`; it never tells the
- * human what to choose.
- */
-tradeoff: string
-}
-/**
- * A note for decisions collapsed below the cap.
- */
-export interface TruncationNote {
-/**
- * How many decisions were collapsed below the cap.
- */
-collapsed: number
-/**
- * Human-readable collapse reason.
- */
-reason: string
-}
 /**
  * The separable `decision-surface` envelope: the single call that puts taste-
  * decisions in front of a human, callable WITHOUT the full pipeline (the
@@ -9954,6 +10008,37 @@ agent_schema: AgentSchema
  */
 injection_note: string
 }
+/**
+ * The full `fallow audit --brief --format json` envelope. Carries the
+ * informational verdict, the triage and graph-facts orientation stages, plus
+ * the reused "subtract" section (the same dead-code / duplication / complexity
+ * payload `fallow audit --format json` emits).
+ */
+export interface ReviewBriefOutput {
+schema_version: ReviewBriefSchemaVersion
+/**
+ * Fallow CLI version that produced this output.
+ */
+version: string
+/**
+ * Command discriminator singleton: always `"audit-brief"`.
+ */
+command: string
+triage: DiffTriage
+graph_facts: GraphFacts
+partition: PartitionFacts
+impact_closure: ImpactClosureFacts
+focus: FocusMap
+deltas: ReviewDeltas
+/**
+ * 6.F, headline: reviewer-private weakening signals (tests
+ * removed/skipped, thresholds lowered, suppressions added, security steps
+ * removed). Advisory, never gates, never auto-posted.
+ */
+weakening: WeakeningSignal[]
+routing: RoutingFacts
+decisions: DecisionSurface
+}
 /**
  * The review direction artifact: the order to review in, the coherent units,
  * and per-unit concern lens + out-of-diff + expert. A minimal projection of the
@@ -10301,6 +10386,29 @@ export interface CodeClimateLines {
  */
 begin: number
 }
+/**
+ * Structured JSON error emitted on stdout when `--format json` is active and a
+ * command fails. It carries no `kind` discriminator: it is distinguished from
+ * the kind-tagged success envelopes by the required `error: true` field, and is
+ * a document-root branch alongside `FallowOutput` and `CodeClimateOutput` in
+ * `docs/output-schema.json`. Agents that pass `--format json` and observe a
+ * non-zero exit code parse this shape from stdout.
+ */
+export interface ErrorOutput {
+/**
+ * Always `true`. The discriminator that separates an error document from a
+ * success envelope (which instead carries a `kind`).
+ */
+error: boolean
+/**
+ * Human-readable error message.
+ */
+message: string
+/**
+ * The process exit code the CLI returns alongside this document.
+ */
+exit_code: number
+}
 
 /**
  * Inner complexity-violation payload, flattened into `HealthFinding`