fallow 3.17.0 → 3.19.0

package/types/output-contract.d.ts

@@ -24,7 +24,7 @@
 
 
 /**
- * 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`, `type-aware-status`. 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.
+ * 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`, `type-aware-status`, `similar-code`, `similar-code-inspect`, `similar-code-review`. 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 | ErrorOutput)
 /**
@@ -98,6 +98,12 @@ kind: "review-walkthrough-validation"
 kind: "suppression-inventory"
 }) | (TypeAwareStatusOutput & {
 kind: "type-aware-status"
+}) | (SimilarCodeOutput & {
+kind: "similar-code"
+}) | (SimilarCodeInspectOutput & {
+kind: "similar-code-inspect"
+}) | (SimilarCodeReviewOutput & {
+kind: "similar-code-review"
 }))
 /**
  * Schema projection for the audit envelope's exact version.
@@ -363,9 +369,9 @@ type: "jsdoc_tag"
  */
 export type DependencyOverrideSource = ("pnpm-workspace.yaml" | "package.json")
 /**
- * Why a dependency-override entry is misconfigured. `pnpm install` would
- * either fail at install time or silently no-op on these entries; surfacing
- * them statically catches the issue before pnpm does.
+ * Why a dependency-override entry is misconfigured. The active package
+ * manager may fail at install time or silently no-op on these entries;
+ * surfacing them statically catches the issue first.
  */
 export type DependencyOverrideMisconfigReason = ("unparsable-key" | "empty-value")
 /**
@@ -441,6 +447,12 @@ kind: "skipped-minified-file"
  */
 error: string
 kind: "source-read-failure"
+} | {
+kind: "bun-lockb-override-resolution-skipped"
+} | {
+kind: "bun-lock-override-resolution-skipped"
+} | {
+kind: "bun-resolutions-shadowed-by-overrides"
 })
 /**
  * Discriminant for [`CloneGroupAction::kind`]. Mirrors the action types
@@ -697,10 +709,11 @@ export type UnusedAtRuleKind = ("property-registration" | "layer")
 /**
  * The surface through which a design token is consumed. The `theme-var` /
  * `css-var` / `utility` / `apply` kinds are Tailwind v4 `@theme` consumption; the
- * `js-member` / `js-call` kinds are CSS-in-JS consumption (member access on an
- * imported StyleX/vanilla-extract token binding, or a PandaCSS `token('...')`
- * call). The kind is the disjoint origin signal that distinguishes a Tailwind
- * token entry from a CSS-in-JS token entry in the shared `token_consumers` list.
+ * `js-member` / `js-call` kinds are CSS-in-JS consumption (member access through a
+ * same-file or imported StyleX/vanilla-extract token binding, a StyleX
+ * theme-group call, or a PandaCSS token-path call). The kind is the disjoint origin signal that
+ * distinguishes a Tailwind token entry from a CSS-in-JS token entry in the
+ * shared `token_consumers` list.
  */
 export type ConsumerKind = ("theme-var" | "css-var" | "utility" | "apply" | "js-member" | "js-call")
 /**
@@ -1037,6 +1050,74 @@ export type SuppressionInventoryOrigin = "comment"
  * Schema projection for the type-aware status envelope's exact version.
  */
 export type TypeAwareStatusSchemaVersion = 8
