Crate fallow_api 

Programmatic API contract types for fallow.

Runtime execution for dead-code, duplication and health lives here. The default health runner, EngineHealthRunner, runs the engine pipeline. Tests and hosts can inject a different runner. This crate owns the CLI-independent option, error, and output contracts so NAPI, future Rust embedders, and the engine facade can share them without depending on the CLI crate.

Re-exports

pub use audit_output::AuditAttribution;

pub use audit_output::AuditCodeClimateOutputInput;

pub use audit_output::AuditJsonHeaderInput;

pub use audit_output::AuditJsonOutputInput;

pub use audit_output::AuditSarifOutputInput;

pub use audit_output::AuditSummary;

pub use audit_output::AuditVerdict;

pub use audit_output::attach_audit_duplication_demotion_attribution;

pub use audit_output::attach_audit_styling_attribution;

pub use audit_output::attach_audit_wire_attribution;

pub use audit_output::build_audit_codeclimate;

pub use audit_output::build_audit_codeclimate_issues;

pub use audit_output::build_audit_header_json;

pub use audit_output::build_audit_header_map;

pub use audit_output::build_audit_sarif;

pub use audit_output::build_review_brief_header;

pub use audit_output::serialize_audit_json;

pub use combined_output::CombinedCheckJsonSection;

pub use combined_output::CombinedJsonOutputInput;

pub use combined_output::serialize_combined_dupes_json;

pub use combined_output::serialize_combined_health_json;

pub use combined_output::serialize_combined_json;

pub use compact_output::build_compact_lines;

pub use compact_output::build_duplication_compact_lines;

pub use compact_output::build_grouped_compact_lines;

pub use compact_output::build_health_compact_lines;

pub use coverage::CoverageInputError;

pub use coverage::CoverageInputSource;

pub use coverage::CoverageInputs;

pub use coverage::resolve_coverage_inputs;

pub use dead_code_codeclimate::build_codeclimate;

pub use doctor::DoctorOptions;

pub use doctor::run_doctor;

pub use doctor::run_doctor_with_cache_dir;

pub use dupes_output::AttributedCloneGroup;

pub use dupes_output::AttributedCloneGroupFinding;

pub use dupes_output::AttributedInstance;

pub use dupes_output::CloneDemotionReason;

pub use dupes_output::CloneFamilyFinding;

pub use dupes_output::CloneGroupFinding;

pub use dupes_output::CombinedDupesSection;

pub use dupes_output::DupesReportPayload;

pub use dupes_output::DuplicationGroup;

pub use dupes_output::DuplicationGrouping;

pub use dupes_output::build_duplication_codeclimate;

pub use editor::ChangedFilesError;

pub use editor::EditorAnalysisOutput;

pub use editor::EditorAnalysisResults;

pub use editor::EditorAnalysisSession;

pub use editor::EditorCloneFamily;

pub use editor::EditorCloneFingerprintSet;

pub use editor::EditorCloneGroup;

pub use editor::EditorCloneInstance;

pub use editor::EditorDeadCodeAnalysisOutput;

pub use editor::EditorDuplicationReport;

pub use editor::EditorDuplicationStats;

pub use editor::EditorInlineComplexityExceeded;

pub use editor::EditorInlineComplexityFinding;

pub use editor::EditorMirroredDirectory;

pub use editor::EditorProjectAnalysisOutput;

pub use editor::EditorRefactoringKind;

pub use editor::EditorRefactoringSuggestion;

pub use editor::EditorSessionParseCounts;

pub use editor::collect_inline_complexity;

pub use editor::editor_duplicates;

pub use editor::editor_extract;

pub use editor::editor_results;

pub use editor::editor_security;

pub use editor::editor_suppress;

pub use editor::filter_inline_complexity_by_changed_files;

pub use editor::resolve_git_toplevel;

pub use editor::try_get_changed_files_with_toplevel;

pub use explain::CHECK_RULES;

pub use explain::DUPES_RULES;

pub use explain::FLAGS_RULES;

pub use explain::HEALTH_RULES;

pub use explain::RuleDef;

pub use explain::RuleGuide;

pub use explain::SECURITY_RULES;

pub use explain::all_rules;

pub use explain::bare_rule_id;

pub use explain::coverage_analyze_meta;

pub use explain::coverage_setup_meta;

pub use explain::explain_issue_type;

pub use explain::rule_by_id;

pub use explain::rule_by_token;

