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
17/// Engine alias for [`fallow_types::trace::ClassMemberTrace`].
18pub type ClassMemberTrace = fallow_types::trace::ClassMemberTrace;
19/// Engine alias for [`fallow_types::trace::CloneTrace`].
20pub type CloneTrace = fallow_types::trace::CloneTrace;
21/// Engine alias for [`fallow_types::trace::DependencyTrace`].
22pub type DependencyTrace = fallow_types::trace::DependencyTrace;
23/// Engine alias for [`fallow_types::trace::ExportReference`].
24pub type ExportReference = fallow_types::trace::ExportReference;
25/// Engine alias for [`fallow_types::trace::ExportTrace`].
26pub type ExportTrace = fallow_types::trace::ExportTrace;
27/// Engine alias for [`fallow_types::trace::FileTrace`].
28pub type FileTrace = fallow_types::trace::FileTrace;
29/// Engine alias for [`fallow_types::trace::ImpactClosureGap`].
30pub type ImpactClosureGap = fallow_types::trace::ImpactClosureGap;
31/// Engine alias for [`fallow_types::trace::ImpactClosureTrace`].
32pub type ImpactClosureTrace = fallow_types::trace::ImpactClosureTrace;
33/// Engine alias for [`fallow_types::trace::PipelineTimings`].
34pub type PipelineTimings = fallow_types::trace::PipelineTimings;
35/// Engine alias for [`fallow_types::trace::ReExportChain`].
36pub type ReExportChain = fallow_types::trace::ReExportChain;
37pub use trace_impl::SemanticClassMethodResolutionError;
38/// Engine alias for [`fallow_types::trace::TracedCloneGroup`].
39pub type TracedCloneGroup = fallow_types::trace::TracedCloneGroup;
40/// Engine alias for [`fallow_types::trace::TracedExport`].
41pub type TracedExport = fallow_types::trace::TracedExport;
42/// Engine alias for [`fallow_types::trace::TracedReExport`].
43pub type TracedReExport = fallow_types::trace::TracedReExport;
44
45/// Trace why an export is considered used or unused.
46#[must_use]
47pub fn trace_export(
48    graph: &RetainedModuleGraph,
49    root: &Path,
50    file_path: &str,
51    export_name: &str,
52) -> Option<ExportTrace> {
53    trace_impl::trace_export(graph.as_graph(), root, file_path, export_name)
54}
55
56/// Reconcile checker-backed trace evidence with graph reachability while
57/// retaining non-crediting evidence for inspection.
58pub fn reconcile_semantic_trace_reachability(
59    graph: &RetainedModuleGraph,
60    root: &Path,
61    target_reachable: bool,
62    trace: &mut fallow_types::semantic::SemanticSymbolTrace,
63) {
64    trace_impl::reconcile_semantic_trace_reachability(
65        graph.as_graph(),
66        root,
67        target_reachable,
68        trace,
69    );
70}
71
72/// Resolve the source identity for an exact semantic export query.
73#[must_use]
74pub fn semantic_symbol_for_export(
75    graph: &RetainedModuleGraph,
76    root: &Path,
77    file_path: &str,
78    export_name: &str,
79) -> Option<fallow_types::semantic::SemanticSymbol> {
80    trace_impl::semantic_symbol_for_export(graph.as_graph(), root, file_path, export_name)
81}
82
83/// Resolve the source identity for an exact semantic class-member query.
84#[must_use]
85pub fn semantic_symbol_for_class_member(
86    graph: &RetainedModuleGraph,
87    root: &Path,
88    file_path: &str,
89    member_name: &str,
90) -> Option<fallow_types::semantic::SemanticSymbol> {
91    trace_impl::semantic_symbol_for_class_member(graph.as_graph(), root, file_path, member_name)
92}
93
94/// Resolve one exact exported class method for semantic impact analysis.
95pub fn semantic_symbol_for_exact_class_method(
96    graph: &RetainedModuleGraph,
97    root: &Path,
98    file_path: &str,
99    owner_name: &str,
100    member_name: &str,
101) -> Result<fallow_types::semantic::SemanticSymbol, SemanticClassMethodResolutionError> {
102    trace_impl::semantic_symbol_for_exact_class_method(
103        graph.as_graph(),
104        root,
105        file_path,
106        owner_name,
107        member_name,
108    )
109}
110
111/// Trace a class / enum / store member (the `--trace FILE:MEMBER` fallback when
112/// `MEMBER` is not a top-level export). See issue #1744.
113#[must_use]
114pub fn trace_class_member(
115    graph: &RetainedModuleGraph,
116    root: &Path,
117    file_path: &str,
118    member_name: &str,
119) -> Option<ClassMemberTrace> {
120    trace_impl::trace_class_member(graph.as_graph(), root, file_path, member_name)
121}
122
123/// Trace all graph edges for a file.
124#[must_use]
125pub fn trace_file(graph: &RetainedModuleGraph, root: &Path, file_path: &str) -> Option<FileTrace> {
126    trace_impl::trace_file(graph.as_graph(), root, file_path)
127}
128
129/// Trace where a dependency is used.
130#[must_use]
131#[expect(
132    clippy::implicit_hasher,
133    reason = "fallow standardizes on FxHashSet across the workspace"
134)]
135pub fn trace_dependency(
136    graph: &RetainedModuleGraph,
137    root: &Path,
138    package_name: &str,
139    script_used_packages: &FxHashSet<String>,
140) -> DependencyTrace {
141    trace_impl::trace_dependency(graph.as_graph(), root, package_name, script_used_packages)
142}
143
144/// Trace duplicate-code groups that contain a source location.
145#[must_use]
146pub fn trace_clone(
147    report: &DuplicationReport,
148    root: &Path,
149    file_path: &str,
150    line: usize,
151) -> CloneTrace {
152    trace_impl::trace_clone(report, root, file_path, line)
153}
154
155/// Trace a duplicate-code group by its stable content fingerprint.
156#[must_use]
157pub fn trace_clone_by_fingerprint(
158    report: &DuplicationReport,
159    root: &Path,
160    fingerprint: &str,
161) -> CloneTrace {
162    trace_impl::trace_clone_by_fingerprint(report, root, fingerprint)
163}
164
165/// Trace the impact closure for a file.
166#[must_use]
167pub fn trace_impact_closure(
168    graph: &RetainedModuleGraph,
169    root: &Path,
170    file_path: &str,
171) -> Option<ImpactClosureTrace> {
172    trace_impl::trace_impact_closure(graph.as_graph(), root, file_path)
173}
fallow_engine/trace.rs

fallow_engine/
trace.rs