+/**
+ * Version singleton for raw similar-code output.
+ */
+export type SimilarCodeSchemaVersion = "1"
+/**
+ * Provider families admitted by the version 1 public contract.
+ */
+export type SimilarCodeProvider = "official-local-companion"
+/**
+ * Stable, coarse interpretation of a candidate score.
+ */
+export type SimilarCodeSimilarityBand = ("moderate" | "high" | "very-high")
+/**
+ * Verification state of a raw semantic candidate.
+ */
+export type SimilarCodeVerificationStatus = "unverified"
+/**
+ * Explicit availability state for one optional enrichment source.
+ */
+export type SimilarCodeEnrichmentState = ("available" | "unavailable" | "not-requested")
+/**
+ * Read-only actions supported by the candidate workflow.
+ */
+export type SimilarCodeActionType = ("inspect" | "review")
+/**
+ * Overall trustworthiness of an emitted result set.
+ */
+export type SimilarCodeCompletionStatus = ("complete" | "partial")
+/**
+ * Bounded phase names in the similar-code pipeline.
+ */
+export type SimilarCodePhase = ("discovery" | "extraction" | "cache" | "embedding" | "validation" | "comparison" | "enrichment")
+/**
+ * Completion state for one generation phase.
+ */
+export type SimilarCodePhaseStatus = ("complete" | "partial" | "skipped" | "timed-out")
+/**
+ * Stable reasons why admitted work was skipped or truncated.
+ */
+export type SimilarCodeSkipReason = ("below-minimum-lines" | "unsupported-function" | "generated-source" | "function-too-large" | "input-limit" | "source-bytes-limit" | "vector-memory-limit" | "comparison-limit" | "candidate-limit" | "neighbor-limit" | "timeout" | "provider-failure" | "token-truncation" | "enrichment-unavailable")
+/**
+ * Vector cache outcome for a run.
+ */
+export type SimilarCodeCacheStatus = ("disabled" | "hit" | "miss" | "mixed")
+/**
+ * Non-severity diagnostic domain for similar-code generation.
+ */
+export type SimilarCodeDiagnosticDomain = ("workspace" | "extraction" | "provider" | "cache" | "enrichment" | "review")
+/**
+ * Version singleton for a similar-code inspect packet.
+ */
+export type SimilarCodeInspectSchemaVersion = "1"
+/**
+ * Conservative syntactic side-effect hint for an inspected function.
+ */
+export type SimilarCodeSideEffectHint = ("pure-looking" | "may-have-side-effects" | "unknown")
+/**
+ * Version singleton for reviewed similar-code output.
+ */
+export type SimilarCodeReviewSchemaVersion = "1"
+/**
+ * Domain outcome assigned by review, never by candidate generation.
+ */
+export type SimilarCodeDomainOutcome = ("same-responsibility" | "related-but-distinct" | "intentional-duplication" | "unrelated" | "needs-human-review")
+/**
+ * How review matched an external verdict to the current candidate.
+ */
+export type SimilarCodeVerdictMatch = ("candidate-id" | "review-key" | "unverified" | "ambiguous-review-key")
 /**
  * Discriminator value for [`CodeClimateIssue::kind`].
  */
@@ -2283,20 +2364,23 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, package.json's
- * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * Entries in pnpm-workspace.yaml's overrides section, package.json's
+ * pnpm.overrides block, npm or Bun's top-level overrides object, or Bun's
+ * top-level resolutions object,
  * whose target package is not declared by any workspace package and is
- * not present in pnpm-lock.yaml or package-lock.json. Default severity
- * is warn because projects without a readable lockfile fall back to
- * manifest-only checks; the hint field flags those conservative cases.
+ * not present in pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json,
+ * or bun.lock. Default severity is warn because projects without a
+ * readable lockfile fall back to manifest-only checks; the hint field
+ * flags those conservative cases. When the only lockfile is bun's binary
+ * bun.lockb, resolution cannot be read and the check emits nothing.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides or npm overrides entries whose key or value does not
- * parse as a valid override spec (empty key, empty value, malformed
- * selector, unbalanced parent matcher). The package manager will reject
- * these at install time. Default severity is error. Wrapped in
+ * Package-manager override or resolution entries whose key or value does
+ * not parse in the declaration source's grammar (empty key, empty value,
+ * malformed selector, unbalanced parent matcher). The package manager may
+ * reject or ignore these at install time. Default severity is error. Wrapped in
  * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
