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_change_scope;

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::health_signal_header_part;

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.

ChangeScope

Engine-owned change scope of one run: a global changed-file set or the per-workspace Git baselines of workspaces.changedSince. The resolved change scope of one run.

ChangeScopeRequest

Engine-owned change scope of one run: a global changed-file set or the per-workspace Git baselines of workspaces.changedSince. The change-scope inputs of one run.

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.

PackageBaselineStatus

Shared JSON and editor notification row for an applied package Git ref. One applied baseline for an exact, project-relative workspace root.

PackageChangeScope

Engine-owned per-workspace Git baseline state used by analysis surfaces. Resolved package baselines for one analysis project.

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.

ChangeScopeOwner

Engine-owned change scope of one run: a global changed-file set or the per-workspace Git baselines of workspaces.changedSince. Who owns the change scope of a run.

ComplexitySort

Sort criteria for complexity findings.

DuplicationMode

Programmatic duplication mode selection.

OwnershipEmailMode

Privacy mode for ownership-aware hotspot output.

PackageBaselineError

Engine-owned per-workspace Git baseline state used by analysis surfaces. Failure to resolve an authored workspace baseline.

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.

first_package_baselines

Engine-owned change scope of one run: a global changed-file set or the per-workspace Git baselines of workspaces.changedSince. The package_baselines rows of a combined report: the rows of the first section that applied the map. The sections of one run resolve the same map, so a section without rows either did not run or used a global scope.

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.

package_baseline_statuses

Engine-owned change scope of one run: a global changed-file set or the per-workspace Git baselines of workspaces.changedSince. Project-relative package baseline rows, sorted by workspace root.

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.