fallow_engine/
trace.rs

1//! Read-only trace helpers exposed through the engine boundary.
2
3use std::path::Path;
4
5use rustc_hash::FxHashSet;
6
7use crate::duplicates::DuplicationReport;
8use crate::module_graph::RetainedModuleGraph;
9
10#[expect(
11    unused_imports,
12    reason = "engine owns a copied trace implementation whose internal pub uses serve its tests"
13)]
14#[path = "trace_impl.rs"]
15mod trace_impl;
16
17pub type ClassMemberTrace = fallow_types::trace::ClassMemberTrace;
18pub type CloneTrace = fallow_types::trace::CloneTrace;
19pub type DependencyTrace = fallow_types::trace::DependencyTrace;
20pub type ExportReference = fallow_types::trace::ExportReference;
21pub type ExportTrace = fallow_types::trace::ExportTrace;
22pub type FileTrace = fallow_types::trace::FileTrace;
23pub type ImpactClosureGap = fallow_types::trace::ImpactClosureGap;
24pub type ImpactClosureTrace = fallow_types::trace::ImpactClosureTrace;
25pub type PipelineTimings = fallow_types::trace::PipelineTimings;
26pub type ReExportChain = fallow_types::trace::ReExportChain;
27pub use trace_impl::SemanticClassMethodResolutionError;
28pub type TracedCloneGroup = fallow_types::trace::TracedCloneGroup;
29pub type TracedExport = fallow_types::trace::TracedExport;
30pub type TracedReExport = fallow_types::trace::TracedReExport;
31
32/// Trace why an export is considered used or unused.
33#[must_use]
34pub fn trace_export(
35    graph: &RetainedModuleGraph,
36    root: &Path,
37    file_path: &str,
38    export_name: &str,
39) -> Option<ExportTrace> {
40    trace_impl::trace_export(graph.as_graph(), root, file_path, export_name)
41}
42
43/// Resolve the source identity for an exact semantic export query.
44#[must_use]
45pub fn semantic_symbol_for_export(
46    graph: &RetainedModuleGraph,
47    root: &Path,
48    file_path: &str,
49    export_name: &str,
50) -> Option<fallow_types::semantic::SemanticSymbol> {
51    trace_impl::semantic_symbol_for_export(graph.as_graph(), root, file_path, export_name)
52}
53
54/// Resolve the source identity for an exact semantic class-member query.
55#[must_use]
56pub fn semantic_symbol_for_class_member(
57    graph: &RetainedModuleGraph,
58    root: &Path,
59    file_path: &str,
60    member_name: &str,
61) -> Option<fallow_types::semantic::SemanticSymbol> {
62    trace_impl::semantic_symbol_for_class_member(graph.as_graph(), root, file_path, member_name)
63}
64
65/// Resolve one exact exported class method for semantic impact analysis.
66pub fn semantic_symbol_for_exact_class_method(
67    graph: &RetainedModuleGraph,
68    root: &Path,
69    file_path: &str,
70    owner_name: &str,
71    member_name: &str,
72) -> Result<fallow_types::semantic::SemanticSymbol, SemanticClassMethodResolutionError> {
73    trace_impl::semantic_symbol_for_exact_class_method(
74        graph.as_graph(),
75        root,
76        file_path,
77        owner_name,
78        member_name,
79    )
80}
81
82/// Trace a class / enum / store member (the `--trace FILE:MEMBER` fallback when
83/// `MEMBER` is not a top-level export). See issue #1744.
84#[must_use]
85pub fn trace_class_member(
86    graph: &RetainedModuleGraph,
87    root: &Path,
88    file_path: &str,
89    member_name: &str,
90) -> Option<ClassMemberTrace> {
91    trace_impl::trace_class_member(graph.as_graph(), root, file_path, member_name)
92}
93
94/// Trace all graph edges for a file.
95#[must_use]
96pub fn trace_file(graph: &RetainedModuleGraph, root: &Path, file_path: &str) -> Option<FileTrace> {
97    trace_impl::trace_file(graph.as_graph(), root, file_path)
98}
99
100/// Trace where a dependency is used.
101#[must_use]
102#[expect(
103    clippy::implicit_hasher,
104    reason = "fallow standardizes on FxHashSet across the workspace"
105)]
106pub fn trace_dependency(
107    graph: &RetainedModuleGraph,
108    root: &Path,
109    package_name: &str,
110    script_used_packages: &FxHashSet<String>,
111) -> DependencyTrace {
112    trace_impl::trace_dependency(graph.as_graph(), root, package_name, script_used_packages)
113}
114
115/// Trace duplicate-code groups that contain a source location.
116#[must_use]
117pub fn trace_clone(
118    report: &DuplicationReport,
119    root: &Path,
120    file_path: &str,
121    line: usize,
122) -> CloneTrace {
123    trace_impl::trace_clone(report, root, file_path, line)
124}
125
126/// Trace a duplicate-code group by its stable content fingerprint.
127#[must_use]
128pub fn trace_clone_by_fingerprint(
129    report: &DuplicationReport,
130    root: &Path,
131    fingerprint: &str,
132) -> CloneTrace {
133    trace_impl::trace_clone_by_fingerprint(report, root, fingerprint)
134}
135
136/// Trace the impact closure for a file.
137#[must_use]
138pub fn trace_impact_closure(
139    graph: &RetainedModuleGraph,
140    root: &Path,
141    file_path: &str,
142) -> Option<ImpactClosureTrace> {
143    trace_impl::trace_impact_closure(graph.as_graph(), root, file_path)
144}
fallow_engine/trace.rs

fallow_engine/
trace.rs