@@ -2454,7 +2538,24 @@ regression?: (RegressionResult | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load.
+ * Non-fatal diagnostics about the project itself, from all three stages
+ * that record them (issue #473):
+ *
+ * - workspace discovery, at config load: `undeclared-workspace`,
+ *   `malformed-package-json`, `glob-matched-no-package-json`,
+ *   `malformed-tsconfig`, `tsconfig-reference-dir-missing`;
+ * - source discovery, during the file walk: `skipped-large-file`,
+ *   `skipped-minified-file`, `source-read-failure`;
+ * - dead-code analysis, from the dependency-catalog and override
+ *   detectors: `malformed-pnpm-workspace-yaml`,
+ *   `bun-lockb-override-resolution-skipped`.
+ *
+ * Analysis-stage kinds therefore reach only the envelopes whose run
+ * includes a dead-code analyze pass, never a standalone
+ * `fallow dupes --format json`. `path` is project-root-relative with
+ * forward slashes; the array is omitted when empty. The same list is
+ * repeated on each top-level command's envelope so single-command
+ * consumers see it without having to look at a separate top-level field.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -2638,12 +2739,12 @@ empty_catalog_groups: number
  */
 unresolved_catalog_references: number
 /**
- * Pnpm `overrides:` entries whose target package is not declared by any
- * workspace package and not present in the lockfile.
+ * Package-manager overrides whose target package is not declared by any
+ * workspace package and not present in the active readable lockfile.
  */
 unused_dependency_overrides: number
 /**
- * Pnpm `overrides:` entries whose key or value cannot be parsed.
+ * Package-manager overrides whose key or value cannot be parsed.
  */
 misconfigured_dependency_overrides: number
 /**
@@ -3886,7 +3987,7 @@ parent_package?: (string | null)
  */
 version_constraint?: (string | null)
 /**
- * The right-hand side of the entry: the version pnpm should force.
+ * The right-hand side of the entry: the version the package manager should force.
  */
 version_range: string
 source: DependencyOverrideSource
@@ -7733,15 +7834,17 @@ near_duplicate_theme_tokens?: NearDuplicateThemeToken[]
  */
 near_duplicate_css_in_js_tokens?: NearDuplicateThemeToken[]
 /**
- * A location-aware reverse index of Tailwind v4 `@theme` token consumers:
- * per token, where it is consumed (`var()` reads, `@apply` bodies, generated
- * utility classes) and through which surface, plus the full `consumer_count`
- * (a static lower bound) and the defining site. Built from the same gated
- * candidate set as `unused_theme_tokens` (v4 + non-plugin + non-published +
- * whole-scope), so a token with `consumer_count: 0` is the same "nothing
- * consumes this" signal. Sorted by token; empty when the project is not
- * Tailwind v4 or a plugin / published-library / partial-scope run gated the
- * scan out.
+ * A location-aware reverse index of design-token consumers. Tailwind v4
+ * entries cover `@theme` tokens consumed through `var()` reads, `@apply`
+ * bodies, or generated utilities. CSS-in-JS entries cover supported StyleX,
+ * vanilla-extract, PandaCSS, styled-components, and Emotion definitions and
+ * their member or call consumers. Every entry includes the defining site,
+ * located consumer samples, and the full `consumer_count` as a static lower
+ * bound. Tailwind entries use the same gated candidate set as
+ * `unused_theme_tokens`; CSS-in-JS entries require supported direct imports.
+ * Partial-scope runs omit the index. Sorted by token and empty when no
+ * eligible token definitions are found. A zero count is evidence for
+ * investigation, not deletion proof.
  */
 token_consumers?: TokenConsumers[]
 /**
@@ -8576,13 +8679,14 @@ actions: CssCandidateAction[]
  *   `apply`), built from the same gated candidate set as `unused_theme_tokens`
  *   (v4 + non-plugin + non-published + whole-scope), so a `consumer_count: 0`
  *   corroborates the `unused_theme_tokens` "nothing consumes this" finding.
- * - CSS-in-JS tokens (kind `js-member` / `js-call`) from StyleX `defineVars`,
- *   vanilla-extract `createTheme` family definitions, and PandaCSS `defineTokens`,
- *   consumed via cross-module member access or PandaCSS `token('...')` calls. NOTE:
+ * - CSS-in-JS tokens (kind `js-member` / `js-call`) from StyleX `defineVars` /
+ *   `unstable_defineVarsNested`, vanilla-extract `createTheme` family definitions,
+ *   and PandaCSS `defineTokens`, consumed via same-file or cross-module member
+ *   access, StyleX theme-group calls, or PandaCSS `token('...')` calls. NOTE:
  *   CSS-in-JS has NO corroborating dead-token finding (there is no
  *   `unused_theme_tokens` analogue), so a CSS-in-JS `consumer_count: 0` is a weaker
- *   signal than the Tailwind case (and the cross-file scan is relative-import or
- *   generated-token-helper only, so alias / bare-package imports are not counted).
+ *   signal than the Tailwind case (and unresolved dynamic imports or computed
+ *   accesses are not counted).
  *
  * This is DESCRIPTIVE context (a blast-radius lookup), not a finding, so it
  * deliberately carries no `actions` array (unlike the cleanup-candidate types in
@@ -8594,14 +8698,14 @@ export interface TokenConsumers {
 /**
  * The token identity. For a Tailwind `@theme` token this is the full custom
  * property as authored, INCLUDING the `--` prefix (`--color-brand`). For a
- * CSS-in-JS token (kind `js-member`) this is the binding-qualified dotted
+ * CSS-in-JS token (kind `js-member` / `js-call`) this is the binding-qualified dotted
  * access path, NO `--` prefix (`vars.color.primary`), matching how consumers
  * read it. The presence of the `--` prefix distinguishes the two origins.
  */
 token: string
 /**
  * For a Tailwind token, the v4 theme namespace (`color`, `radius`,
- * `font-weight`, ...). For a CSS-in-JS token (kind `js-member`), the defining
+ * `font-weight`, ...). For a CSS-in-JS token (kind `js-member` / `js-call`), the defining
  * export BINDING the token set is accessed through (`vars`), which identifies
  * the token set, NOT a semantic group. (The field is thus overloaded by
  * origin; branch on `consumers[].kind` or the `token` shape.)
@@ -8620,9 +8724,10 @@ definition_path: string
 definition_line: number
 /**
  * The FULL number of consumer locations found, a STATIC LOWER BOUND: a
- * computed class name (`bg-${color}`) or a value read outside CSS/markup the
- * scan never sees is not counted. This is the aggregate over every consumer,
- * computed BEFORE [`consumers`](Self::consumers) is capped to a sample.
+ * computed class name (`bg-${color}`), unresolved import, dynamic token
+ * structure, or computed CSS-in-JS access is not counted. This is the
+ * aggregate over every consumer, computed BEFORE
+ * [`consumers`](Self::consumers) is capped to a sample.
  */
 consumer_count: number
 /**
@@ -8634,8 +8739,8 @@ consumer_count: number
 consumers: TokenConsumerLocation[]
 }
 /**
- * Where one Tailwind v4 `@theme` token is consumed, and through which surface.
- * One entry in a [`TokenConsumers::consumers`] sample.
+ * Where one Tailwind or CSS-in-JS design token is consumed, and through which
+ * surface. One entry in a [`TokenConsumers::consumers`] sample.
  */
 export interface TokenConsumerLocation {
 /**
@@ -9036,6 +9141,18 @@ is_used: boolean
  * Files that reference this export directly.
  */
 direct_references: ExportReference[]
+/**
+ * Reachable direct references grouped by namespace. This is additive to
+ * `namespace` and `direct_references`, whose winning-lane meaning remains
+ * unchanged for backwards compatibility.
+ */
+direct_references_by_namespace?: NamespacedExportReferences[]
+/**
+ * A star-export collision that makes the traced name ambiguous. When
+ * present, `is_used: false` is an abstention rather than an unused-code
+ * verdict.
+ */
+star_export_ambiguity?: (StarExportAmbiguity | null)
 /**
  * Re-export chains that pass through this export.
  */
@@ -9062,6 +9179,36 @@ from_file: string
  */
 kind: string
 }
+/**
+ * Direct references that credit one namespace of an export binding.
+ */
+export interface NamespacedExportReferences {
+namespace: SemanticNamespace
+/**
+ * Number of reachable references in this namespace.
+ */
+reference_count: number
+/**
+ * Reachable references in deterministic graph order.
+ */
+references: ExportReference[]
+}
+/**
+ * The `export *` collision that keeps a name from being exported.
+ */
+export interface StarExportAmbiguity {
+/**
+ * Files that each declare a colliding declaration under the traced name
+ * (project-root-relative), sorted. These are the origins to fix: keep one,
+ * rename or explicitly re-export the rest.
+ */
+sources: string[]
+/**
+ * The namespaces the collision occurs in, type before value. A name can
+ * collide in type space, value space, or both.
+ */
+namespaces: SemanticNamespace[]
+}
 /**
  * A re-export chain showing how an export is propagated.
  */
@@ -9105,6 +9252,7 @@ member_kind: string
  * The export that declares this member (the class / enum / store name).
  */
 owner_export: string
+owner_namespace?: SemanticNamespace
 /**
  * Whether the owning export is considered used.
  */
@@ -9423,22 +9571,6 @@ export interface UnresolvedCallee {
 callee: string
 reason: UnresolvedReason
 }
-/**
- * The `export *` collision that keeps a name from being exported.
- */
-export interface StarExportAmbiguity {
-/**
- * Files that each declare a colliding declaration under the traced name
- * (project-root-relative), sorted. These are the origins to fix: keep one,
- * rename or explicitly re-export the rest.
- */
-sources: string[]
-/**
- * The namespaces the collision occurs in, type before value. A name can
- * collide in type space, value space, or both.
- */
-namespaces: SemanticNamespace[]
-}
 /**
  * Envelope emitted by `fallow --format review-github` / `review-gitlab`.
  */
@@ -9576,7 +9708,8 @@ comments: number
  */
 current_fingerprints: number
 /**
- * Distinct fingerprints found in existing comments.
+ * Distinct fingerprints with an open Fallow lifecycle, including
+ * provider-resolved discussions not yet closed by a Fallow marker.
  */
 existing_fingerprints: number
 /**
@@ -9584,7 +9717,7 @@ existing_fingerprints: number
  */
 new_fingerprints: number
 /**
- * Fingerprints commented earlier whose findings no longer exist.
+ * Fingerprints with open Fallow lifecycles whose findings no longer exist.
  */
 stale_fingerprints: number
 /**
@@ -9604,7 +9737,7 @@ provider_warning?: (string | null)
  */
 resolution_comments_posted: number
 /**
- * Stale discussion threads resolved (GitLab).
+ * Provider discussion threads resolved or re-closed.
  */
 threads_resolved: number
 /**
@@ -9914,8 +10047,10 @@ workspace_count: number
 workspaces: WorkspaceInfo[]
 /**
  * Workspace discovery diagnostics produced while reading workspace
- * declarations. Present for compatibility with the current wire contract,
- * even when empty.
+ * declarations. Paths are project-root-relative and use forward slashes,
+ * like `workspaces[].path` and like the `workspace_diagnostics[]` array on
+ * the analysis envelopes. Present for compatibility with the current wire
+ * contract, even when empty.
  */
 workspace_diagnostics: WorkspaceDiagnostic[]
 }
@@ -10090,7 +10225,10 @@ groups?: (HealthGroup[] | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load.
+ * Workspace-discovery, source-discovery, and analysis-stage diagnostics
+ * for the run. See `CheckOutput::workspace_diagnostics` for the full
+ * contract: the kinds each stage records, project-root-relative paths,
+ * omitted when empty.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -10239,11 +10377,13 @@ groups?: (DuplicationGroup[] | null)
  */
 _meta?: (Meta | null)
 /**
- * Workspace-discovery diagnostics surfaced during config load
+ * Workspace-discovery and source-discovery diagnostics for the run
  * (issue #473). See `CheckOutput::workspace_diagnostics` for the full
  * contract; the same list is repeated on each top-level command's
  * envelope so single-command consumers see it without having to look at
- * a separate top-level field.
+ * a separate top-level field. A standalone `fallow dupes` run has no
+ * dead-code analyze pass, so the two analysis-stage kinds never appear
+ * here.
  */
 workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
@@ -10592,20 +10732,23 @@ empty_catalog_groups?: EmptyCatalogGroupFinding[]
  */
 unresolved_catalog_references?: UnresolvedCatalogReferenceFinding[]
 /**
- * Entries in pnpm-workspace.yaml's overrides: section, package.json's
- * pnpm.overrides block, or package.json's top-level npm overrides object,
+ * Entries in pnpm-workspace.yaml's overrides section, package.json's
+ * pnpm.overrides block, npm or Bun's top-level overrides object, or Bun's
+ * top-level resolutions object,
  * whose target package is not declared by any workspace package and is
- * not present in pnpm-lock.yaml or package-lock.json. Default severity
- * is warn because projects without a readable lockfile fall back to
- * manifest-only checks; the hint field flags those conservative cases.
+ * not present in pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json,
+ * or bun.lock. Default severity is warn because projects without a
+ * readable lockfile fall back to manifest-only checks; the hint field
+ * flags those conservative cases. When the only lockfile is bun's binary
+ * bun.lockb, resolution cannot be read and the check emits nothing.
  * Wrapped in [`UnusedDependencyOverrideFinding`].
  */
 unused_dependency_overrides?: UnusedDependencyOverrideFinding[]
 /**
- * pnpm.overrides or npm overrides entries whose key or value does not
- * parse as a valid override spec (empty key, empty value, malformed
- * selector, unbalanced parent matcher). The package manager will reject
- * these at install time. Default severity is error. Wrapped in
+ * Package-manager override or resolution entries whose key or value does
+ * not parse in the declaration source's grammar (empty key, empty value,
+ * malformed selector, unbalanced parent matcher). The package manager may
+ * reject or ignore these at install time. Default severity is error. Wrapped in
  * [`MisconfiguredDependencyOverrideFinding`].
  */
 misconfigured_dependency_overrides?: MisconfiguredDependencyOverrideFinding[]
@@ -11022,6 +11165,10 @@ _meta?: (Meta | null)
  * distinguish "gate ran and passed" from "gate did not run" (absent).
  */
 gate?: (SecurityGate | null)
+/**
+ * Diagnostics owned by this security analysis run.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
  * Security candidates. Paths are project-root-relative, forward-slash.
  */
@@ -11639,6 +11786,10 @@ _meta?: (Meta | null)
  * Gate verdict, present only when `--gate <mode>` was set.
  */
 gate?: (SecurityGate | null)
+/**
+ * Diagnostics owned by the full security analysis summarized here.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecuritySummary
 }
 /**
@@ -11758,6 +11909,10 @@ export interface SecuritySurvivorsOutput {
 schema_version: SecuritySurvivorsSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Diagnostics preserved from the candidate security report.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecuritySurvivorsSummary
 /**
  * Verifier-retained candidates keyed by finding id.
@@ -11840,6 +11995,10 @@ export interface SecurityBlindSpotsOutput {
 schema_version: SecurityBlindSpotsSchemaVersion
 version: ToolVersion
 elapsed_ms: ElapsedMs
+/**
+ * Diagnostics owned by the security analysis used for this view.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 summary: SecurityBlindSpotsSummary
 /**
  * Grouped unresolved callee diagnostics, derived from existing samples.
@@ -11918,6 +12077,15 @@ dupes?: (DupesReportPayload | null)
  * Health section of the combined run.
  */
 health?: (HealthReport | null)
+/**
+ * Workspace-discovery, source-discovery, and analysis-stage diagnostics
+ * for the run (issue #2366). See `CheckOutput::workspace_diagnostics` for
+ * the full contract: root-relative paths, omitted when empty. The
+ * combined envelope carries them here rather than inside a section, so a
+ * run that skips a section (`--skip check`, `--only health`,
+ * `--only dupes`) still reports every diagnostic its analyses recorded.
+ */
+workspace_diagnostics?: WorkspaceDiagnostic[]
 /**
  * Read-only follow-up commands aggregated across the combined run's
  * findings. See `CheckOutput::next_steps` for the contract.
@@ -13094,6 +13262,548 @@ backend_version?: (string | null)
  */
 remediation?: (string | null)
 }
+/**
+ * Raw `fallow similar-code --format json` output.
+ */
+export interface SimilarCodeOutput {
+schema_version: SimilarCodeSchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+generation: SimilarCodeGeneration
+/**
+ * Deterministically ordered unverified candidates.
+ */
+candidates: SimilarCodeCandidate[]
+completion: SimilarCodeCompletion
+/**
+ * Non-severity diagnostics in deterministic order.
+ */
+diagnostics: SimilarCodeDiagnostic[]
+}
+/**
+ * Complete provenance needed to reproduce candidate generation.
+ */
+export interface SimilarCodeGeneration {
+/**
+ * Version of extraction and normalization semantics used for both IDs.
+ */
+extraction_semantics_version: number
+/**
+ * Version of the calculation that produces model embeddings.
+ */
+embedding_semantics_version: number
+provider: SimilarCodeProviderProvenance
+model: SimilarCodeModelProvenance
+parameters: SimilarCodeGenerationParameters
+scope: SimilarCodeScopeProvenance
+/**
+ * Minimum cosine similarity admitted into the candidate set.
+ */
+threshold: number
+/**
+ * Minimum source line count admitted into function extraction.
+ */
+min_lines: number
+}
+/**
+ * Immutable local provider provenance for one generation run.
+ */
+export interface SimilarCodeProviderProvenance {
+provider: SimilarCodeProvider
+/**
+ * Exact companion package version.
+ */
+companion_version: string
+/**
+ * Companion protocol version negotiated for this run.
+ */
+protocol_version: number
+/**
+ * Whether source content left the local machine. Version 1 requires false.
+ */
+source_left_machine: boolean
+}
+/**
+ * Immutable model artifact provenance.
+ */
+export interface SimilarCodeModelProvenance {
+/**
+ * Stable model identifier.
+ */
+model_id: string
+/**
+ * Immutable model revision.
+ */
+revision: string
+/**
+ * SHA-256 digest of the exact model artifact bytes.
+ */
+artifact_sha256: string
+/**
+ * SPDX license identifier or reviewed license label.
+ */
+license: string
+/**
+ * Embedding vector dimensions.
+ */
+dimensions: number
+}
+/**
+ * Parameters that materially affect generated embeddings and scores.
+ */
+export interface SimilarCodeGenerationParameters {
+/**
+ * Numeric representation used for model inference.
+ */
+dtype: string
+/**
+ * Pooling strategy applied to model output.
+ */
+pooling: string
+/**
+ * Whether vectors were normalized before comparison.
+ */
+normalized: boolean
+/**
+ * Maximum inference batch size used by the run.
+ */
+batch_size: number
+/**
+ * Maximum tokenizer length before deterministic truncation.
+ */
+max_tokens: number
+/**
+ * Digest over the complete effective generation parameter set.
+ */
+parameter_sha256: string
+}
+/**
+ * Effective endpoint scope used for corpus admission and pair retention.
+ */
+export interface SimilarCodeScopeProvenance {
+/**
+ * Whether file, changed-file, diff, or workspace scoping was active.
+ */
+active: boolean
+/**
+ * Sorted project-root-relative paths satisfying every active predicate.
+ */
+paths: string[]
+}
+/**
+ * One unverified semantic similar-code candidate.
+ */
+export interface SimilarCodeCandidate {
+/**
+ * Snapshot-stable opaque candidate identity.
+ */
+candidate_id: string
+/**
+ * Content-stable key used for safe line-movement rebinding.
+ */
+review_key: string
+left: SimilarCodeLocation
+right: SimilarCodeLocation
+/**
+ * Cosine similarity reported by the pinned provider and model.
+ */
+similarity: number
+similarity_band: SimilarCodeSimilarityBand
+verification_status: SimilarCodeVerificationStatus
+enrichment: SimilarCodeEnrichmentAvailability
+/**
+ * Read-only inspect and review affordances.
+ */
+actions: SimilarCodeAction[]
+}
+/**
+ * Exact named location of one candidate function.
+ */
+export interface SimilarCodeLocation {
+/**
+ * Project-root-relative, forward-slash path.
+ */
+path: string
+/**
+ * Extracted function or method name.
+ */
+name: string
+/**
+ * One-based inclusive start line.
+ */
+start_line: number
+/**
+ * One-based inclusive start column.
+ */
+start_column: number
+/**
+ * One-based inclusive end line.
+ */
+end_line: number
+/**
+ * One-based inclusive end column.
+ */
+end_column: number
+/**
+ * SHA-256 digest of the exact extracted function source.
+ */
+source_sha256: string
+}
+/**
+ * Availability of every supported source-grounded enrichment.
+ */
+export interface SimilarCodeEnrichmentAvailability {
+graph_relationship: SimilarCodeEnrichmentState
+entry_point_reachability: SimilarCodeEnrichmentState
+callers: SimilarCodeEnrichmentState
+callees: SimilarCodeEnrichmentState
+ownership: SimilarCodeEnrichmentState
+churn: SimilarCodeEnrichmentState
+tests: SimilarCodeEnrichmentState
+deterministic_clone_coverage: SimilarCodeEnrichmentState
+runtime: SimilarCodeEnrichmentState
+}
+/**
+ * Read-only follow-up exposed for a candidate.
+ */
+export interface SimilarCodeAction {
+action: SimilarCodeActionType
+/**
+ * Human-readable description of the read-only operation.
+ */
+description: string
+/**
+ * Explicit mutation guarantee. Version 1 requires this to be true.
+ */
+read_only: boolean
+}
+/**
+ * Typed completion, limit, skip, and cache accounting.
+ */
+export interface SimilarCodeCompletion {
+status: SimilarCodeCompletionStatus
+/**
+ * Per-phase completion in pipeline order.
+ */
+phases: SimilarCodePhaseCompletion[]
+limits: SimilarCodeLimits
+/**
+ * Aggregated skips in phase and reason order.
+ */
+skips: SimilarCodeSkip[]
+cache: SimilarCodeCacheSummary
+/**
+ * Aggregate model inference wall time reported by the local provider.
+ */
+provider_inference_ms: number
+}
+/**
+ * Accounting for one bounded generation phase.
+ */
+export interface SimilarCodePhaseCompletion {
+phase: SimilarCodePhase
+status: SimilarCodePhaseStatus
+/**
+ * Number of admitted inputs processed by this phase.
+ */
+processed: number
+/**
+ * Total admitted inputs known to this phase, when available.
+ */
+total?: (number | null)
+/**
+ * Stable explanation when the phase did not complete.
+ */
+reason?: (string | null)
+}
+/**
+ * Effective resource limits for a similar-code run.
+ */
+export interface SimilarCodeLimits {
+/**
+ * Maximum source files admitted.
+ */
+max_files: number
+/**
+ * Maximum extracted functions admitted.
+ */
+max_functions: number
+/**
+ * Maximum aggregate normalized source bytes admitted.
+ */
+max_source_bytes: number
+/**
+ * Maximum normalized bytes admitted for one function.
+ */
+max_function_bytes: number
+/**
+ * Maximum embedding batch size.
+ */
+max_batch_size: number
+/**
+ * Maximum vector bytes retained for comparison.
+ */
+max_vector_bytes: number
+/**
+ * Maximum pair comparisons performed.
+ */
+max_comparisons: number
+/**
+ * Maximum candidates returned.
+ */
+max_candidates: number
+/**
+ * Maximum returned neighbors per function.
+ */
+max_neighbors_per_function: number
+/**
+ * End-to-end timeout in milliseconds.
+ */
+timeout_ms: number
+}
+/**
+ * Count of skipped work for a stable reason.
+ */
+export interface SimilarCodeSkip {
+phase: SimilarCodePhase
+reason: SimilarCodeSkipReason
+/**
+ * Number of inputs skipped for this phase and reason.
+ */
+count: number
+}
+/**
+ * Privacy-safe cache accounting. Source fragments are never represented.
+ */
+export interface SimilarCodeCacheSummary {
+status: SimilarCodeCacheStatus
+/**
+ * Valid vector cache hits.
+ */
+hits: number
+/**
+ * Vector cache misses.
+ */
+misses: number
+/**
+ * Newly written vector cache entries.
+ */
+writes: number
+/**
+ * Corrupt or incompatible entries ignored safely.
+ */
+invalid_entries: number
+}
+/**
+ * Actionable diagnostic without a severity or gate implication.
+ */
+export interface SimilarCodeDiagnostic {
+domain: SimilarCodeDiagnosticDomain
+/**
+ * Stable machine-readable code.
+ */
+code: string
+/**
+ * Bounded human-readable explanation.
+ */
+message: string
+/**
+ * Optional project-root-relative path.
+ */
+path?: (string | null)
+}
+/**
+ * `fallow similar-code inspect --format json` output.
+ */
+export interface SimilarCodeInspectOutput {
+schema_version: SimilarCodeInspectSchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+generation: SimilarCodeGeneration
+candidate: SimilarCodeCandidate
+packet: SimilarCodeInspectPacket
+completion: SimilarCodeCompletion
+/**
+ * Non-severity diagnostics in deterministic order.
+ */
+diagnostics: SimilarCodeDiagnostic[]
+}
+/**
+ * Bounded source-grounded packet for one immutable candidate.
+ */
+export interface SimilarCodeInspectPacket {
+/**
+ * Candidate identity this packet describes.
+ */
+candidate_id: string
+/**
+ * Content-stable review key this packet describes.
+ */
+review_key: string
+availability: SimilarCodeEnrichmentAvailability
+/**
+ * Graph relationship label, when relationship evidence is available.
+ */
+graph_relationship?: (string | null)
+left: SimilarCodeSideEvidence
+right: SimilarCodeSideEvidence
+}
+/**
+ * Bounded evidence for one side of an inspect packet.
+ */
+export interface SimilarCodeSideEvidence {
+/**
+ * Bounded source window included only in inspect output, never raw output or cache.
+ */
+source_window?: (string | null)
+/**
+ * Declared parameter count when extraction supplied it.
+ */
+parameter_count?: (number | null)
+/**
+ * Whether the inspected function is declared async.
+ */
+is_async?: (boolean | null)
+/**
+ * Whether the inspected function is a generator.
+ */
+is_generator?: (boolean | null)
+/**
+ * Whether the inspected function contains an await expression.
+ */
+has_await?: (boolean | null)
+/**
+ * Whether the inspected function contains a throw expression.
+ */
+has_throw?: (boolean | null)
+/**
+ * Conservative syntactic side-effect classification.
+ */
+side_effect_hint?: (SimilarCodeSideEffectHint | null)
+/**
+ * Whether the function is reachable from a configured entry point.
+ */
+entry_point_reachable?: (boolean | null)
+/**
+ * Bounded, deterministically ordered direct callers.
+ */
+callers: SimilarCodeNamedReference[]
+/**
+ * Bounded, deterministically ordered direct callees.
+ */
+callees: SimilarCodeNamedReference[]
+/**
+ * Bounded, deterministically ordered ownership labels.
+ */
+owners: string[]
+/**
+ * Recent commit count in the configured churn window.
+ */
+churn_commits?: (number | null)
+/**
+ * Bounded, root-relative related test paths.
+ */
+tests: string[]
+/**
+ * Fraction covered by deterministic clone groups, from zero through one.
+ */
+deterministic_clone_coverage?: (number | null)
+/**
+ * Runtime observation count when compatible runtime evidence is present.
+ */
+runtime_observations?: (number | null)
+}
+/**
+ * One named graph reference used in an inspect packet.
+ */
+export interface SimilarCodeNamedReference {
+/**
+ * Project-root-relative, forward-slash path.
+ */
+path: string
+/**
+ * Referenced symbol name.
+ */
+name: string
+/**
+ * One-based source line.
+ */
+line: number
+}
+/**
+ * `fallow similar-code review --format json` output.
+ */
+export interface SimilarCodeReviewOutput {
+schema_version: SimilarCodeReviewSchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+generation: SimilarCodeGeneration
+review: SimilarCodeReviewProvenance
+/**
+ * Raw candidates joined with verdicts in candidate order.
+ */
+candidates: SimilarCodeReviewedCandidate[]
+completion: SimilarCodeCompletion
+/**
+ * Non-severity diagnostics in deterministic order.
+ */
+diagnostics: SimilarCodeDiagnostic[]
+}
+/**
+ * Digests that make the review join reproducible without exposing source.
+ */
+export interface SimilarCodeReviewProvenance {
+/**
+ * SHA-256 digest of the exact candidate JSON input bytes.
+ */
+candidates_sha256: string
+/**
+ * SHA-256 digest of the exact verdict JSON input bytes.
+ */
+verdicts_sha256: string
+}
+/**
+ * One candidate joined with its separate verdict, if safely matched.
+ */
+export interface SimilarCodeReviewedCandidate {
+candidate: SimilarCodeCandidate
+/**
+ * Safely matched external verdict, absent when still unverified.
+ */
+verdict?: (SimilarCodeVerdict | null)
+verdict_match: SimilarCodeVerdictMatch
+outcome: SimilarCodeDomainOutcome
+}
+/**
+ * Separate verdict input for one immutable candidate.
+ */
+export interface SimilarCodeVerdict {
+/**
+ * Snapshot identity from the raw candidate.
+ */
+candidate_id: string
+/**
+ * Content-stable identity from the raw candidate.
+ */
+review_key: string
+/**
+ * Whether the pair is useful enough to review. Null means undecided.
+ */
+candidate_worthy?: (boolean | null)
+/**
+ * Whether the two functions behave equivalently. Null means undecided.
+ */
+behaviorally_equivalent?: (boolean | null)
+/**
+ * Whether consolidation is safe. Null means undecided.
+ */
+refactor_safe?: (boolean | null)
+outcome: SimilarCodeDomainOutcome
+/**
+ * Bounded explanation grounded in the inspected sources.
+ */
+rationale: string
+}
 /**
  * Single CodeClimate-compatible issue inside [`CodeClimateOutput`].
  */