fallow 2.70.0 → 2.72.0

package/types/output-contract.d.ts

@@ -0,0 +1,2549 @@
+/**
+ * AUTOGENERATED FILE. DO NOT EDIT.
+ *
+ * Generated from `docs/output-schema.json` by
+ * `editors/vscode/scripts/codegen-types.mjs`. The same file is written to
+ * `editors/vscode/src/generated/output-contract.d.ts` (extension internal) and
+ * `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.
+ *   2. Update `docs/output-schema.json` to match. The schema is
+ *      hand-maintained against the Rust structs; the drift-guard test in
+ *      `crates/cli/src/report/json.rs` enforces only a subset of the
+ *      contract (the `HealthFindingAction` enum). Field-level drift between
+ *      Rust and the schema is currently caught by code review.
+ *   3. Run `pnpm --filter fallow-vscode codegen:types` from anywhere.
+ *   4. Commit both regenerated files alongside the schema edit.
+ *
+ * CI runs `pnpm --filter fallow-vscode check:codegen` which fails when
+ * either committed file disagrees with what regen would produce.
+ */
+/* eslint-disable */
+
+
+/**
+ * Schemas for the JSON output of fallow commands. Bare `fallow --format json` produces a combined envelope with `check`, `dupes`, and `health` keys. Individual commands (`fallow dead-code --format json`, `fallow health --format json`, `fallow dupes --format json`, `fallow audit --format json`, `fallow explain <issue-type> --format json`, `fallow coverage setup --json`) produce their own top-level structure.
+ */
+export type FallowJsonOutput = (CombinedOutput | CheckOutput | CheckGroupedOutput | HealthOutput | DupesOutput | AuditOutput | ExplainOutput | CoverageSetupOutput | CodeClimateOutput | ReviewEnvelopeOutput | ReviewReconcileOutput)
+/**
+ * Schema version for this output format (independent of tool version). Bump policy: ADDITIVE changes (new optional top-level fields, new optional struct fields, new array entries, new MCP tools, new CLI flags that map to new optional fields) do NOT bump the version; consumers receive new fields without breaking. BREAKING changes (renamed fields, removed fields, type changes, enum-variant removals, semantic changes to existing fields) DO bump. To detect newly-added fields without a bump, check field presence via JSON-key existence rather than gating on the version. v4 was introduced alongside fallow-cov-protocol 0.2 (per-finding verdict, stable IDs, evidence block, renamed summary fields); v5 introduced health_score formula_version 2 with scale-invariant scoring semantics; v6 widened `AddToConfigAction.value` from a scalar string to `oneOf: [string, array]` so the new `ignoreExports` action can carry a paste-ready array of `{ file, exports }` rule objects (the legacy `ignoreDependencies` etc. variants still emit strings, so consumers that switch on `config_key` keep working unchanged). The runtime-coverage block is extended additively as the protocol evolves (currently 0.3, which adds an optional capture_quality summary field). Other additive examples: dupes --group-by adds optional grouped_by, total_issues, groups fields without bumping.
+ */
+export type SchemaVersion = 6
+/**
+ * Fallow tool version that produced this output.
+ */
+export type ToolVersion = string
+/**
+ * Analysis duration in milliseconds.
+ */
+export type ElapsedMs = number
+/**
+ * A suggested action for resolving an issue. Each issue includes an array of possible actions: a fix action (auto-fixable or manual), suppress-line, suppress-file, and/or add-to-config.
+ */
+export type IssueAction = (FixAction | SuppressLineAction | SuppressFileAction | AddToConfigAction)
+/**
+ * Only present inside `fallow audit --format json` sub-results. true means this finding's structural key was not present at the base ref; false means it was inherited from the base ref.
+ */
+export type AuditIntroduced = boolean
+/**
+ * Overall report verdict. Independent of the per-finding verdict.
+ */
+export type RuntimeCoverageReportVerdict = ("clean" | "hot-path-touched" | "cold-code-detected" | "license-expired-grace" | "unknown")
+/**
+ * Discrete signal captured during runtime-coverage post-processing. Multiple signals can apply to a single report; `verdict` collapses to the most actionable one for the current context.
+ */
+export type RuntimeCoverageSignal = ("license-expired-grace" | "cold-code-detected" | "hot-path-touched")
+/**
+ * Protocol-level per-function runtime coverage verdict derived from the decision table in fallow-cov-protocol. The CLI's `runtime_coverage.findings` array omits `active` entries even though the underlying enum still includes it.
+ */
+export type RuntimeCoverageVerdict = ("safe_to_delete" | "review_required" | "coverage_unavailable" | "low_traffic" | "active" | "unknown")
+/**
+ * Confidence level for a runtime coverage finding.
+ */
+export type RuntimeCoverageConfidence = ("very_high" | "high" | "medium" | "low" | "none" | "unknown")
+/**
+ * Blast-radius risk band. The current thresholds are high at >=20 static callers or >=1,000,000 traffic-weighted caller reach; medium at >=5 callers or >=50,000 weighted reach; low otherwise.
+ */
+export type RuntimeCoverageRiskBand = ("low" | "medium" | "high")
+/**
+ * License or trial watermark applied to runtime coverage output.
+ */
+export type RuntimeCoverageWatermark = ("trial-expired" | "license-expired-grace" | "unknown")
+/**
+ * CodeClimate-compatible issue array. GitLab Code Quality consumes the same shape.
+ */
+export type CodeClimateOutput = CodeClimateIssue[]
+
+/**
+ * Combined output from bare `fallow` invocation. Contains results from all enabled analyses (check, dupes, health). Use --only/--skip to select.
+ */
+export interface CombinedOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+check?: CheckOutput
+dupes?: DupesOutput
+health?: HealthOutput
+}
+export interface CheckOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+/**
+ * Total number of issues found across all categories.
+ */
+total_issues: number
+unused_files: UnusedFile[]
+unused_exports: UnusedExport[]
+unused_types: UnusedExport[]
+private_type_leaks: PrivateTypeLeak[]
+unused_dependencies: UnusedDependency[]
+unused_dev_dependencies: UnusedDependency[]
+unused_optional_dependencies: UnusedDependency[]
+unused_enum_members: UnusedMember[]
+unused_class_members: UnusedMember[]
+unresolved_imports: UnresolvedImport[]
+unlisted_dependencies: UnlistedDependency[]
+duplicate_exports: DuplicateExport[]
+type_only_dependencies: TypeOnlyDependency[]
+test_only_dependencies: TestOnlyDependency[]
+circular_dependencies: CircularDependency[]
+boundary_violations: BoundaryViolation[]
+stale_suppressions: StaleSuppression[]
+/**
+ * Entries in pnpm-workspace.yaml's catalog: or catalogs: sections not referenced by any workspace package via the catalog: protocol.
+ */
+unused_catalog_entries?: UnusedCatalogEntry[]
+/**
+ * Workspace package.json references to catalogs (catalog: or catalog:<name>) that do not declare the consumed package. pnpm install will error until the named catalog grows to include the package or the reference is switched / removed.
+ */
+unresolved_catalog_references?: UnresolvedCatalogReference[]
+entry_points?: EntryPoints
+summary?: CheckSummary
+baseline_deltas?: BaselineDeltas
+baseline?: BaselineMatch
+regression?: RegressionResult
+_meta?: Meta
+}
+export interface UnusedFile {
+/**
+ * File path (forward slashes, relative to project root).
+ */
+path: string
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface FixAction {
+/**
+ * Kebab-case identifier for the fix action.
+ */
+type: ("remove-export" | "delete-file" | "remove-dependency" | "move-dependency" | "remove-enum-member" | "remove-class-member" | "resolve-import" | "install-dependency" | "remove-duplicate" | "move-to-dev" | "refactor-cycle" | "refactor-boundary" | "export-type" | "remove-catalog-entry" | "update-catalog-reference" | "add-catalog-entry" | "remove-catalog-reference")
+/**
+ * Whether `fallow fix` can apply this fix automatically.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the fix.
+ */
+description: string
+/**
+ * Optional context note. Present on non-auto-fixable actions, and on auto-fixable re-export findings to warn about public API surface.
+ */
+note?: string
+/**
+ * Only present on `update-catalog-reference` actions: catalogs in the same workspace that DO declare the package, sorted lexicographically. Lets agents pick the catalog to switch to without re-reading the source.
+ */
+available_in_catalogs?: string[]
+}
+export interface SuppressLineAction {
+/**
+ * Action type identifier.
+ */
+type: "suppress-line"
+/**
+ * Always false for suppress actions.
+ */
+auto_fixable: false
+/**
+ * Human-readable description of the suppression.
+ */
+description: string
+/**
+ * The inline comment to place above the line (e.g., '// fallow-ignore-next-line unused-export'). When multiple suppressible findings share the same path and line, this may contain a comma-separated issue-kind list such as '// fallow-ignore-next-line unused-export, complexity'.
+ */
+comment: string
+/**
+ * Present on multi-location issue types (e.g., duplicate_exports) to indicate the comment must be applied at each location.
+ */
+scope?: "per-location"
+}
+export interface SuppressFileAction {
+/**
+ * Action type identifier.
+ */
+type: "suppress-file"
+/**
+ * Always false for suppress actions.
+ */
+auto_fixable: false
+/**
+ * Human-readable description of the suppression.
+ */
+description: string
+/**
+ * The file-level comment to place at the top of the file (e.g., '// fallow-ignore-file unused-file').
+ */
+comment: string
+}
+export interface AddToConfigAction {
+/**
+ * Action type identifier.
+ */
+type: "add-to-config"
+/**
+ * Always false for config actions.
+ */
+auto_fixable: false
+/**
+ * Human-readable description of the config change.
+ */
+description: string
+/**
+ * The fallow config key to add the value to (e.g., 'ignoreDependencies').
+ */
+config_key: string
+/**
+ * Value to add to the config key. Shape depends on `config_key`. For scalar config keys (`ignoreDependencies`, others) this is a string such as `"lodash"`. For `ignoreExports` this is an array of `{ file, exports }` rule objects so the snippet can be merged into the user's config verbatim.
+ */
+value: (string | {
+file: string
+exports: string[]
+}[])
+/**
+ * Optional URL pointing at a stable JSON Schema fragment that describes the shape of `value`. Agents that intend to validate `value` before writing it into a user's config can fetch the linked schema and run it against `value`. The URL is a JSON Pointer fragment into fallow's main config schema (e.g. `schema.json#/properties/ignoreExports` for the ignoreExports action, or `schema.json#/properties/ignoreDependencies/items` for the per-package ignoreDependencies action). Strictly additive: consumers that ignore the field keep working unchanged.
+ */
+value_schema?: string
+}
+export interface UnusedExport {
+/**
+ * File path containing the unused export.
+ */
+path: string
+/**
+ * Name of the unused export.
+ */
+export_name: string
+/**
+ * Whether this is a type-only export (interface, type alias).
+ */
+is_type_only: boolean
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+/**
+ * Byte offset into the source file (used by the fix command).
+ */
+span_start: number
+/**
+ * Whether this finding comes from a barrel/index re-export rather than the source definition.
+ */
+is_re_export: boolean
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface PrivateTypeLeak {
+/**
+ * File path containing the exported signature.
+ */
+path: string
+/**
+ * Name of the exported symbol whose signature references a private type.
+ */
+export_name: string
+/**
+ * Name of the same-file private type referenced by the exported signature.
+ */
+type_name: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+/**
+ * Byte offset of the private type reference in the source file.
+ */
+span_start: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface UnusedDependency {
+/**
+ * Package name, including internal workspace package names.
+ */
+package_name: string
+/**
+ * Which section of package.json the dependency is listed in.
+ */
+location: ("dependencies" | "devDependencies" | "optionalDependencies")
+/**
+ * Path to the package.json where this dependency is listed.
+ */
+path: string
+/**
+ * 1-based line number of the dependency entry in package.json.
+ */
+line: number
+/**
+ * Workspace roots that import this package even though the declaring workspace does not.
+ */
+used_in_workspaces?: string[]
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface UnusedMember {
+/**
+ * File path containing the unused member.
+ */
+path: string
+/**
+ * Name of the parent enum or class.
+ */
+parent_name: string
+/**
+ * Name of the unused member.
+ */
+member_name: string
+/**
+ * Member kind (e.g., EnumMember, ClassMethod, ClassProperty).
+ */
+kind: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface UnresolvedImport {
+/**
+ * File path containing the unresolved import.
+ */
+path: string
+/**
+ * The import specifier that could not be resolved.
+ */
+specifier: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface UnlistedDependency {
+/**
+ * Package name, including internal workspace package names, that is imported but not listed in package.json.
+ */
+package_name: string
+/**
+ * Import sites where this unlisted dependency is used.
+ */
+imported_from: ImportSite[]
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface ImportSite {
+/**
+ * File containing the import.
+ */
+path: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+}
+export interface DuplicateExport {
+/**
+ * The export name that appears in multiple modules.
+ */
+export_name: string
+/**
+ * Locations where this export name is defined.
+ */
+locations: DuplicateLocation[]
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface DuplicateLocation {
+/**
+ * File containing the duplicate export.
+ */
+path: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+}
+export interface TypeOnlyDependency {
+/**
+ * Production dependency that is only used via type-only imports.
+ */
+package_name: string
+/**
+ * Path to the package.json where this dependency is listed.
+ */
+path: string
+/**
+ * 1-based line number of the dependency entry in package.json.
+ */
+line: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface TestOnlyDependency {
+/**
+ * Production dependency that is only imported by test files — consider moving to devDependencies.
+ */
+package_name: string
+/**
+ * Path to the package.json where this dependency is listed.
+ */
+path: string
+/**
+ * 1-based line number of the dependency entry in package.json.
+ */
+line: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface CircularDependency {
+/**
+ * File paths forming the import cycle, in cycle order.
+ */
+files: string[]
+/**
+ * Number of files in the cycle.
+ */
+length: number
+/**
+ * 1-based line number of the import that starts the cycle.
+ */
+line: number
+/**
+ * 0-based byte column offset of the import that starts the cycle.
+ */
+col: number
+/**
+ * Whether this cycle crosses workspace package boundaries. Only present when true.
+ */
+is_cross_package?: boolean
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface BoundaryViolation {
+/**
+ * Relative path to the file making the disallowed import.
+ */
+from_path: string
+/**
+ * Relative path to the file being imported.
+ */
+to_path: string
+/**
+ * Architecture zone of the importing file.
+ */
+from_zone: string
+/**
+ * Architecture zone of the imported file.
+ */
+to_zone: string
+/**
+ * Relative path of the imported file (used as specifier).
+ */
+import_specifier: string
+/**
+ * 1-based line number of the import statement.
+ */
+line: number
+/**
+ * 0-based byte column offset of the import statement.
+ */
+col: number
+/**
+ * Suggested actions to resolve this issue.
+ */
+actions: IssueAction[]
+introduced?: AuditIntroduced
+}
+export interface StaleSuppression {
+/**
+ * Relative path to the file containing the stale suppression.
+ */
+path: string
+/**
+ * 1-based line number of the suppression comment or JSDoc tag.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+origin: ({
+type: "comment"
+/**
+ * The issue kind token (e.g. 'unused-exports'). Absent for blanket suppressions.
+ */
+issue_kind?: string
+/**
+ * True for fallow-ignore-file, false for fallow-ignore-next-line.
+ */
+is_file_level?: boolean
+} | {
+type: "jsdoc_tag"
+/**
+ * Name of the export that was tagged @expected-unused.
+ */
+export_name: string
+})
+introduced?: AuditIntroduced
+}
+/**
+ * A package declared in a pnpm-workspace.yaml catalog that is not referenced by any workspace package via the catalog: protocol.
+ */
+export interface UnusedCatalogEntry {
+/**
+ * Package name declared in the catalog (e.g. 'react').
+ */
+entry_name: string
+/**
+ * Catalog group name. 'default' for the top-level catalog: map, or the named catalog key for entries under catalogs.<name>:.
+ */
+catalog_name: string
+/**
+ * Relative path to pnpm-workspace.yaml.
+ */
+path: string
+/**
+ * 1-based line number of the catalog entry.
+ */
+line: number
+/**
+ * Workspace package.json paths that declare the same package with a hardcoded version range instead of catalog:. Omitted when empty.
+ */
+hardcoded_consumers?: string[]
+actions?: IssueAction[]
+introduced?: AuditIntroduced
+}
+/**
+ * A workspace package.json reference (catalog: or catalog:<name>) pointing at a catalog that does not declare the consumed package. `pnpm install` will fail with ERR_PNPM_CATALOG_ENTRY_NOT_FOUND_FOR_CATALOG_PROTOCOL.
+ */
+export interface UnresolvedCatalogReference {
+/**
+ * Package name being referenced via the catalog protocol (e.g. 'old-react').
+ */
+entry_name: string
+/**
+ * Catalog group the reference points at. 'default' for bare catalog: references, or the named catalog key for catalog:<name> references.
+ */
+catalog_name: string
+/**
+ * Relative path to the consumer package.json.
+ */
+path: string
+/**
+ * 1-based line number of the dependency entry in the consumer package.json.
+ */
+line: number
+/**
+ * Other catalogs in the same workspace that DO declare this package, sorted lexicographically. When non-empty, the suggested fix is to flip the reference to one of those catalogs; when empty, the fix is to add the missing entry to the named catalog or to remove the reference. Omitted when empty.
+ */
+available_in_catalogs?: string[]
+actions?: IssueAction[]
+introduced?: AuditIntroduced
+}
+/**
+ * Entry point detection summary showing total detected entry points and their sources.
+ */
+export interface EntryPoints {
+/**
+ * Total number of detected entry points.
+ */
+total: number
+/**
+ * Breakdown of entry points by detection source (e.g., 'package.json', 'next.js', 'config entry').
+ */
+sources: {
+[k: string]: number
+}
+}
+/**
+ * Per-category issue counts for dead code analysis.
+ */
+export interface CheckSummary {
+unused_files?: number
+unused_exports?: number
+unused_types?: number
+private_type_leaks?: number
+unused_dependencies?: number
+unused_dev_dependencies?: number
+unused_enum_members?: number
+unused_class_members?: number
+unresolved_imports?: number
+unlisted_dependencies?: number
+duplicate_exports?: number
+circular_dependencies?: number
+boundary_violations?: number
+stale_suppressions?: number
+unused_catalog_entries?: number
+unresolved_catalog_references?: number
+}
+/**
+ * Per-category delta comparison against a saved baseline. Shows current count, baseline count, and delta for each category.
+ */
+export interface BaselineDeltas {
+/**
+ * Net change in total issues vs baseline (positive = more issues).
+ */
+total_delta: number
+/**
+ * Per-category breakdown of current, baseline, and delta counts.
+ */
+per_category: {
+[k: string]: {
+/**
+ * Current issue count for this category.
+ */
+current: number
+/**
+ * Baseline issue count for this category.
+ */
+baseline: number
+/**
+ * Change from baseline (current - baseline).
+ */
+delta: number
+}
+}
+}
+/**
+ * Baseline match statistics. Shows how many baseline entries existed and how many matched current issues. Useful for detecting stale baselines programmatically.
+ */
+export interface BaselineMatch {
+/**
+ * Total number of entries in the loaded baseline file.
+ */
+entries: number
+/**
+ * Number of baseline entries that matched current issues and were filtered.
+ */
+matched: number
+}
+/**
+ * Result of regression detection (--fail-on-regression). Compares current issue counts against a baseline from config or an explicit file.
+ */
+export interface RegressionResult {
+status: ("pass" | "exceeded" | "skipped")
+baseline_total?: number
+current_total?: number
+delta?: number
+tolerance?: number
+tolerance_kind?: ("absolute" | "percentage")
+exceeded: boolean
+/**
+ * Only present when status is 'skipped'.
+ */
+reason?: string
+}
+/**
+ * Metric definitions and documentation links. Included when --explain is passed (always present in MCP responses). Helps AI agents and CI systems interpret metric values.
+ */
+export interface Meta {
+/**
+ * URL to the documentation page for this command.
+ */
+docs?: string
+/**
+ * Per-metric definitions: name, description, range, interpretation.
+ */
+metrics?: {
+[k: string]: {
+/**
+ * Human-readable metric name.
+ */
+name?: string
+/**
+ * What this metric measures and how it is computed.
+ */
+description?: string
+/**
+ * Valid value range (e.g., '[0, 100]').
+ */
+range?: string
+/**
+ * How to read the value (e.g., 'lower is better').
+ */
+interpretation?: string
+}
+}
+/**
+ * Per-rule definitions for check command output.
+ */
+rules?: {
+[k: string]: {
+/**
+ * Human-readable rule name.
+ */
+name?: string
+/**
+ * What this rule detects.
+ */
+description?: string
+/**
+ * URL to the rule documentation.
+ */
+docs?: string
+}
+}
+}
+/**
+ * Duplication analysis output. Contains clone groups (individual duplicates), clone families (groups sharing the same files), and aggregate statistics. With --group-by, the project-level fields stay populated and an additional `grouped_by` + `groups` envelope is appended.
+ */
+export interface DupesOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+/**
+ * All detected clone groups. Each group contains 2+ instances of identical or near-identical code.
+ */
+clone_groups: CloneGroup[]
+/**
+ * Clone families: groups of clone groups sharing the same file set, indicating systematic duplication patterns.
+ */
+clone_families: CloneFamily[]
+stats: DuplicationStats
+/**
+ * Directory pairs with high structural duplication. Only present when mirrored directories are detected.
+ */
+mirrored_directories?: MirroredDirectory[]
+/**
+ * Resolver mode used for partitioning. Present only when `--group-by` is active.
+ */
+grouped_by?: ("owner" | "directory" | "package" | "section")
+/**
+ * Per-group buckets when `--group-by` is active. Each clone group is attributed to its largest-owner key (most instances; alphabetical tiebreak). Sort: most clone groups first, then alphabetical, with `(unowned)` pinned last.
+ */
+groups?: DuplicationGroup[]
+_meta?: Meta
+}
+/**
+ * A group of code clones — the same (or normalized-equivalent) code appearing in multiple places.
+ */
+export interface CloneGroup {
+/**
+ * All instances where this duplicated code appears.
+ */
+instances: CloneInstance[]
+/**
+ * Number of normalized source tokens in the duplicated block.
+ */
+token_count: number
+/**
+ * Number of source lines in the duplicated block.
+ */
+line_count: number
+/**
+ * Suggested actions to eliminate this clone group.
+ */
+actions?: CloneGroupAction[]
+introduced?: AuditIntroduced
+}
+/**
+ * A single instance of duplicated code at a specific location.
+ */
+export interface CloneInstance {
+/**
+ * File path (relative to project root).
+ */
+file: string
+/**
+ * 1-based start line of the clone.
+ */
+start_line: number
+/**
+ * 1-based end line of the clone.
+ */
+end_line: number
+/**
+ * 0-based start column.
+ */
+start_col: number
+/**
+ * 0-based end column.
+ */
+end_col: number
+/**
+ * The actual source code fragment.
+ */
+fragment: string
+}
+/**
+ * A suggested action for a clone group.
+ */
+export interface CloneGroupAction {
+/**
+ * Action type identifier.
+ */
+type: ("extract-shared" | "suppress-line")
+/**
+ * Whether fallow can auto-fix this action.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the action.
+ */
+description: string
+/**
+ * The inline comment to insert (e.g., '// fallow-ignore-next-line code-duplication'). Present for suppress-line actions.
+ */
+comment?: string
+}
+/**
+ * A clone family: a set of clone groups sharing the same file set, indicating systematic duplication.
+ */
+export interface CloneFamily {
+/**
+ * Files involved in this family (sorted).
+ */
+files: string[]
+/**
+ * Clone groups belonging to this family.
+ */
+groups: CloneGroup[]
+/**
+ * Total duplicated lines across all groups in this family.
+ */
+total_duplicated_lines: number
+/**
+ * Total duplicated tokens across all groups in this family.
+ */
+total_duplicated_tokens: number
+/**
+ * Refactoring suggestions for this family.
+ */
+suggestions: RefactoringSuggestion[]
+/**
+ * Suggested actions to eliminate duplication in this family.
+ */
+actions?: CloneFamilyAction[]
+}
+export interface RefactoringSuggestion {
+/**
+ * What kind of refactoring is suggested.
+ */
+kind: ("ExtractFunction" | "ExtractModule")
+/**
+ * Human-readable description of the suggestion.
+ */
+description: string
+/**
+ * Estimated lines that could be eliminated.
+ */
+estimated_savings: number
+}
+/**
+ * A suggested action for a clone family.
+ */
+export interface CloneFamilyAction {
+/**
+ * Action type identifier.
+ */
+type: ("extract-shared" | "apply-suggestion" | "suppress-line")
+/**
+ * Whether fallow can auto-fix this action.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the action.
+ */
+description: string
+/**
+ * Additional context for the action.
+ */
+note?: string
+/**
+ * The inline comment to insert (e.g., '// fallow-ignore-next-line code-duplication'). Present for suppress-line actions.
+ */
+comment?: string
+}
+/**
+ * Aggregate duplication statistics for the analyzed project.
+ */
+export interface DuplicationStats {
+/**
+ * Total files analyzed.
+ */
+total_files: number
+/**
+ * Files containing at least one clone instance.
+ */
+files_with_clones: number
+/**
+ * Total lines across all analyzed files.
+ */
+total_lines: number
+/**
+ * Lines that are part of at least one clone.
+ */
+duplicated_lines: number
+/**
+ * Total tokens across all analyzed files.
+ */
+total_tokens: number
+/**
+ * Tokens that are part of at least one clone.
+ */
+duplicated_tokens: number
+/**
+ * Number of clone groups in the reported `clone_groups[]` array. Matches `clone_groups[].length` post `minOccurrences` filtering; the count of groups hidden by the filter is exposed in `clone_groups_below_min_occurrences`.
+ */
+clone_groups: number
+/**
+ * Total clone instances across all reported groups. Matches `clone_groups[]`'s flattened instance count post `minOccurrences` filtering.
+ */
+clone_instances: number
+/**
+ * Percentage of duplicated lines (0.0 to 100.0). Always reflects the FULL corpus, computed BEFORE the `minOccurrences` filter so trend lines and `threshold` gates stay stable when the filter changes.
+ */
+duplication_percentage: number
+/**
+ * Number of clone groups hidden by `duplicates.minOccurrences`. Absent (or `0`) when the filter is at its default of `2` and nothing was hidden. Pre-filter clone group count = `clone_groups + clone_groups_below_min_occurrences`.
+ */
+clone_groups_below_min_occurrences?: number
+}
+/**
+ * A pair of directories with high structural duplication, indicating systematic copy-paste of directory trees.
+ */
+export interface MirroredDirectory {
+/**
+ * First directory path (relative to project root).
+ */
+dir_a: string
+/**
+ * Second directory path (relative to project root).
+ */
+dir_b: string
+/**
+ * File names that appear in both directories with duplicated content.
+ */
+shared_files: string[]
+/**
+ * Total duplicated lines across all shared files.
+ */
+total_lines: number
+}
+/**
+ * A single grouped duplication bucket. Per-group `stats` are dedup-aware and computed over the FULL group BEFORE any `--top` truncation.
+ */
+export interface DuplicationGroup {
+/**
+ * Group label (owner / directory / package / section). `(unowned)` for files with no CODEOWNERS rule, `(no section)` for pre-section rules in section mode.
+ */
+key: string
+stats: DuplicationStats
+/**
+ * Clone groups attributed to this owner. Each group's `primary_owner` is its largest-owner key; per-instance `owner` lets consumers see cross-bucket fan-out without re-resolving paths.
+ */
+clone_groups: AttributedCloneGroup[]
+clone_families: CloneFamily[]
+}
+/**
+ * A clone group annotated with its largest-owner attribution and per-instance owner keys.
+ */
+export interface AttributedCloneGroup {
+/**
+ * Largest-owner attribution: the resolver key with the most instances in this clone group. Ties broken alphabetically (smallest key wins).
+ */
+primary_owner: string
+token_count: number
+line_count: number
+/**
+ * Each instance carries its own `owner` field alongside the standard CloneInstance shape.
+ */
+instances: {
+file: string
+start_line: number
+end_line: number
+start_col: number
+end_col: number
+fragment: string
+/**
+ * Resolver key for this specific instance (per-instance, not the group-level largest-owner).
+ */
+owner: string
+}[]
+/**
+ * Suggested actions for this clone group (extract-shared, suppress-line, etc.).
+ */
+actions?: unknown[]
+}
+export interface HealthOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+summary: HealthSummary
+/**
+ * Functions and synthetic template entries exceeding complexity thresholds, sorted by the --sort criteria.
+ */
+findings: HealthFinding[]
+/**
+ * Per-file health scores. Only present when --file-scores is used. Sorted by maintainability_index ascending (worst first). Zero-function files (barrels) are excluded by default.
+ */
+file_scores?: FileHealthScore[]
+/**
+ * Hotspot entries combining git churn with complexity. Only present when --hotspots is used. Sorted by score descending (highest risk first).
+ */
+hotspots?: HotspotEntry[]
+hotspot_summary?: HotspotSummary
+vital_signs?: VitalSigns
+health_score?: HealthScore
+/**
+ * Functions exceeding 60 LOC (very high risk). Only present when unit size very-high-risk bin >= 3%. Sorted by line count descending.
+ */
+large_functions?: LargeFunctionEntry[]
+/**
+ * Ranked refactoring recommendations. Only present when --targets is used. Sorted by efficiency (priority/effort) descending.
+ */
+targets?: RefactoringTarget[]
+target_thresholds?: TargetThresholds
+health_trend?: HealthTrend
+coverage_gaps?: CoverageGaps
+runtime_coverage?: RuntimeCoverageReport
+/**
+ * Resolver mode used when --group-by is active. Present only on grouped output. The top-level `vital_signs`, `health_score`, and `summary` keep the active run scope (for example after --workspace); per-group versions live inside each entry of `groups`.
+ */
+grouped_by?: ("owner" | "directory" | "package" | "section")
+/**
+ * Per-group health output, present only when --group-by is active. Each group recomputes its own vital_signs and health_score from the files in that group, mirroring how --workspace scopes a single subset.
+ */
+groups?: HealthGroup[]
+/**
+ * Audit breadcrumb explaining systemic action-array adjustments. Present only when at least one adjustment was made (e.g., health finding suppression hints omitted because a baseline is active). When --group-by is active, each entry of `groups` may carry its own `actions_meta` describing the same omission so per-group consumers do not need to walk back to the report root.
+ */
+actions_meta?: {
+/**
+ * True when `suppress-line` actions were not emitted on health findings.
+ */
+suppression_hints_omitted: boolean
+/**
+ * Why suppression hints were omitted. `baseline-active` = `--baseline` or `--save-baseline` was passed; `config-disabled` = `health.suggestInlineSuppression: false`; `unspecified` = caller omitted hints without setting a reason.
+ */
+reason: string
+/**
+ * The report section affected by this metadata. Other health sections can still carry their own suppress actions.
+ */
+scope: "health-findings"
+}
+_meta?: Meta
+}
+export interface HealthSummary {
+/**
+ * Number of files analyzed for complexity.
+ */
+files_analyzed: number
+/**
+ * Total number of functions found.
+ */
+functions_analyzed: number
+/**
+ * Number of functions exceeding at least one threshold (before --top truncation).
+ */
+functions_above_threshold: number
+/**
+ * Configured cyclomatic complexity threshold.
+ */
+max_cyclomatic_threshold: number
+/**
+ * Configured cognitive complexity threshold.
+ */
+max_cognitive_threshold: number
+/**
+ * Configured CRAP (Change Risk Anti-Patterns) score threshold. Functions meeting or exceeding this score appear as findings with the `crap` and optional `coverage_pct` fields populated.
+ */
+max_crap_threshold: number
+/**
+ * Number of files with health scores. Only present when --file-scores is used. 0 indicates the flag was set but scoring failed.
+ */
+files_scored?: number
+/**
+ * Average maintainability index across all scored files (before --top truncation). Only present when --file-scores is used and at least one file was scored.
+ */
+average_maintainability?: number
+/**
+ * Coverage model used for CRAP score computation. 'static_estimated' (default) uses per-function graph-based estimation from export references: directly test-referenced = 85%, indirectly reachable = 40%, untested = 0%. 'istanbul' uses real per-function statement coverage from a coverage-final.json file (--coverage flag or auto-detected). 'static_binary' is the legacy binary model. Only present when file scores are computed.
+ */
+coverage_model?: ("static_binary" | "static_estimated" | "istanbul")
+/**
+ * Number of functions matched against Istanbul coverage data. Only present when coverage_model is 'istanbul'.
+ */
+istanbul_matched?: number
+/**
+ * Total functions evaluated for Istanbul matching. Only present when coverage_model is 'istanbul'.
+ */
+istanbul_total?: number
+/**
+ * Number of findings with critical severity (cognitive >= 40 or cyclomatic >= 50).
+ */
+severity_critical_count: number
+/**
+ * Number of findings with high severity (cognitive 25-39 or cyclomatic 30-49).
+ */
+severity_high_count: number
+/**
+ * Number of findings with moderate severity (below high thresholds).
+ */
+severity_moderate_count: number
+}
+export interface HealthFinding {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Function name, "<anonymous>" for unnamed functions/arrows, or "<template>" for synthetic Angular template findings.
+ */
+name: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * 0-based byte column offset.
+ */
+col: number
+/**
+ * McCabe cyclomatic complexity (1 + decision points).
+ */
+cyclomatic: number
+/**
+ * SonarSource cognitive complexity (structural + nesting penalty).
+ */
+cognitive: number
+/**
+ * Number of lines in the function body.
+ */
+line_count: number
+/**
+ * Number of parameters (excluding TypeScript's this parameter).
+ */
+param_count: number
+/**
+ * Which threshold(s) this finding exceeds. `crap` and its combinations are emitted when `max_crap_threshold` is crossed.
+ */
+exceeded: ("cyclomatic" | "cognitive" | "both" | "crap" | "cyclomatic_crap" | "cognitive_crap" | "all")
+/**
+ * CRAP score (rounded to one decimal). Present only when the function exceeded the CRAP threshold; absent otherwise.
+ */
+crap?: number
+/**
+ * Per-function statement coverage percentage (0.0 to 100.0) used to derive `crap`. Present only when Istanbul coverage data matched the function; absent for the estimated model or unmatched functions.
+ */
+coverage_pct?: number
+/**
+ * Bucketed coverage tier used to drive action selection. Present whenever CRAP triggered the finding (Istanbul or estimated), absent otherwise. `none` = coverage is at most 0% (file not test-reachable, or Istanbul reports 0); `partial` = coverage is in `(0, 70)`; `high` = coverage is at or above the high watermark (default `>= 70`, or the estimated 85% band).
+ */
+coverage_tier?: ("none" | "partial" | "high")
+/**
+ * How far above the threshold: moderate (just above), high (recommended for extraction), or critical (immediate extraction candidate). Defaults: cognitive 25/40, cyclomatic 30/50.
+ */
+severity: ("moderate" | "high" | "critical")
+/**
+ * Suggested actions to address this complex finding.
+ */
+actions?: HealthFindingAction[]
+introduced?: AuditIntroduced
+}
+/**
+ * A suggested action for a health complexity finding.
+ */
+export interface HealthFindingAction {
+/**
+ * Action type identifier. A single finding's `actions` array can carry MULTIPLE entries of different types: e.g., a finding that exceeded both cyclomatic and CRAP at `coverage_tier`: partial will get BOTH `increase-coverage` AND `refactor-function`, plus `suppress-line`. Consumers that select a single action should treat the FIRST non-`suppress-{line,file}` action as primary. `add-tests` is emitted when CRAP triggered the finding, the function has no test coverage (`coverage_tier`: none), and full coverage can bring CRAP below `max_crap_threshold` (cyclomatic < threshold, since CRAP bottoms out at CC at 100% coverage). `increase-coverage` is emitted when CRAP triggered the finding, some coverage exists (`coverage_tier`: partial or high), and full coverage can bring CRAP below `max_crap_threshold`; the description steers toward targeted branch coverage rather than scaffolding new tests. `refactor-function` is emitted when cyclomatic/cognitive triggered the finding, when full coverage still cannot bring CRAP below `max_crap_threshold` (cyclomatic >= threshold), or as a secondary action when cyclomatic is within 5 of the cyclomatic threshold AND cognitive is at or above `max_cognitive_threshold / 2` (the cognitive floor suppresses false positives on flat type-tag dispatchers and JSX render maps where high cyclomatic comes from a single switch with near-zero cognitive load). `suppress-file` is emitted instead of `suppress-line` for synthetic Angular `<template>` findings on `.html` files, because line-suppression comments cannot be expressed in HTML; the `comment` field carries `<!-- fallow-ignore-file complexity -->` and `placement` is `top-of-template`.
+ */
+type: ("refactor-function" | "add-tests" | "increase-coverage" | "suppress-file" | "suppress-line")
+/**
+ * Whether fallow can auto-fix this action.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the action.
+ */
+description: string
+/**
+ * Additional context for the action.
+ */
+note?: string
+/**
+ * The inline comment to insert (e.g., '// fallow-ignore-next-line complexity' or '<!-- fallow-ignore-file complexity -->'). Present for suppress actions.
+ */
+comment?: string
+/**
+ * Where to insert the suppress comment (e.g., 'above-function-declaration', 'above-angular-decorator', or 'top-of-template'). Present for suppress actions.
+ */
+placement?: string
+}
+/**
+ * Per-file health score. Formula: MI = 100 - (complexity_density x 30) - (dead_code_ratio x 20) - min(ln(fan_out+1) x 4, 15), clamped to [0, 100]. Type-only exports excluded from dead_code_ratio. CRAP scores combine cyclomatic complexity with static test reachability.
+ */
+export interface FileHealthScore {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Number of files that import this file.
+ */
+fan_in: number
+/**
+ * Number of files this file directly imports.
+ */
+fan_out: number
+/**
+ * Fraction of value exports (excluding type-only) with zero references (0.0–1.0).
+ */
+dead_code_ratio: number
+/**
+ * Total cyclomatic complexity / lines of code.
+ */
+complexity_density: number
+/**
+ * Weighted composite score (0–100, higher is better).
+ */
+maintainability_index: number
+/**
+ * Sum of cyclomatic complexity across all functions in this file.
+ */
+total_cyclomatic: number
+/**
+ * Sum of cognitive complexity across all functions in this file.
+ */
+total_cognitive: number
+/**
+ * Number of functions in this file.
+ */
+function_count: number
+/**
+ * Total lines of code in the file.
+ */
+lines: number
+/**
+ * Maximum CRAP score among functions in this file. Computed via the active `coverage_model` per the canonical formula CC^2 * (1 - cov/100)^3 + CC (Savoia & Evans, 2007). Coverage source: `static_estimated` (default, graph-based per-function estimate), `istanbul` (real per-function statement coverage from --coverage), or the legacy `static_binary` (whole-file 0%/100%, retained for compatibility).
+ */
+crap_max: number
+/**
+ * Count of functions with CRAP score >= 30 (CC >= 5 without test dependency path).
+ */
+crap_above_threshold: number
+}
+/**
+ * A hotspot: a file that is both complex and frequently changing. Score = normalized_churn × normalized_complexity × 100 (0–100, higher = riskier).
+ */
+export interface HotspotEntry {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Hotspot score (0–100). Higher means more risk.
+ */
+score: number
+/**
+ * Number of commits touching this file in the analysis window.
+ */
+commits: number
+/**
+ * Recency-weighted commit count (exponential decay, half-life 90 days).
+ */
+weighted_commits: number
+/**
+ * Total lines added across all commits in the window.
+ */
+lines_added: number
+/**
+ * Total lines deleted across all commits in the window.
+ */
+lines_deleted: number
+/**
+ * Total cyclomatic complexity / lines of code.
+ */
+complexity_density: number
+/**
+ * Number of files that import this file (blast radius).
+ */
+fan_in: number
+/**
+ * Churn trend: accelerating (recent > 1.5× older), stable, or cooling (recent < 0.67× older).
+ */
+trend: ("accelerating" | "stable" | "cooling")
+/**
+ * Suggested actions to reduce hotspot risk.
+ */
+actions?: HotspotAction[]
+ownership?: OwnershipMetrics
+}
+/**
+ * A suggested action for a hotspot file. Ownership-derived action types (low-bus-factor, unowned-hotspot, ownership-drift) appear only when --ownership is enabled.
+ */
+export interface HotspotAction {
+/**
+ * Action type identifier.
+ */
+type: ("refactor-file" | "add-tests" | "low-bus-factor" | "unowned-hotspot" | "ownership-drift")
+/**
+ * Whether fallow can auto-fix this action.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the action.
+ */
+description: string
+/**
+ * Additional context for the action.
+ */
+note?: string
+/**
+ * Suggested CODEOWNERS pattern. Only present on unowned-hotspot actions. Derived per the heuristic field; consumers should branch on heuristic rather than assume a stable algorithm.
+ */
+suggested_pattern?: string
+/**
+ * Strategy used to derive suggested_pattern. Reserved for future evolution (e.g., 'codeowners-cluster').
+ */
+heuristic?: "directory-deepest"
+}
+/**
+ * Per-file ownership signals derived from git author history and CODEOWNERS. Only computed when --ownership is requested.
+ */
+export interface OwnershipMetrics {
+/**
+ * Avelino truck factor: minimum contributors covering at least 50% of recency-weighted commits in the analysis window. Lower = higher knowledge-loss risk.
+ */
+bus_factor: number
+/**
+ * Distinct authors after bot filtering.
+ */
+contributor_count: number
+top_contributor: ContributorEntry
+/**
+ * Up to three additional contributors by share, ordered descending. Useful for review routing.
+ */
+recent_contributors?: ContributorEntry[]
+/**
+ * CODEOWNERS-resolved primary owner for this file, when a rule matches.
+ */
+declared_owner?: (string | null)
+/**
+ * Tristate: true = CODEOWNERS file exists but no rule matches; false = a rule matches; null = no CODEOWNERS file discovered for the repository.
+ */
+unowned: (boolean | null)
+/**
+ * True when ownership has drifted from the original author to a new top contributor (file age >= 30 days, original author share < 10%).
+ */
+drift: boolean
+/**
+ * Human-readable explanation of the drift. Field is omitted (not null) when drift is false.
+ */
+drift_reason?: string
+}
+/**
+ * Per-author contribution summary. The identifier is rendered per the configured ownership.emailMode (handle, hash, or raw); the format field discriminates the three so type-aware consumers can branch without re-parsing.
+ */
+export interface ContributorEntry {
+/**
+ * Display string for the contributor. Raw email when format=raw (e.g. alice@example.com), local-part handle when format=handle (e.g. alice), or non-cryptographic pseudonym when format=hash (e.g. xxh3:abcdef0123456789). Do not assume this is an email address.
+ */
+identifier: string
+/**
+ * Discriminator for identifier shape. Set by ownership.emailMode at analysis time.
+ */
+format: ("raw" | "handle" | "hash")
+/**
+ * Recency-weighted share of total weighted commits, rounded to three decimals.
+ */
+share: number
+/**
+ * Days since this contributor last touched the file.
+ */
+stale_days: number
+/**
+ * Total commits by this contributor in the analysis window.
+ */
+commits: number
+}
+export interface HotspotSummary {
+/**
+ * Analysis window display string (e.g., '6 months').
+ */
+since: string
+/**
+ * Minimum commits threshold.
+ */
+min_commits: number
+/**
+ * Number of files with churn data meeting the threshold.
+ */
+files_analyzed: number
+/**
+ * Number of files excluded (below min_commits).
+ */
+files_excluded: number
+/**
+ * Whether the repository is a shallow clone.
+ */
+shallow_clone: boolean
+}
+/**
+ * Project-wide vital signs metrics. Optional fields are null when the corresponding analysis was not run.
+ */
+export interface VitalSigns {
+/**
+ * Percentage of unreachable files.
+ */
+dead_file_pct?: (number | null)
+/**
+ * Percentage of unused exports.
+ */
+dead_export_pct?: (number | null)
+/**
+ * Average cyclomatic complexity.
+ */
+avg_cyclomatic: number
+/**
+ * Percentage of functions at or above the critical cyclomatic threshold. Used by the scale-invariant health score.
+ */
+critical_complexity_pct?: (number | null)
+/**
+ * 90th percentile cyclomatic complexity.
+ */
+p90_cyclomatic: number
+/**
+ * Code duplication percentage. Null if duplication pipeline was not run.
+ */
+duplication_pct?: (number | null)
+/**
+ * Files with hotspot score >= 50. Null if git history unavailable.
+ */
+hotspot_count?: (number | null)
+/**
+ * Files in the top 1% of the within-project hotspot ranking. Null if git history unavailable.
+ */
+hotspot_top_pct_count?: (number | null)
+/**
+ * Average maintainability index (0-100).
+ */
+maintainability_avg?: (number | null)
+/**
+ * Percentage of scored files with maintainability index below 70. Null if file scores were not computed.
+ */
+maintainability_low_pct?: (number | null)
+/**
+ * Number of unused dependencies.
+ */
+unused_dep_count?: (number | null)
+/**
+ * Unused dependencies per 1,000 files. Null if dead code analysis did not run.
+ */
+unused_deps_per_k_files?: (number | null)
+/**
+ * Number of circular dependency chains.
+ */
+circular_dep_count?: (number | null)
+/**
+ * Circular dependency chains per 1,000 files. Null if dead code analysis did not run.
+ */
+circular_deps_per_k_files?: (number | null)
+counts?: VitalSignsCounts
+unit_size_profile?: RiskProfile
+/**
+ * Functions above 60 LOC per 1,000 functions. Null if no functions analyzed.
+ */
+functions_over_60_loc_per_k?: (number | null)
+unit_interfacing_profile?: RiskProfile
+/**
+ * 95th percentile fan-in across all files. Null if file scores not computed.
+ */
+p95_fan_in?: (number | null)
+/**
+ * Percentage of files with fan-in above the effective threshold. Null if file scores not computed.
+ */
+coupling_high_pct?: (number | null)
+/**
+ * Total lines of code across all parsed modules. 0 if no modules parsed.
+ */
+total_loc?: number
+}
+/**
+ * Raw counts behind the vital signs percentages.
+ */
+export interface VitalSignsCounts {
+/**
+ * Total number of discovered source files.
+ */
+total_files?: number
+/**
+ * Total number of exports across all files.
+ */
+total_exports?: number
+/**
+ * Number of unreachable files.
+ */
+dead_files?: number
+/**
+ * Number of unused exports.
+ */
+dead_exports?: number
+}
+/**
+ * Risk profile: percentage of functions in each risk bin. Bins depend on the measured property (unit size or parameter count).
+ */
+export interface RiskProfile {
+/**
+ * Percentage of functions in the low-risk bin.
+ */
+low_risk: number
+/**
+ * Percentage of functions in the medium-risk bin.
+ */
+medium_risk: number
+/**
+ * Percentage of functions in the high-risk bin.
+ */
+high_risk: number
+/**
+ * Percentage of functions in the very-high-risk bin.
+ */
+very_high_risk: number
+}
+/**
+ * Project-level health score. Score = 100 minus available penalties from dead code, complexity, maintainability, hotspots, unused deps, circular deps, unit size, coupling, and duplication. Missing metrics do not penalize; --score computes the score and duplication penalty, while churn-backed hotspot penalties require hotspot analysis (--hotspots, or --targets with --score).
+ */
+export interface HealthScore {
+/**
+ * Health score formula version. Version 2 uses scale-invariant density/tail metrics for monorepo-safe scoring.
+ */
+formula_version: number
+/**
+ * Overall score (0-100, higher is better). Reproducible: 100 - sum(penalties) == score.
+ */
+score: number
+/**
+ * Letter grade. A: score >= 85, B: 70-84, C: 55-69, D: 40-54, F: below 40.
+ */
+grade: ("A" | "B" | "C" | "D" | "F")
+penalties: HealthScorePenalties
+}
+/**
+ * Per-component penalty breakdown. Each field shows points subtracted. None/absent means the metric was not available (pipeline didn't run). Sum of all penalties = 100 - score.
+ */
+export interface HealthScorePenalties {
+/**
+ * Points lost from dead files (max 15). Null if dead code pipeline not run.
+ */
+dead_files?: (number | null)
+/**
+ * Points lost from dead exports (max 15). Null if dead code pipeline not run.
+ */
+dead_exports?: (number | null)
+/**
+ * Points lost from critical-complexity density (max 20). Older snapshots without density fields fall back to average cyclomatic complexity above 1.5.
+ */
+complexity: number
+/**
+ * Points lost from legacy p90 cyclomatic complexity above 10. Current scale-invariant runs report 0 because tail complexity is folded into complexity.
+ */
+p90_complexity: number
+/**
+ * Points lost from low maintainability density (max 15). Null if file-scores not computed.
+ */
+maintainability?: (number | null)
+/**
+ * Points lost from top-percentile hotspot density (max 10). Null if hotspots not computed.
+ */
+hotspots?: (number | null)
+/**
+ * Points lost from unused dependency density (max 25). Null if dead code pipeline not run.
+ */
+unused_deps?: (number | null)
+/**
+ * Points lost from circular dependency density (max 25). Null if dead code pipeline not run.
+ */
+circular_deps?: (number | null)
+/**
+ * Points lost from oversized-function density (max 10). Null if no functions analyzed.
+ */
+unit_size?: (number | null)
+/**
+ * Points lost from coupling concentration density (max 5). Null if file scores not computed.
+ */
+coupling?: (number | null)
+/**
+ * Points lost from code duplication (max 10). Penalty = min(max(0, duplication_pct - 5) * 1, 10). Null if duplication pipeline not run.
+ */
+duplication?: (number | null)
+}
+/**
+ * A function exceeding 60 lines of code (very high risk size bin).
+ */
+export interface LargeFunctionEntry {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Function name, or "<anonymous>" for unnamed functions/arrows.
+ */
+name: string
+/**
+ * 1-based line number.
+ */
+line: number
+/**
+ * Number of lines in the function body.
+ */
+line_count: number
+}
+export interface RefactoringTarget {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Weighted priority score (0-100). Higher = more urgent.
+ */
+priority: number
+/**
+ * priority / effort_numeric (Low=1, Medium=2, High=3). Default sort order.
+ */
+efficiency: number
+/**
+ * Human-readable one-line recommendation.
+ */
+recommendation: string
+/**
+ * Recommendation category.
+ */
+category: ("urgent_churn_complexity" | "break_circular_dependency" | "split_high_impact" | "remove_dead_code" | "extract_complex_functions" | "extract_dependencies")
+/**
+ * Heuristic effort estimate.
+ */
+effort: ("low" | "medium" | "high")
+/**
+ * Data source reliability. High = deterministic analysis, Medium = heuristic, Low = git-dependent.
+ */
+confidence: ("high" | "medium" | "low")
+/**
+ * Contributing factors that triggered this recommendation. Empty array omitted from JSON.
+ */
+factors?: {
+/**
+ * Metric name (fan_in, dead_code_ratio, etc.).
+ */
+metric: string
+/**
+ * Raw metric value.
+ */
+value: number
+/**
+ * Threshold that was exceeded.
+ */
+threshold: number
+/**
+ * Human-readable explanation.
+ */
+detail: string
+}[]
+/**
+ * Structured evidence for supported categories. Omitted when not applicable.
+ */
+evidence?: {
+/**
+ * Names of unused exports (for remove_dead_code).
+ */
+unused_exports?: string[]
+/**
+ * Complex functions with line numbers (for extract_complex_functions).
+ */
+complex_functions?: {
+name?: string
+line?: number
+cognitive?: number
+}[]
+/**
+ * Files in the import cycle (for break_circular_dependency).
+ */
+cycle_path?: string[]
+}
+/**
+ * Suggested actions for this refactoring target.
+ */
+actions?: RefactoringTargetAction[]
+}
+/**
+ * A suggested action for a refactoring target.
+ */
+export interface RefactoringTargetAction {
+/**
+ * Action type identifier.
+ */
+type: ("apply-refactoring" | "suppress-line")
+/**
+ * Whether fallow can auto-fix this action.
+ */
+auto_fixable: boolean
+/**
+ * Human-readable description of the action.
+ */
+description: string
+/**
+ * The recommendation category for apply-refactoring actions.
+ */
+category?: string
+/**
+ * The inline comment to insert. Present for suppress-line actions when evidence exists.
+ */
+comment?: string
+/**
+ * Where to insert the suppress comment. Present for suppress-line actions.
+ */
+placement?: string
+}
+/**
+ * Adaptive percentile-based thresholds derived from the project's metric distribution. Used for priority scoring and rule matching.
+ */
+export interface TargetThresholds {
+/**
+ * Fan-in saturation for priority formula (p95, floor 5).
+ */
+fan_in_p95: number
+/**
+ * Fan-in moderate threshold for contributing factors (p75, floor 3).
+ */
+fan_in_p75: number
+/**
+ * Fan-out saturation for priority formula (p95, floor 8).
+ */
+fan_out_p95: number
+/**
+ * Fan-out high threshold for rules and factors (p90, floor 5).
+ */
+fan_out_p90: number
+}
+/**
+ * Trend comparison between the current run and a previous snapshot. Shows per-metric deltas with directional indicators.
+ */
+export interface HealthTrend {
+/**
+ * The snapshot being compared against.
+ */
+compared_to: {
+/**
+ * ISO 8601 timestamp of the snapshot.
+ */
+timestamp: string
+/**
+ * Git SHA at time of snapshot.
+ */
+git_sha?: string
+/**
+ * Health score from the snapshot (stored, not re-derived).
+ */
+score?: number
+/**
+ * Letter grade from the snapshot.
+ */
+grade?: string
+}
+metrics: {
+/**
+ * Metric identifier (e.g., 'score', 'dead_file_pct').
+ */
+name: string
+/**
+ * Human-readable label.
+ */
+label: string
+/**
+ * Previous value (from snapshot).
+ */
+previous: number
+/**
+ * Current value (from this run).
+ */
+current: number
+/**
+ * Absolute change (current - previous).
+ */
+delta: number
+direction: ("improving" | "declining" | "stable")
+/**
+ * Unit for display (e.g., '%', '').
+ */
+unit: string
+previous_count?: TrendCount
+current_count?: TrendCount
+}[]
+/**
+ * Number of snapshots found in the snapshot directory.
+ */
+snapshots_loaded: number
+overall_direction: ("improving" | "declining" | "stable")
+}
+/**
+ * Raw numerator/denominator for a percentage metric in trend comparison.
+ */
+export interface TrendCount {
+/**
+ * The numerator (e.g., dead files count).
+ */
+value: number
+/**
+ * The denominator (e.g., total files).
+ */
+total: number
+}
+/**
+ * Static test coverage gaps derived from the module graph. Shows runtime files and exports with no test dependency path.
+ */
+export interface CoverageGaps {
+summary: CoverageGapSummary
+/**
+ * Runtime files with no test dependency path. Omitted when empty.
+ */
+files?: UntestedFile[]
+/**
+ * Runtime exports with no test-reachable reference chain. Omitted when empty.
+ */
+exports?: UntestedExport[]
+}
+/**
+ * Aggregate coverage-gap counters for the current analysis scope.
+ */
+export interface CoverageGapSummary {
+/**
+ * Runtime-reachable files in scope.
+ */
+runtime_files: number
+/**
+ * Runtime-reachable files also reachable from tests.
+ */
+covered_files: number
+/**
+ * Percentage of runtime files that are test-reachable.
+ */
+file_coverage_pct: number
+/**
+ * Runtime files with no test dependency path.
+ */
+untested_files: number
+/**
+ * Runtime exports with no test-reachable reference chain.
+ */
+untested_exports: number
+}
+/**
+ * A runtime file with no test dependency path.
+ */
+export interface UntestedFile {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Number of value exports declared by the file.
+ */
+value_export_count: number
+}
+/**
+ * A runtime export that no test-reachable module references.
+ */
+export interface UntestedExport {
+/**
+ * File path (relative to project root).
+ */
+path: string
+/**
+ * Export name.
+ */
+export_name: string
+/**
+ * 1-based source line.
+ */
+line: number
+/**
+ * 0-based source column.
+ */
+col: number
+}
+/**
+ * Runtime coverage findings merged into the health report or emitted by `fallow coverage analyze`. Present in health output when --runtime-coverage is used. Shape mirrors the runtime coverage JSON contract; cloud mode fetches runtime facts explicitly and merges them locally with AST/static analysis.
+ */
+export interface RuntimeCoverageReport {
+/**
+ * Runtime coverage JSON contract version. This is scoped to the runtime_coverage block and is independent of the top-level fallow JSON schema_version.
+ */
+schema_version: "1"
+verdict: RuntimeCoverageReportVerdict
+/**
+ * Every runtime-coverage signal the report carries, severity-descending. Independent of `verdict`. Empty when `verdict` is `clean` and there is no license grace. Used by JSON / SARIF / MCP consumers that want the complete set rather than the headline.
+ */
+signals?: RuntimeCoverageSignal[]
+summary: RuntimeCoverageSummary
+/**
+ * Surfaced runtime coverage findings (`safe_to_delete`, `review_required`, `low_traffic`, `coverage_unavailable`). Omitted when empty. `active` functions stay out of this list so the CLI output remains actionable.
+ */
+findings?: RuntimeCoverageFinding[]
+/**
+ * Top runtime functions by invocation count. Omitted when empty.
+ */
+hot_paths?: RuntimeCoverageHotPath[]
+/**
+ * First-class blast-radius entries for runtime-observed functions. Present whenever runtime coverage analysis runs.
+ */
+blast_radius?: RuntimeCoverageBlastRadiusEntry[]
+/**
+ * First-class production-importance entries for runtime-observed functions. Present whenever runtime coverage analysis runs.
+ */
+importance?: RuntimeCoverageImportanceEntry[]
+watermark?: RuntimeCoverageWatermark
+/**
+ * Non-fatal merge or coverage diagnostics. Omitted when empty.
+ */
+warnings?: RuntimeCoverageMessage[]
+}
+export interface RuntimeCoverageSummary {
+/**
+ * Runtime evidence source used for this report. Local mode reads a supplied runtime coverage artifact; cloud mode pulls the latest fallow.cloud runtime context after explicit opt-in.
+ */
+data_source: ("local" | "cloud")
+/**
+ * Timestamp of the newest runtime payload included in the report. Null for local single-capture artifacts that do not carry cloud receipt metadata.
+ */
+last_received_at: (string | null)
+/**
+ * Number of functions the sidecar could observe in the V8 or Istanbul dump.
+ */
+functions_tracked: number
+/**
+ * Tracked functions that received at least one invocation.
+ */
+functions_hit: number
+/**
+ * Tracked functions that were never invoked.
+ */
+functions_unhit: number
+/**
+ * Functions the sidecar could not track (lazy-parsed, worker thread, dynamic code, unresolved source map).
+ */
+functions_untracked: number
+/**
+ * Ratio of functions_hit / functions_tracked, expressed as a percent.
+ */
+coverage_percent: number
+/**
+ * Total number of observed invocations across all functions. Denominator for low-traffic classification.
+ */
+trace_count: number
+/**
+ * Days of observation covered by the supplied dump (Phase 2 local analysis emits 0 — set by the beacon/cloud in Phase 3+).
+ */
+period_days: number
+/**
+ * Distinct deployments contributing to the supplied dump (Phase 2 local analysis emits 0).
+ */
+deployments_seen: number
+capture_quality?: RuntimeCoverageCaptureQuality
+}
+/**
+ * Quality-of-capture signals emitted by the sidecar so the CLI can explain short-window captures honestly instead of letting users blame the tool.
+ */
+export interface RuntimeCoverageCaptureQuality {
+/**
+ * Total observation window in seconds. Finer-grained than period_days (which rounds up to whole days).
+ */
+window_seconds: number
+/**
+ * Number of distinct production instances that contributed to the dump.
+ */
+instances_observed: number
+/**
+ * True when the untracked-function ratio exceeds the sidecar's lazy-parse threshold (30%). Signals that many untracked functions likely reflect lazy-parsed code rather than unreachable code.
+ */
+lazy_parse_warning: boolean
+/**
+ * functions_untracked / functions_tracked as a percentage, rounded to 2 decimal places.
+ */
+untracked_ratio_percent: number
+}
+export interface RuntimeCoverageFinding {
+/**
+ * Stable content-hash ID of the form `fallow:prod:<hash>`, where <hash> is the first 8 hex characters of SHA-256(file + function + line + 'prod').
+ */
+id: string
+/**
+ * File path relative to the project root.
+ */
+path: string
+/**
+ * Static function name as reported in the merged coverage result.
+ */
+function: string
+/**
+ * 1-indexed line number the function starts on.
+ */
+line: number
+verdict: RuntimeCoverageVerdict
+/**
+ * Observed invocation count for the function. Omitted when the function is untracked (lazy-parsed, worker-thread isolate, dynamic code).
+ */
+invocations?: number
+confidence: RuntimeCoverageConfidence
+evidence: RuntimeCoverageEvidence
+/**
+ * Suggested actions for this finding. Omitted when empty.
+ */
+actions?: RuntimeCoverageAction[]
+}
+/**
+ * Supporting evidence for a runtime coverage finding. Mirrors the rows of the decision table.
+ */
+export interface RuntimeCoverageEvidence {
+/**
+ * `used` when the function is reachable in the module graph, `unused` otherwise.
+ */
+static_status: ("used" | "unused")
+/**
+ * `covered` when the project's test suite hits this function, `not_covered` otherwise.
+ */
+test_coverage: ("covered" | "not_covered")
+/**
+ * `tracked` when V8 observed the function, `untracked` otherwise.
+ */
+v8_tracking: ("tracked" | "untracked")
+/**
+ * Reason the function is untracked. Populated only when v8_tracking is `untracked`. Values: `lazy_parsed`, `worker_thread`, `dynamic_eval`, `unknown`.
+ */
+untracked_reason?: string
+/**
+ * Days of observation backing this finding.
+ */
+observation_days: number
+/**
+ * Distinct deployments backing this finding.
+ */
+deployments_observed: number
+}
+/**
+ * Suggested follow-up action for a runtime coverage finding.
+ */
+export interface RuntimeCoverageAction {
+/**
+ * Action identifier, normalized to `type` in JSON output. Known values emitted by `fallow coverage analyze`: `delete-cold-code` (verdict=safe_to_delete), `review-runtime` (verdict=review_required). The sidecar may emit additional protocol-specific identifiers; consumers should treat unknown values as forward-compat extensions.
+ */
+type: string
+/**
+ * Human-readable recommendation.
+ */
+description: string
+/**
+ * Whether fallow can apply this action automatically.
+ */
+auto_fixable: boolean
+}
+export interface RuntimeCoverageHotPath {
+/**
+ * Stable content-hash ID of the form `fallow:hot:<hash>`.
+ */
+id: string
+/**
+ * File path relative to the project root.
+ */
+path: string
+/**
+ * Function name for the hot path.
+ */
+function: string
+/**
+ * 1-indexed line number the function starts on.
+ */
+line: number
+/**
+ * 1-indexed line the function ends on (inclusive). `0` indicates the value was unavailable (older protocol-0.4 sidecars), in which case consumers MUST treat the range as a single line at `line`.
+ */
+end_line: number
+/**
+ * Observed invocation count for the hot path.
+ */
+invocations: number
+/**
+ * Percentile rank over this response's hot-path distribution. 100 = busiest, 0 = quietest that still qualified.
+ */
+percentile: number
+/**
+ * Suggested actions for this hot path (e.g., review-on-change). Omitted when empty.
+ */
+actions?: RuntimeCoverageAction[]
+}
+export interface RuntimeCoverageBlastRadiusEntry {
+/**
+ * Stable content-hash ID of the form `fallow:blast:<hash>`.
+ */
+id: string
+/**
+ * File path relative to the project root.
+ */
+file: string
+/**
+ * Function name for the blast-radius entry.
+ */
+function: string
+/**
+ * 1-indexed line number the function starts on.
+ */
+line: number
+/**
+ * Static caller count from the module graph.
+ */
+caller_count: number
+/**
+ * Caller reach weighted by observed runtime traffic.
+ */
+caller_count_weighted_by_traffic: number
+/**
+ * Distinct deploy SHAs that touched the function in the observation window. Cloud mode only; omitted in local mode.
+ */
+deploys_touched?: number
+risk_band: RuntimeCoverageRiskBand
+}
+export interface RuntimeCoverageImportanceEntry {
+/**
+ * Stable content-hash ID of the form `fallow:importance:<hash>`.
+ */
+id: string
+/**
+ * File path relative to the project root.
+ */
+file: string
+/**
+ * Function name for the importance entry.
+ */
+function: string
+/**
+ * 1-indexed line number the function starts on.
+ */
+line: number
+/**
+ * Observed invocation count for this function.
+ */
+invocations: number
+/**
+ * Cyclomatic complexity from the static health pipeline.
+ */
+cyclomatic: number
+/**
+ * Number of CODEOWNERS owners matched for this file. Zero means no owner was resolved.
+ */
+owner_count: number
+/**
+ * 0-100 explainable score from log-scaled traffic, capped complexity weight, and ownership-risk weight.
+ */
+importance_score: number
+/**
+ * Templated one-sentence explanation for the score.
+ */
+reason: string
+}
+export interface RuntimeCoverageMessage {
+/**
+ * Stable warning code.
+ */
+code: string
+/**
+ * Human-readable warning message.
+ */
+message: string
+}
+/**
+ * A health report scoped to a single resolver bucket (workspace package, CODEOWNERS owner, directory, or GitLab CODEOWNERS section). Carries per-group vital_signs / health_score plus the per-file output (findings, file scores, hotspots, large functions, refactoring targets) restricted to the same subset.
+ */
+export interface HealthGroup {
+/**
+ * Group identifier produced by the resolver. For 'package' grouping: workspace package name (e.g. '@scope/app-a') or '(root)' for files outside any workspace. For 'owner' grouping: the CODEOWNERS team. For 'directory' grouping: the top-level directory prefix. For 'section' grouping: the GitLab CODEOWNERS section name, or '(no section)' / '(unowned)' for unmatched files.
+ */
+key: string
+/**
+ * Section default owners (GitLab CODEOWNERS `[Section] @owner1 @owner2`). Present only when grouped_by is 'section'.
+ */
+owners?: string[]
+/**
+ * Number of files in this group after workspace, ignore, and changed-since filters.
+ */
+files_analyzed: number
+/**
+ * Number of findings rendered for this group (post-baseline / post-`--top` truncation, mirroring HealthSummary semantics).
+ */
+functions_above_threshold: number
+vital_signs?: VitalSigns
+health_score?: HealthScore
+/**
+ * Findings restricted to files in this group. Omitted when empty.
+ */
+findings?: HealthFinding[]
+/**
+ * File scores restricted to files in this group. Omitted when empty.
+ */
+file_scores?: FileHealthScore[]
+/**
+ * Hotspots restricted to files in this group. Omitted when empty.
+ */
+hotspots?: HotspotEntry[]
+/**
+ * Large functions in files belonging to this group. Omitted when empty.
+ */
+large_functions?: LargeFunctionEntry[]
+/**
+ * Refactoring targets in files belonging to this group. Omitted when empty.
+ */
+targets?: RefactoringTarget[]
+}
+/**
+ * Grouped dead code output produced when --group-by is active. Issues are partitioned into groups (by CODEOWNERS team, directory prefix, workspace package, or GitLab CODEOWNERS section) instead of flat arrays.
+ */
+export interface CheckGroupedOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+elapsed_ms: ElapsedMs
+/**
+ * The grouping strategy used. 'owner' groups by CODEOWNERS team, 'directory' groups by top-level directory prefix, 'package' groups by workspace package name, 'section' groups by GitLab CODEOWNERS `[Section]` header name.
+ */
+grouped_by: ("owner" | "directory" | "package" | "section")
+/**
+ * Total number of issues across all groups.
+ */
+total_issues: number
+/**
+ * One entry per group, each containing the same issue arrays as the ungrouped CheckOutput.
+ */
+groups: CheckGroupedEntry[]
+_meta?: Meta
+}
+/**
+ * A single group within grouped dead code output. Contains the group key, a per-group total, and the same issue arrays as CheckOutput.
+ */
+export interface CheckGroupedEntry {
+/**
+ * Group identifier. For 'owner' grouping: the CODEOWNERS team (e.g., '@team-name'). For 'directory' grouping: the top-level directory prefix (e.g., 'src/components'). For 'section' grouping: the GitLab CODEOWNERS section name (e.g., 'billing'), or '(no section)' for files owned by a rule declared before any section header.
+ */
+key: string
+/**
+ * Section default owners (GitLab CODEOWNERS `[Section] @owner1 @owner2`). Emitted only when grouped_by is 'section'. Empty for the '(no section)' and '(unowned)' buckets.
+ */
+owners?: string[]
+/**
+ * Total number of issues in this group.
+ */
+total_issues: number
+unused_files: UnusedFile[]
+unused_exports: UnusedExport[]
+unused_types: UnusedExport[]
+private_type_leaks: PrivateTypeLeak[]
+unused_dependencies: UnusedDependency[]
+unused_dev_dependencies: UnusedDependency[]
+unused_optional_dependencies: UnusedDependency[]
+unused_enum_members: UnusedMember[]
+unused_class_members: UnusedMember[]
+unresolved_imports: UnresolvedImport[]
+unlisted_dependencies: UnlistedDependency[]
+duplicate_exports: DuplicateExport[]
+type_only_dependencies: TypeOnlyDependency[]
+test_only_dependencies: TestOnlyDependency[]
+circular_dependencies: CircularDependency[]
+boundary_violations: BoundaryViolation[]
+stale_suppressions?: StaleSuppression[]
+}
+/**
+ * Audit output combining dead code, complexity, and duplication scoped to changed files. Returns a verdict (pass/warn/fail) with per-category summary, optional new-vs-inherited attribution, and full sub-results.
+ */
+export interface AuditOutput {
+schema_version: SchemaVersion
+version: ToolVersion
+command: "audit"
+/**
+ * pass = no issues, warn = warn-severity only (exit 0), fail = error-severity issues (exit 1)
+ */
+verdict: ("pass" | "warn" | "fail")
+/**
+ * Number of files changed between base ref and HEAD
+ */
+changed_files_count: number
+/**
+ * Git ref used as comparison base (explicit or auto-detected)
+ */
+base_ref: string
+/**
+ * Short SHA of HEAD (omitted if git unavailable)
+ */
+head_sha?: string
+elapsed_ms: ElapsedMs
+/**
+ * Only emitted when --performance is set. true means audit reused the current run's keys as the base snapshot because every changed file was either a non-behavioral doc or token-equivalent at the base ref (the docs-only-diff fast path); false means the regular base worktree analysis ran.
+ */
+base_snapshot_skipped?: boolean
+summary: {
+dead_code_issues?: number
+dead_code_has_errors?: boolean
+complexity_findings?: number
+max_cyclomatic?: (number | null)
+duplication_clone_groups?: number
+}
+/**
+ * Counts split by whether each finding was introduced by the current changeset or already existed at the base ref. The default audit gate is new-only, so inherited findings are context. With audit.gate or --gate set to all, audit skips the extra base-snapshot attribution pass and these counts stay zero.
+ */
+attribution: {
+/**
+ * Which findings affect the audit verdict.
+ */
+gate: ("new-only" | "all")
+dead_code_introduced: number
+dead_code_inherited: number
+complexity_introduced: number
+complexity_inherited: number
+duplication_introduced: number
+duplication_inherited: number
+}
+dead_code?: CheckOutput
+duplication?: DupesOutput
+complexity?: HealthOutput
+}
+/**
+ * Standalone rule explanation for one issue type. This command does not run project analysis and intentionally returns a compact object without schema_version/version metadata.
+ */
+export interface ExplainOutput {
+/**
+ * Canonical rule id, for example fallow/unused-export.
+ */
+id: string
+/**
+ * Human-readable rule name.
+ */
+name: string
+/**
+ * Short one-line explanation of the issue.
+ */
+summary: string
+/**
+ * Why the issue matters and what fallow checks.
+ */
+rationale: string
+/**
+ * Concrete example of the finding.
+ */
+example: string
+/**
+ * Recommended fix or suppression guidance.
+ */
+how_to_fix: string
+/**
+ * Docs URL for the rule.
+ */
+docs: string
+}
+/**
+ * Deterministic agent-readable runtime coverage setup instructions. In workspaces, members contains one entry per detected runtime package and runtime_targets is the union of all member targets. With --explain, an optional _meta object describes fields, enums, and warning semantics.
+ */
+export interface CoverageSetupOutput {
+schema_version: "1"
+/**
+ * Primary detected runtime framework. For workspaces this mirrors the first emitted runtime member; unknown means no runtime member was detected.
+ */
+framework_detected: ("nextjs" | "nestjs" | "nuxt" | "sveltekit" | "astro" | "remix" | "vite" | "plain_node" | "unknown")
+package_manager: ("npm" | "pnpm" | "yarn" | "bun" | null)
+/**
+ * Union of runtime targets across emitted members.
+ */
+runtime_targets: ("node" | "browser")[]
+/**
+ * Per-runtime-workspace setup recipes. Pure aggregator roots and build-only library packages are omitted.
+ */
+members: CoverageSetupMember[]
+config_written: null
+commands: string[]
+/**
+ * Compatibility copy of the primary member's files, with workspace prefixes when the primary member is not the root.
+ */
+files_to_edit: CoverageSetupFileToEdit[]
+/**
+ * Compatibility copy of the primary member's snippets, with workspace prefixes when the primary member is not the root.
+ */
+snippets: CoverageSetupSnippet[]
+dockerfile_snippet: (string | null)
+next_steps: string[]
+warnings: string[]
+/**
+ * Optional explain metadata emitted only with fallow coverage setup --json --explain.
+ */
+_meta?: {
+[k: string]: unknown
+}
+}
+export interface CoverageSetupMember {
+name: string
+/**
+ * Workspace path relative to the analyzed root, or . for the root member.
+ */
+path: string
+framework_detected: ("nextjs" | "nestjs" | "nuxt" | "sveltekit" | "astro" | "remix" | "vite" | "plain_node" | "unknown")
+package_manager: ("npm" | "pnpm" | "yarn" | "bun" | null)
+runtime_targets: ("node" | "browser")[]
+files_to_edit: CoverageSetupFileToEdit[]
+snippets: CoverageSetupSnippet[]
+dockerfile_snippet: (string | null)
+warnings: string[]
+}
+export interface CoverageSetupFileToEdit {
+path: string
+reason: string
+}
+export interface CoverageSetupSnippet {
+label: string
+path: string
+content: string
+}
+export interface CodeClimateIssue {
+type: "issue"
+check_name: string
+description: string
+categories: string[]
+severity: ("info" | "minor" | "major" | "critical" | "blocker")
+fingerprint: string
+location: {
+path: string
+lines: {
+begin: number
+}
+}
+}
+/**
+ * Typed review envelope consumed by action/scripts/review.sh and ci/scripts/review.sh.
+ */
+export interface ReviewEnvelopeOutput {
+/**
+ * GitHub review event. Omitted for GitLab.
+ */
+event?: "COMMENT"
+body: string
+comments: (GitHubReviewComment | GitLabReviewComment)[]
+meta: {
+schema: "fallow-review-envelope/v1"
+provider: ("github" | "gitlab")
+check_conclusion?: ("success" | "neutral" | "failure")
+}
+}
+export interface GitHubReviewComment {
+path: string
+line: number
+/**
+ * GitHub review comments target current-state/new-side lines; deletion-side comments are not modeled yet.
+ */
+side: "RIGHT"
+body: string
+fingerprint: string
+}
+export interface GitLabReviewComment {
+body: string
+position: GitLabReviewPosition
+fingerprint: string
+}
+export interface GitLabReviewPosition {
+base_sha?: string
+start_sha?: string
+head_sha?: string
+position_type: "text"
+old_path: string
+new_path: string
+new_line: number
+}
+export interface ReviewReconcileOutput {
+schema: "fallow-review-reconcile/v1"
+provider: ("github" | "gitlab")
+target: (string | null)
+dry_run: boolean
+comments: number
+current_fingerprints: number
+existing_fingerprints: number
+new_fingerprints: number
+stale_fingerprints: number
+new: string[]
+stale: string[]
+provider_warning?: (string | null)
+resolution_comments_posted: number
+threads_resolved: number
+apply_errors: string[]
+}