pub use explain::rule_command;

pub use explain::rule_docs_url;

pub use explain::rule_guide;

pub use explain::rule_severity_key;

pub use explain::security_meta;

pub use explain::serialize_explain_programmatic_json;

pub use explain::unknown_explain_error;

pub use grouped_output::ResultGroup;

pub use grouped_output::UNOWNED_GROUP_LABEL;

pub use grouped_output::build_duplication_grouping_with;

pub use grouped_output::group_analysis_results_with;

pub use grouped_output::largest_clone_group_owner_with;

pub use health_codeclimate::build_health_codeclimate;

pub use json_output::CheckJsonExtraOutputs;

pub use json_output::CheckJsonOutputInput;

pub use json_output::CheckJsonPayloadInput;

pub use json_output::DuplicationJsonOutputInput;

pub use json_output::GroupedCheckJsonOutputInput;

pub use json_output::GroupedDuplicationJsonOutputInput;

pub use json_output::serialize_check_json;

pub use json_output::serialize_check_json_payload;

pub use json_output::serialize_duplication_json;

pub use json_output::serialize_grouped_check_json;

pub use json_output::serialize_grouped_duplication_json;

pub use list_output::ListJsonEnvelope;

pub use list_output::ListJsonOutputInput;

pub use list_output::build_list_json_output;

pub use list_output::serialize_list_json_output;

pub use markdown_output::build_duplication_markdown;

pub use markdown_output::build_grouped_markdown;

pub use markdown_output::build_health_markdown;

pub use markdown_output::build_markdown;

pub use markdown_output::build_walkthrough_markdown;

pub use output_contracts::AuditOutput;

pub use output_contracts::BoundariesListLogicalGroup;

pub use output_contracts::BoundariesListRule;

pub use output_contracts::BoundariesListZone;

pub use output_contracts::BoundariesListing;

pub use output_contracts::CombinedOutput;

pub use output_contracts::FallowOutput;

pub use output_contracts::ImpactOutput;

pub use output_contracts::ListBoundariesOutput;

pub use output_contracts::ListEntryPointOutput;

pub use output_contracts::ListOutput;

pub use output_contracts::ListPluginOutput;

pub use output_contracts::ReviewBriefWireOutput;

pub use output_contracts::SecurityGate;

pub use output_contracts::SecurityOutput;

pub use output_contracts::SecurityOutputConfig;

pub use output_contracts::SecuritySummaryOutput;

pub use output_contracts::SimilarCodeCandidateSnapshot;

pub use output_contracts::SimilarCodeOutput;

pub use output_contracts::TraceOutput;

pub use output_contracts::WorkspacesOutput;

pub use runtime::AuditProgrammaticKeySnapshot;

pub use runtime::AuditProgrammaticOutput;

pub use runtime::BoundaryViolationsOutput;

pub use runtime::BoundaryViolationsProgrammaticOutput;

pub use runtime::CircularDependenciesOutput;

pub use runtime::CircularDependenciesProgrammaticOutput;

pub use runtime::CombinedProgrammaticOutput;

pub use runtime::DeadCodeOutput;

pub use runtime::DeadCodeProgrammaticOutput;

pub use runtime::DecisionSurfaceProgrammaticOutput;

pub use runtime::DuplicationOutput;

pub use runtime::DuplicationProgrammaticOutput;

pub use runtime::EngineHealthRunner;

pub use runtime::FeatureFlagsOutput;

pub use runtime::FeatureFlagsProgrammaticOutput;

pub use runtime::HealthJsonReportInput;

pub use runtime::HealthProgrammaticOutput;

pub use runtime::ProgrammaticHealthAnalysis;

pub use runtime::ProgrammaticHealthNextStepFacts;

pub use runtime::ProgrammaticHealthRun;

pub use runtime::ProgrammaticHealthRunner;

pub use runtime::TraceClassMemberOutput;

pub use runtime::TraceCloneOutput;

pub use runtime::TraceCloneProgrammaticOutput;

pub use runtime::TraceDependencyOutput;

pub use runtime::TraceDependencyProgrammaticOutput;

pub use runtime::TraceErrorOutput;

pub use runtime::TraceErrorProgrammaticOutput;

pub use runtime::TraceExportOutput;

pub use runtime::TraceExportProgrammaticOutput;

pub use runtime::TraceExportTargetOutput;

pub use runtime::TraceFileOutput;

