use fallow_engine::session::AnalysisSession;
use fallow_types::duplicates::DuplicationReport;
use rustc_hash::FxHashSet;
use crate::{
ProgrammaticAnalysisContext, ProgrammaticError, TraceCloneOptions,
TraceCloneProgrammaticOutput, TraceCloneTarget, TraceDependencyOptions,
TraceDependencyProgrammaticOutput, TraceErrorOptions, TraceErrorProgrammaticOutput,
TraceExportOptions, TraceExportProgrammaticOutput, TraceExportTargetOutput, TraceFileOptions,
TraceFileProgrammaticOutput, TraceImportPathOptions, TraceImportPathProgrammaticOutput,
};
use super::{ProgrammaticResult, duplication, resolve_programmatic_analysis_context};
struct TraceArtifacts {
graph: fallow_engine::module_graph::RetainedModuleGraph,
script_used_packages: FxHashSet<String>,
}
/// Trace why an export is considered used or unused.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options, config load
/// failures, graph construction failures, or missing trace targets.
pub fn run_trace_export(
options: &TraceExportOptions,
) -> ProgrammaticResult<TraceExportProgrammaticOutput> {
validate_non_empty("file", &options.file)?;
validate_non_empty("export_name", &options.export_name)?;
let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
resolved.install(|| {
let session = load_trace_session(&resolved)?;
let artifacts = trace_artifacts(&session)?;
// Resolve a top-level export first; on a miss fall back to a class /
// enum / store member trace so the MCP tool and Code Mode match the
// CLI's `--trace FILE:MEMBER` behavior instead of a hard not-found
// (issue #1744).
let output = if let Some(export) = fallow_engine::trace::trace_export(
&artifacts.graph,
session.root(),
&options.file,
&options.export_name,
) {
TraceExportTargetOutput::Export(export)
} else if let Some(member) = fallow_engine::trace::trace_class_member(
&artifacts.graph,
session.root(),
&options.file,
&options.export_name,
) {
TraceExportTargetOutput::Member(member)
} else {
return Err(ProgrammaticError::new(
format!(
"export or member '{}' not found in '{}'",
options.export_name, options.file
),
2,
)
.with_code("FALLOW_TRACE_TARGET_NOT_FOUND")
.with_help(
"The name is neither a top-level export nor a class / enum / store member of this \
file. Run trace_file on the file to list its exports, or project_info for the \
project symbol set; confirm the file path is project-relative.",
)
.with_context("trace_export"));
};
Ok(TraceExportProgrammaticOutput { output })
})
}
/// Trace all graph edges for a file.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options, config load
/// failures, graph construction failures, or missing trace targets.
pub fn run_trace_file(
options: &TraceFileOptions,
) -> ProgrammaticResult<TraceFileProgrammaticOutput> {
validate_non_empty("file", &options.file)?;
let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
resolved.install(|| {
let session = load_trace_session(&resolved)?;
let artifacts = trace_artifacts(&session)?;
let output =
fallow_engine::trace::trace_file(&artifacts.graph, session.root(), &options.file)
.ok_or_else(|| {
ProgrammaticError::new(
format!("file '{}' not found in module graph", options.file),
2,
)
.with_code("FALLOW_TRACE_TARGET_NOT_FOUND")
.with_help(
"The file is not in the analyzed module graph. Run project_info to list \
discovered files; the path must be project-relative and not excluded by \
ignore patterns or outside the analyzed roots.",
)
.with_context("trace_file")
})?;
Ok(TraceFileProgrammaticOutput { output })
})
}
/// Trace the shortest import path between two modules.
///
/// An unreachable pair is a RESULT, not an error: the output reports
/// `reachable: false` with zero hops. A missing or ambiguous endpoint is an error.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options, config load
/// failures, graph construction failures, or a missing or ambiguous endpoint.
pub fn run_trace_import_path(
options: &TraceImportPathOptions,
) -> ProgrammaticResult<TraceImportPathProgrammaticOutput> {
validate_non_empty("from", &options.from)?;
validate_non_empty("to", &options.to)?;
let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
resolved.install(|| {
let session = load_trace_session(&resolved)?;
let artifacts = trace_artifacts(&session)?;
let output = fallow_engine::trace::trace_import_path(
&artifacts.graph,
session.root(),
&options.from,
&options.to,
)
.map_err(|endpoint| {
let label = endpoint.label();
let value = match endpoint {
fallow_engine::trace::ImportPathEndpoint::From
| fallow_engine::trace::ImportPathEndpoint::AmbiguousFrom => &options.from,
fallow_engine::trace::ImportPathEndpoint::To
| fallow_engine::trace::ImportPathEndpoint::AmbiguousTo => &options.to,
};
if endpoint.is_ambiguous() {
return ProgrammaticError::new(format!("'{value}' ({label}) matches multiple modules"), 2)
.with_code("FALLOW_TRACE_TARGET_AMBIGUOUS")
.with_help("Use the full project-relative path; run project_info to list discovered files.")
.with_context("trace_import_path");
}
ProgrammaticError::new(format!("'{value}' ({label}) not found in module graph"), 2)
.with_code("FALLOW_TRACE_TARGET_NOT_FOUND")
.with_help(
"The module is not in the analyzed module graph. Run project_info to list \
discovered files; both paths must be project-relative and not excluded by \
ignore patterns or outside the analyzed roots.",
)
.with_context("trace_import_path")
})?;
Ok(TraceImportPathProgrammaticOutput { output })
})
}
/// Resolve a runtime stack trace's frames against the project graph.
///
/// A trace in which nothing resolves is a RESULT, not an error: the output
/// reports every frame with the origin and resolution that explain why. Only
/// an empty trace argument, a config load failure, or a failed analysis is an
/// error.
///
/// # Errors
///
/// Returns a structured programmatic error for an empty or oversized trace,
/// config load failures, or graph construction failures.
pub fn run_trace_error(
options: &TraceErrorOptions,
) -> ProgrammaticResult<TraceErrorProgrammaticOutput> {
if options.trace.trim().is_empty() {
// Typed like the oversized-trace refusal below rather than through
// `validate_non_empty`: both are the same tool refusing the same
// argument, so both carry a `code`, a `help` and a `context`.
return Err(ProgrammaticError::new("trace must not be empty", 2)
.with_code("FALLOW_INVALID_TRACE_OPTIONS")
.with_help(
"Paste the stack trace text into `trace`, as your runtime printed it. \
trace_error resolves frames against the project graph, so it has nothing \
to resolve without them.",
)
.with_context("trace_error"));
}
if options.trace.len() as u64 > fallow_engine::trace_error::MAX_STACK_TRACE_BYTES {
let limit = fallow_engine::trace_error::MAX_STACK_TRACE_BYTES;
return Err(ProgrammaticError::new(
format!("stack trace exceeds the {limit}-byte limit"),
2,
)
.with_code("FALLOW_INVALID_TRACE_OPTIONS")
.with_help(
"A stack trace is a handful of kilobytes. Pass the trace itself rather than a \
redirected log file, and cut it to the frames that matter.",
)
.with_context("trace_error"));
}
let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
resolved.install(|| {
let session = load_trace_session(&resolved)?;
let output = fallow_engine::trace_error::trace_error_with_session(
&session,
&options.trace,
options.source.clone(),
)
.map_err(|err| {
ProgrammaticError::new(format!("stack-trace resolution failed: {err}"), 2)
.with_code("FALLOW_ANALYSIS_FAILED")
.with_context("trace_error")
})?;
Ok(TraceErrorProgrammaticOutput { output })
})
}
/// Trace where a dependency is used.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options, config load, or
/// graph construction failures.
pub fn run_trace_dependency(
options: &TraceDependencyOptions,
) -> ProgrammaticResult<TraceDependencyProgrammaticOutput> {
validate_non_empty("package_name", &options.package_name)?;
let resolved = resolve_programmatic_analysis_context(&options.analysis)?;
resolved.install(|| {
let session = load_trace_session(&resolved)?;
let artifacts = trace_artifacts(&session)?;
let output = fallow_engine::trace::trace_dependency(
&artifacts.graph,
session.root(),
&options.package_name,
&artifacts.script_used_packages,
);
Ok(TraceDependencyProgrammaticOutput { output })
})
}
/// Trace duplicate-code groups by location or stable fingerprint.
///
/// # Errors
///
/// Returns a structured programmatic error for invalid options, config load
/// failures, duplicate detection failures, or missing trace targets.
pub fn run_trace_clone(
options: &TraceCloneOptions,
) -> ProgrammaticResult<TraceCloneProgrammaticOutput> {
validate_trace_clone_target(&options.target)?;
let resolved = resolve_programmatic_analysis_context(&options.duplication.analysis)?;
resolved.install(|| {
resolved.ensure_not_cancelled("config load and file discovery")?;
let session = duplication::load_duplication_session(&options.duplication, &resolved)?;
resolved.ensure_not_cancelled("duplication detection")?;
let dupes_config =
duplication::build_dupes_config(&options.duplication, &session.config().duplicates);
let cache_dir = (!resolved.no_cache).then_some(session.config().cache_dir.as_path());
let report = session
.find_duplicates_with_defaults(&dupes_config, cache_dir)
.report;
// Duplication detection is infallible, so the cancelled run has to be
// reported before the report is traced as a complete one.
resolved.ensure_not_cancelled("the clone trace")?;
let (trace, not_found) = match &options.target {
TraceCloneTarget::Location { file, line } => (
fallow_engine::trace::trace_clone(&report, session.root(), file, *line),
format!("no clone found at {file}:{line}"),
),
TraceCloneTarget::Fingerprint(fingerprint) => (
fallow_engine::trace::trace_clone_by_fingerprint(
&report,
session.root(),
fingerprint,
),
format!("no clone group with fingerprint {fingerprint}"),
),
};
if trace.matched_instance.is_none() {
return Err(ProgrammaticError::new(not_found, 2)
.with_code("FALLOW_TRACE_TARGET_NOT_FOUND")
.with_help(
"No clone matched. Run find_dupes to list clone groups and their fingerprints; \
a location must fall inside a reported clone instance, and a fingerprint must \
be a find_dupes clone_groups[].fingerprint (a dup:<id> value).",
)
.with_context("trace_clone"));
}
Ok(TraceCloneProgrammaticOutput { output: trace })
})
}
/// Exercise the retained-graph trace family and compact JSON boundary without
/// repeating project discovery, parsing, or graph construction.
///
/// # Errors
///
/// Returns a structured error when a fixture target is missing or compact JSON
/// serialization fails.
#[doc(hidden)]
#[allow(
clippy::implicit_hasher,
reason = "the engine trace boundary intentionally accepts the workspace-standard FxHashSet"
)]
pub fn benchmark_trace_graph_family_compact_json(
graph: &fallow_engine::module_graph::RetainedModuleGraph,
root: &std::path::Path,
script_used_packages: &FxHashSet<String>,
) -> ProgrammaticResult<(usize, usize, usize, usize, usize)> {
let export =
fallow_engine::trace::trace_export(graph, root, "src/000-shared.ts", "sharedValue")
.ok_or_else(|| benchmark_trace_target_missing("src/000-shared.ts:sharedValue"))?;
let export_reference_count = export.direct_references.len();
let export_json =
crate::serialize_trace_export_programmatic_json(TraceExportProgrammaticOutput {
output: TraceExportTargetOutput::Export(export),
})?;
let file = fallow_engine::trace::trace_file(graph, root, "src/000-shared.ts")
.ok_or_else(|| benchmark_trace_target_missing("src/000-shared.ts"))?;
let file_export_count = file.exports.len();
let file_imported_by_count = file.imported_by.len();
let file_json = crate::serialize_trace_file_programmatic_json(TraceFileProgrammaticOutput {
output: file,
})?;
let dependency =
fallow_engine::trace::trace_dependency(graph, root, "trace-package", script_used_packages);
let dependency_import_count = dependency.import_count;
let dependency_json =
crate::serialize_trace_dependency_programmatic_json(TraceDependencyProgrammaticOutput {
output: dependency,
})?;
let rendered_bytes = compact_json_len(&[export_json, file_json, dependency_json])?;
Ok((
export_reference_count,
file_export_count,
file_imported_by_count,
dependency_import_count,
rendered_bytes,
))
}
/// Stable facts returned by the clone trace benchmark boundary.
#[doc(hidden)]
#[derive(Debug, PartialEq, Eq)]
pub struct TraceCloneBenchmarkResult {
/// Location identity returned by the location trace.
pub location_file: std::path::PathBuf,
/// Location line returned by the location trace.
pub location_line: usize,
/// Group fingerprint returned by the location trace.
pub location_fingerprint: String,
/// Group fingerprint returned by the fingerprint trace.
pub fingerprint_fingerprint: String,
/// Groups returned by the location trace.
pub location_group_count: usize,
/// Groups returned by the fingerprint trace.
pub fingerprint_group_count: usize,
/// Instances returned by the location trace.
pub location_instance_count: usize,
/// Instances returned by the fingerprint trace.
pub fingerprint_instance_count: usize,
/// Total compact JSON bytes for both trace responses.
pub rendered_bytes: usize,
}
/// Exercise both supported clone trace identities from one retained report.
///
/// # Errors
///
/// Returns a structured error when either identity misses or compact JSON
/// serialization fails.
#[doc(hidden)]
pub fn benchmark_trace_clone_compact_json(
report: &DuplicationReport,
root: &std::path::Path,
file: &str,
line: usize,
fingerprint: &str,
) -> ProgrammaticResult<TraceCloneBenchmarkResult> {
let location_trace = fallow_engine::trace::trace_clone(report, root, file, line);
let matched_location = location_trace
.matched_instance
.as_ref()
.ok_or_else(|| benchmark_trace_target_missing(&format!("{file}:{line}")))?;
let location_file = matched_location.file.clone();
let location_line = matched_location.start_line;
let location_fingerprint = location_trace
.clone_groups
.first()
.map(|group| group.fingerprint.clone())
.ok_or_else(|| benchmark_trace_target_missing(&format!("{file}:{line}")))?;
let location_group_count = location_trace.clone_groups.len();
let location_instance_count = location_trace
.clone_groups
.iter()
.map(|group| group.instances.len())
.sum();
let location_json =
crate::serialize_trace_clone_programmatic_json(TraceCloneProgrammaticOutput {
output: location_trace,
})?;
let fingerprint_trace =
fallow_engine::trace::trace_clone_by_fingerprint(report, root, fingerprint);
if fingerprint_trace.matched_instance.is_none() {
return Err(benchmark_trace_target_missing(fingerprint));
}
let fingerprint_fingerprint = fingerprint_trace
.clone_groups
.first()
.map(|group| group.fingerprint.clone())
.ok_or_else(|| benchmark_trace_target_missing(fingerprint))?;
let fingerprint_group_count = fingerprint_trace.clone_groups.len();
let fingerprint_instance_count = fingerprint_trace
.clone_groups
.iter()
.map(|group| group.instances.len())
.sum();
let fingerprint_json =
crate::serialize_trace_clone_programmatic_json(TraceCloneProgrammaticOutput {
output: fingerprint_trace,
})?;
let rendered_bytes = compact_json_len(&[location_json, fingerprint_json])?;
Ok(TraceCloneBenchmarkResult {
location_file,
location_line,
location_fingerprint,
fingerprint_fingerprint,
location_group_count,
fingerprint_group_count,
location_instance_count,
fingerprint_instance_count,
rendered_bytes,
})
}
fn compact_json_len(values: &[serde_json::Value]) -> ProgrammaticResult<usize> {
serde_json::to_vec(values)
.map(|json| json.len())
.map_err(|err| {
ProgrammaticError::new(
format!("failed to serialize benchmark trace JSON: {err}"),
2,
)
.with_code("FALLOW_SERIALIZE_BENCHMARK_TRACE")
.with_context("benchmark_trace")
})
}
fn benchmark_trace_target_missing(target: &str) -> ProgrammaticError {
ProgrammaticError::new(format!("benchmark trace target not found: {target}"), 2)
.with_code("FALLOW_BENCHMARK_TRACE_TARGET_NOT_FOUND")
.with_context("benchmark_trace")
}
fn validate_non_empty(field: &str, value: &str) -> ProgrammaticResult<()> {
if value.trim().is_empty() {
return Err(
ProgrammaticError::new(format!("{field} must not be empty"), 2)
.with_code("FALLOW_INVALID_TRACE_OPTIONS")
.with_context(field.to_string()),
);
}
Ok(())
}
fn validate_trace_clone_target(target: &TraceCloneTarget) -> ProgrammaticResult<()> {
match target {
TraceCloneTarget::Location { file, line } => {
validate_non_empty("file", file)?;
if *line == 0 {
return Err(ProgrammaticError::new("line must be greater than 0", 2)
.with_code("FALLOW_INVALID_TRACE_OPTIONS")
.with_context("trace_clone.line"));
}
}
TraceCloneTarget::Fingerprint(fingerprint) => {
validate_non_empty("fingerprint", fingerprint)?;
}
}
Ok(())
}
fn load_trace_session(
resolved: &ProgrammaticAnalysisContext,
) -> ProgrammaticResult<AnalysisSession> {
super::dead_code::load_dead_code_session(
&super::dead_code::default_dead_code_options_for_context(resolved),
resolved,
)
}
fn trace_artifacts(session: &AnalysisSession) -> ProgrammaticResult<TraceArtifacts> {
let artifacts = session
.analyze_dead_code_with_session_artifacts(false, true, None)
.map_err(|err| {
super::dead_code::map_engine_error(
&err,
"trace analysis failed",
"FALLOW_TRACE_FAILED",
"trace",
)
})?;
let graph = artifacts.analysis.graph.ok_or_else(|| {
ProgrammaticError::new("trace requires a retained module graph", 2)
.with_code("FALLOW_TRACE_GRAPH_UNAVAILABLE")
.with_context("trace.graph")
})?;
Ok(TraceArtifacts {
graph,
script_used_packages: artifacts.analysis.script_used_packages,
})
}
#[cfg(test)]
mod benchmark_tests {
use std::fmt::Write as _;
use std::fs;
use fallow_engine::duplicates::CloneFingerprintSet;
use super::*;
const FIXTURE_SIZE: usize = 4;
fn write_file(root: &std::path::Path, path: &str, source: impl AsRef<str>) {
let path = root.join(path);
fs::create_dir_all(path.parent().expect("fixture file has parent"))
.expect("fixture directory is created");
fs::write(path, source.as_ref()).expect("fixture file is written");
}
#[test]
fn graph_family_benchmark_boundary_uses_only_retained_artifacts() {
let temp_dir = tempfile::TempDir::new().expect("temporary project is created");
let root = temp_dir.path().to_path_buf();
write_file(
&root,
"package.json",
r#"{"name":"trace-test","type":"module","main":"src/index.ts"}"#,
);
write_file(
&root,
"src/000-shared.ts",
"export const sharedValue = 42;\n",
);
let mut index_source = String::new();
for index in 0..FIXTURE_SIZE {
write_file(
&root,
&format!("src/consumer{index}.ts"),
format!(
"import {{ sharedValue }} from './000-shared';\nimport {{ traceHelper }} from 'trace-package';\nexport const value{index} = traceHelper(sharedValue + {index});\n"
),
);
writeln!(
index_source,
"import {{ value{index} }} from './consumer{index}';\nconsole.log(value{index});"
)
.expect("index source is built");
}
write_file(&root, "src/index.ts", index_source);
let session = AnalysisSession::load(&root, None).expect("trace session loads");
let target = session
.files()
.iter()
.find(|file| file.path.ends_with("src/000-shared.ts"))
.expect("trace target is discovered");
assert_eq!(
target.id.0, 0,
"the retained trace target must precede every non-matching importer"
);
let trace_root = session.root().to_path_buf();
let artifacts = session
.analyze_dead_code_with_artifacts(false, true)
.expect("trace graph analysis succeeds");
drop(session);
temp_dir.close().expect("temporary project is removed");
let result = benchmark_trace_graph_family_compact_json(
artifacts.graph.as_ref().expect("trace graph is retained"),
&trace_root,
&artifacts.script_used_packages,
)
.expect("retained trace graph serializes without project IO");
assert_eq!(result.0, FIXTURE_SIZE);
assert_eq!(result.1, 1);
assert_eq!(result.2, FIXTURE_SIZE);
assert_eq!(result.3, FIXTURE_SIZE);
assert!(result.4 > 0);
}
#[test]
fn clone_benchmark_boundary_uses_only_the_retained_report() {
let temp_dir = tempfile::TempDir::new().expect("temporary project is created");
let root = temp_dir.path().to_path_buf();
write_file(
&root,
"package.json",
r#"{"name":"trace-clone-test","type":"module"}"#,
);
for index in 0..FIXTURE_SIZE {
write_file(
&root,
&format!("src/clone{index}.ts"),
format!(
"export function normalizeRecords(records: Array<{{ active: boolean; value: number }}>) {{\n const active = records.filter((record) => record.active);\n const values = active.map((record) => record.value);\n const total = values.reduce((sum, value) => sum + value, 0);\n const average = values.length === 0 ? 0 : total / values.length;\n const maximum = values.reduce((current, value) => Math.max(current, value), 0);\n return {{ total, average, maximum, count: values.length }};\n}}\n\nexport const cloneId = {index};\n"
),
);
}
let session = AnalysisSession::load(&root, None).expect("clone session loads");
let trace_root = session.root().to_path_buf();
let mut config = session.config().duplicates.clone();
config.min_tokens = 35;
config.min_lines = 5;
config.min_occurrences = FIXTURE_SIZE;
let report = session.find_duplicates_with_defaults(&config, None).report;
let group = report
.clone_groups
.iter()
.max_by_key(|group| group.instances.len())
.expect("clone group exists");
let target = group.instances.last().expect("clone instance exists");
let target_file = target
.file
.strip_prefix(&trace_root)
.expect("clone path is project-relative")
.to_string_lossy()
.replace('\\', "/");
let target_line = target.start_line;
let expected_fingerprint =
CloneFingerprintSet::from_groups(&report.clone_groups).fingerprint_for_group(group);
drop(session);
temp_dir.close().expect("temporary project is removed");
let result = benchmark_trace_clone_compact_json(
&report,
&trace_root,
&target_file,
target_line,
&expected_fingerprint,
)
.expect("retained clone report serializes without project IO");
assert_eq!(result.location_file, std::path::PathBuf::from(&target_file));
assert_eq!(result.location_line, target_line);
assert_eq!(result.location_fingerprint, expected_fingerprint);
assert_eq!(result.fingerprint_fingerprint, expected_fingerprint);
assert_eq!(result.location_group_count, 1);
assert_eq!(result.fingerprint_group_count, 1);
assert_eq!(result.location_instance_count, FIXTURE_SIZE);
assert_eq!(result.fingerprint_instance_count, FIXTURE_SIZE);
assert!(result.rendered_bytes > 0);
}
}