fallow 3.3.0 → 3.5.0

package/types/output-contract.d.ts

@@ -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`. 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"
@@ -94,6 +94,8 @@ kind: "decision-surface"
 kind: "review-walkthrough-guide"
 }) | (WalkthroughValidation & {
 kind: "review-walkthrough-validation"
+}) | (SuppressionInventoryOutput & {
+kind: "suppression-inventory"
 }))
 /**
  * Schema version for this output format (independent of tool version). Bump
@@ -375,6 +377,12 @@ kind: "skipped-large-file"
  */
 size_bytes: number
 kind: "skipped-minified-file"
+} | {
+/**
+ * Filesystem or UTF-8 decoding error from `read_to_string`.
+ */
+error: string
+kind: "source-read-failure"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -643,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.
@@ -827,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).
@@ -856,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`].
@@ -871,6 +879,19 @@ export type DecisionSurfaceSchemaVersion = number
  * The discriminated action kinds a decision can carry.
  */
 export type DecisionActionType = ("ask-expert" | "suppress")
+/**
+ * The `fallow suppressions --format json` schema version. Independently
+ * versioned from the main contract, mirroring `SecuritySchemaVersion`.
+ */
+export type SuppressionInventorySchemaVersion = "1"
+/**
+ * Suppression marker scope.
+ */
+export type SuppressionInventoryLevel = ("file" | "line")
+/**
+ * How a suppression in the inventory was authored.
+ */
+export type SuppressionInventoryOrigin = "comment"
 /**
  * Discriminator value for [`CodeClimateIssue::kind`].
  */
@@ -7185,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
@@ -7939,6 +7965,11 @@ grouped_by: GroupByMode
 total_issues: number
 groups: CheckGroupedEntry[]
 _meta?: (Meta | null)
+/**
+ * Diagnostics collected for the full analysis before issue grouping.
+ * See [`CheckOutput::workspace_diagnostics`] for the contract.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
  * Read-only follow-up commands computed from the full (ungrouped) findings.
  * See [`CheckOutput::next_steps`] for the contract.
@@ -9321,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.
@@ -9352,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
@@ -9374,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 {
 /**
@@ -9395,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
@@ -9411,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
 /**
@@ -9670,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
@@ -9928,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
@@ -10135,6 +10246,106 @@ change_anchor: string
  */
 reason: string
 }
+/**
+ * The `fallow suppressions --format json` envelope. `FallowOutput`
+ * discriminates it by the `kind: "suppression-inventory"` tag.
+ *
+ * A read-only projection over the suppression markers present in analyzed
+ * files this run: nothing here is a finding, and the command that emits it
+ * always exits 0.
+ */
+export interface SuppressionInventoryOutput {
+schema_version: SuppressionInventorySchemaVersion
+summary: SuppressionInventorySummary
+/**
+ * Per-file suppression listings, sorted by path then line.
+ */
+files: SuppressionInventoryFile[]
+}
+/**
+ * Project-level totals for the suppression inventory.
+ */
+export interface SuppressionInventorySummary {
+/**
+ * Total suppression markers in scope.
+ */
+total: number
+/**
+ * Number of files carrying at least one marker.
+ */
+files: number
+/**
+ * Markers without a human-authored `--` reason.
+ */
+without_reason: number
+/**
+ * Markers that also appear as stale-suppression findings this run. This
+ * is a JOIN against the existing stale-suppression detector's output
+ * (matched by file and kind), not a new detection.
+ */
+stale: number
+/**
+ * Marker counts per suppressed kind, sorted by count (descending) then
+ * kind. `kind` is `null` for blanket markers, mirroring the per-entry
+ * contract.
+ */
+by_kind: SuppressionKindCount[]
+}
+/**
+ * One `by_kind` row in the suppression inventory summary.
+ */
+export interface SuppressionKindCount {
+/**
+ * The suppressed issue kind in kebab-case, or `null` for blanket markers
+ * (rendered as "blanket" in human output; machine consumers branch on
+ * `null`).
+ */
+kind?: (string | null)
+/**
+ * Number of markers targeting this kind.
+ */
+count: number
+}
+/**
+ * One file's suppression listing.
+ */
+export interface SuppressionInventoryFile {
+/**
+ * Project-root-relative path, forward-slash separated.
+ */
+path: string
+/**
+ * Markers in this file, sorted by line.
+ */
+suppressions: SuppressionInventoryEntry[]
+}
+/**
+ * One suppression marker in the inventory.
+ */
+export interface SuppressionInventoryEntry {
+/**
+ * 1-based line of the suppression comment itself; 0 only if unknown.
+ */
+line: number
+/**
+ * The suppressed issue kind in kebab-case (e.g. `"unused-export"`), or
+ * `null` for a blanket marker that suppresses every kind on its target.
+ * Human output renders the blanket case as the literal word "blanket";
+ * the JSON contract deliberately keeps `null` so machine consumers
+ * branch on `null` instead of a magic string.
+ */
+kind?: (string | null)
+level: SuppressionInventoryLevel
+origin: SuppressionInventoryOrigin
+/**
+ * Human-authored reason after `--`; `null` when absent.
+ */
+reason?: (string | null)
+/**
+ * Whether a human-authored reason is present.
+ */
+reason_present: boolean
+}
 /**
  * Single CodeClimate-compatible issue inside [`CodeClimateOutput`].
  */
@@ -10175,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`