pub use runtime::TraceFileProgrammaticOutput;

pub use runtime::TraceImportPathOutput;

pub use runtime::TraceImportPathProgrammaticOutput;

pub use runtime::inspect_similar_code;

pub use runtime::load_health_config;

pub use runtime::parse_similar_code_candidate_snapshot;

pub use runtime::review_similar_code;

pub use runtime::run_audit;

pub use runtime::run_boundary_violations;

pub use runtime::run_circular_dependencies;

pub use runtime::run_combined;

pub use runtime::run_complexity_with_runner;

pub use runtime::run_dead_code;

pub use runtime::run_dead_code_with_baseline;

pub use runtime::run_decision_surface;

pub use runtime::run_duplication;

pub use runtime::run_feature_flags;

pub use runtime::run_health;

pub use runtime::run_health_with_runner;

pub use runtime::run_similar_code;

pub use runtime::run_trace_clone;

pub use runtime::run_trace_dependency;

pub use runtime::run_trace_error;

pub use runtime::run_trace_export;

pub use runtime::run_trace_file;

pub use runtime::run_trace_import_path;

pub use runtime::select_similar_code_candidate_snapshot;

pub use runtime::serialize_health_report_json;

pub use security_output::SecurityGateMode;

Modules

audit_keys

Stable per-finding keys and audit ledgers that compare head results against a base snapshot, plus helpers that annotate output JSON with introduced-vs-pre-existing attribution.

audit_output

Shared audit JSON payload contracts for programmatic consumers.

audit_run

The changed-code audit.

combined_output

Combined JSON output assembly shared by CLI and programmatic consumers.

compact_output

One-line-per-finding compact text builders for dead-code, grouped, health, and duplication output.

coverage

Istanbul coverage input precedence shared by every surface that feeds CRAP scoring: the explicit flag or tool parameter, then FALLOW_COVERAGE / FALLOW_COVERAGE_ROOT, then health.coverage / health.coverageRoot from the project config. Engine auto-detection of coverage/coverage-final.json applies only when every layer leaves the coverage path unset.

dead_code_codeclimate

Shared dead-code CodeClimate issue construction.

dead_code_sarif

Compatibility re-export for dead-code SARIF assembly now owned by fallow-output.

decision_surface

Decision-surface extractor (stage 6 / 6.G): THE product.

dependency_deltas

Dependency deltas for the decision surface: what a changed package.json adds or moves across a major version, read from the base and head manifest text, projected onto DependencyAnchors. Pure over its inputs; the CLI reads base text through git and the typed runtime through the base worktree, and both hand the pairs to dependency_anchors_from_manifests so the two routes cannot drift.

doctor

Read-only project readiness inspection.

dupes_output

Shared duplication JSON payload contracts for programmatic consumers.

editor

Editor-facing analysis contracts shared by LSP and future editor adapters.

explain

Metric and rule definitions for explainable CLI output.

grouped_output

Shared grouped-output builders for programmatic and CLI consumers.

health_codeclimate

Shared health CodeClimate issue construction.

json_output

Shared JSON output assembly for CLI and programmatic consumers.

list_output

Shared list command JSON output assembly.

markdown_output

Markdown report builders for dead-code, grouped, duplication, health, and walkthrough output.

output_contracts

Concrete output-contract aliases shared by schema and adapter crates.

ownership

Owner-group reach of a changeset for the review brief.

review_deltas

Diff-aware deterministic deltas for the review brief (6.A).

routing

Ownership-aware reviewer routing (6.D).

runtime

Programmatic runtime entry points that avoid depending on fallow-cli.

sarif_output

Compatibility re-exports for SARIF assembly now owned by fallow-output.

schemas

JSON Schema documents and zero-config rule defaults re-exported from fallow-config for embedders such as the MCP resource surface. JSON Schema documents and zero-config rule defaults, re-exported from fallow-config for embedders that must not depend on the config crate directly (the MCP server’s fallow://schema/* and fallow://issue-types resources). Each function returns the exact document the matching CLI command prints (fallow config-schema, fallow plugin-schema, fallow rule-pack-schema), so a cached resource and a CLI dump agree.

security_output

Shared security JSON payload contracts for programmatic consumers.

similar_code

Local-only advisory similar-code discovery and provider status. Local-provider orchestration for advisory similar-code discovery.

warm_parse

Parsed modules that a long-lived process keeps across analysis calls.

Structs

AnalysisOptions

Shared options for all one-shot analyses.

AuditOptions

Options for changed-code audit analysis.

BoundaryData

Owned boundary listing data shared by CLI and programmatic renderers.

CloneTrace

Result of tracing a clone: all groups containing the code at a source location or addressed by a stable clone fingerprint.

CombinedOptions

Options for bare combined analysis through the programmatic API.

ComplexityCoverageInputs

Coverage inputs accepted by the programmatic API.

ComplexityOptions

Options for complexity / health analysis.

ComplexityRunOptions

Normalized programmatic complexity / health inputs owned by fallow-api.

ComplexitySectionOptions

Input for deriving effective programmatic complexity sections.

ComplexityThresholdOverrides

Health threshold overrides accepted by the programmatic API.

DeadCodeFilters

Issue-type filters for the dead-code analysis.

DeadCodeOptions

Options for dead-code-oriented analyses.

DecisionSurfaceOptions

Options for changed-code decision-surface analysis.

DependencyTrace

Result of tracing a dependency: where it is used.

DerivedComplexityOptions

Derived section selection for programmatic health / complexity runs.

DerivedHealthSections

Derived section selection for health runs.

DuplicationOptions

Options for duplication analysis.

ExportReference

A direct reference to an export.

ExportTrace

Result of tracing an export: why it is considered used or unused.

FeatureFlagsOptions

Options for feature-flag analysis.

FeatureFlagsRetirementOptions

Options of the flag retirement report, the --retirement mode of fallow flags.

FileTrace

Result of tracing all edges for a file.

HealthConfig

Configuration for complexity health metrics (fallow health).

HealthSectionOptions

Input for deriving effective health sections from API-owned flags.

ListBoundariesOptions

Options for fallow list --boundaries through the programmatic API.

ListBoundariesProgrammaticOutput

Typed output for fallow list --boundaries before JSON serialization.

LogicalGroupInfo

View-model mirror of LogicalGroup with derived file-count totals.

ProgrammaticAnalysisContext

Resolved common programmatic analysis context.

ProgrammaticError

Structured error surface for the programmatic API.

ProjectInfoOptions

Options for MCP/project metadata listing through the programmatic API.

ProjectInfoProgrammaticOutput

Typed output for project metadata listing before JSON serialization.

ReExportChain

A re-export chain showing how an export is propagated.

RuleInfo

One configured boundary allow rule.

SemanticCouplingOutcome

Coupling report plus shared metadata for report and integration surfaces.

SemanticDeadCodeOutcome

Result of applying a semantic batch to dead-code findings.

SemanticInspectOutcome

Every semantic inspect section resolved for one symbol.

SimilarCodeInspectOptions

Options for one similar-code candidate inspection packet.

SimilarCodeOptions

Options for local advisory similar-code discovery.

TraceCloneOptions

Options for duplicate-code trace analysis.

TraceDependencyOptions

Options for dependency trace analysis.

TraceErrorOptions

Options for stack-trace frame resolution.

TraceExportOptions

Options for export trace analysis.

TraceFileOptions

Options for file trace analysis.

TraceImportPathOptions

Options for shortest-import-path trace analysis.

TracedCloneGroup

One clone group returned from a clone trace request.

TracedExport

An export with usage information.

TracedReExport

A re-export with source information.

TypeAwareError

Opaque type-aware transport failure; the message is the full description.

TypeAwareFileChanges

Project-relative changes applied before the next persistent semantic query.

TypeAwareOptions

Typed options for Fallow’s optional TypeScript semantic companion.

TypeAwareOutcome

Result of a completed type-aware pass.

TypeAwareSession

Explicitly owned semantic sidecar session for one canonical project root.

TypeAwareStatus

Semantic-companion availability report produced by status.

ZoneInfo

One configured boundary zone with its matched file count.

Enums

AuditGate

Value of audit.gate: which findings drive the fallow audit verdict.

ComplexitySort

Sort criteria for complexity findings.

DuplicationMode

Programmatic duplication mode selection.

OwnershipEmailMode

Privacy mode for ownership-aware hotspot output.

TargetEffort

Effort filter for refactoring targets.

TraceCloneTarget

Duplicate-code trace target.

TypeAwareRequire

Completeness policy for opt-in TypeScript semantic analysis.

Constants

COMMON_ANALYSIS_OPTION_FLAGS

Long names of the analysis-affecting global CLI flags that AnalysisOptions mirrors for embedders.

Functions

analyze_type_coupling

Analyze project-local coupling between package-public TypeScript signatures.

annotate_sarif_results

Add a SARIF result property by resolving each result URI through a caller.

boundary_data_to_output

Convert boundary listing data to the stable output contract.

build_duplication_sarif

Build SARIF output from duplication analysis results.

build_grouped_duplication_sarif

Build grouped SARIF output from duplication analysis results.

build_health_sarif

Build SARIF output from a health report.

build_sarif

Builds the complete SARIF run value for a dead-code analysis.

closest_match

Find the closest candidate to input when it is plausibly a typo.

compute_boundary_data

Compute boundary listing data from resolved config and optional discovery.

derive_complexity_options

Derive effective programmatic health / complexity section flags.

derive_complexity_run_options

Normalize public API complexity options into engine-owned run contracts.

derive_complexity_sections

Derive effective programmatic health / complexity section flags.

derive_health_sections

Derive effective health section flags for API consumers.

discard_unverified_semantic_candidates

Drop findings that only exist pending semantic verification, so a failed type-aware pass never reports unverified candidates.

inspect_type_aware_symbol

Resolve every semantic inspect section in one sidecar request and one Program per project.

merge_type_aware_meta

Merge a second semantic capability batch into one run-level metadata block. This preserves the conservative completeness state and keeps every query visible to report, audit, SARIF, MCP, and editor consumers.

refine_type_aware_results_with_config

Refine dead-code results and reapply project finding exclusions after the semantic stage has finished adding or updating findings.

resolve_programmatic_analysis_context

Resolve common programmatic analysis options once for a concrete runtime.

run_list_boundaries

Run list_boundaries through the API-owned runtime path.

run_project_info

Run project metadata listing through the API-owned runtime path.

run_type_aware_symbol_impact

Compute exact-symbol consumers and a bounded targeted-test recommendation.

run_type_aware_symbol_trace

Resolve exact checker-backed references for one exported symbol.

serialize_audit_programmatic_json

Serialize typed audit output into the stable JSON compatibility contract.

serialize_boundary_violations_programmatic_json

Serialize typed boundary-family output into the JSON compatibility contract.

serialize_circular_dependencies_programmatic_json

Serialize typed circular-dependency output into the JSON compatibility contract.

serialize_combined_programmatic_json

Serialize typed combined output into the stable JSON compatibility contract.

serialize_dead_code_programmatic_json

Serialize typed dead-code output into the stable JSON compatibility contract.

serialize_decision_surface_programmatic_json

Serialize typed decision-surface output into the stable JSON contract.

serialize_duplication_programmatic_json

Serialize typed duplication output into the JSON compatibility contract.

serialize_feature_flags_programmatic_json

Serialize typed feature-flag output into the JSON compatibility contract.

serialize_health_programmatic_json

Serialize typed health / complexity output into the JSON compatibility contract.

serialize_list_boundaries_programmatic_json

Serialize typed boundary-list output to the stable JSON contract.

serialize_project_info_programmatic_json

Serialize typed project-info output to the stable JSON contract.

serialize_similar_code_json_output

Serialize raw similar-code output with its root discriminator.

serialize_trace_clone_programmatic_json

Serialize typed clone-trace output into the JSON compatibility contract.

serialize_trace_dependency_programmatic_json

Serialize typed dependency-trace output into the JSON compatibility contract.

serialize_trace_error_programmatic_json

Serialize typed stack-trace resolution into the JSON compatibility contract.

serialize_trace_export_programmatic_json

Serialize typed export-trace output into the JSON compatibility contract.

serialize_trace_file_programmatic_json

Serialize typed file-trace output into the JSON compatibility contract.

serialize_trace_import_path_programmatic_json

Serialize typed import-path-trace output into the JSON compatibility contract.

shutdown_type_aware_sidecars

Permanently close semantic sidecar spawning and terminate active children.

terminate_active_type_aware_sidecars

Terminate every active type-aware sidecar started by this process.

trace_type_aware_symbol

Resolve exact checker-backed references for one exported symbol.

type_aware_status

Inspect the optional semantic companion without loading or analyzing a TypeScript project.

type_aware_symbol_impact

Compute exact-symbol consumers and a bounded targeted-test recommendation.

validate_complexity_options

Validate programmatic complexity / health inputs before invoking a concrete runner.