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/// Resolve the source identity for an exact semantic export query.
57#[must_use]
58pub fn semantic_symbol_for_export(
59    graph: &RetainedModuleGraph,
60    root: &Path,
61    file_path: &str,
62    export_name: &str,
63) -> Option<fallow_types::semantic::SemanticSymbol> {
64    trace_impl::semantic_symbol_for_export(graph.as_graph(), root, file_path, export_name)
65}
66
67/// Resolve the source identity for an exact semantic class-member query.
68#[must_use]
69pub fn semantic_symbol_for_class_member(
70    graph: &RetainedModuleGraph,
71    root: &Path,
72    file_path: &str,
73    member_name: &str,
74) -> Option<fallow_types::semantic::SemanticSymbol> {
75    trace_impl::semantic_symbol_for_class_member(graph.as_graph(), root, file_path, member_name)
76}
77
78/// Resolve one exact exported class method for semantic impact analysis.
79pub fn semantic_symbol_for_exact_class_method(
80    graph: &RetainedModuleGraph,
81    root: &Path,
82    file_path: &str,
83    owner_name: &str,
84    member_name: &str,
85) -> Result<fallow_types::semantic::SemanticSymbol, SemanticClassMethodResolutionError> {
86    trace_impl::semantic_symbol_for_exact_class_method(
87        graph.as_graph(),
88        root,
89        file_path,
90        owner_name,
91        member_name,
92    )
93}
94
95/// Trace a class / enum / store member (the `--trace FILE:MEMBER` fallback when
96/// `MEMBER` is not a top-level export). See issue #1744.
97#[must_use]
98pub fn trace_class_member(
99    graph: &RetainedModuleGraph,
100    root: &Path,
101    file_path: &str,
102    member_name: &str,
103) -> Option<ClassMemberTrace> {
104    trace_impl::trace_class_member(graph.as_graph(), root, file_path, member_name)
105}
106
107/// Trace all graph edges for a file.
108#[must_use]
109pub fn trace_file(graph: &RetainedModuleGraph, root: &Path, file_path: &str) -> Option<FileTrace> {
110    trace_impl::trace_file(graph.as_graph(), root, file_path)
111}
112
113/// Trace where a dependency is used.
114#[must_use]
115#[expect(
116    clippy::implicit_hasher,
117    reason = "fallow standardizes on FxHashSet across the workspace"
118)]
119pub fn trace_dependency(
120    graph: &RetainedModuleGraph,
121    root: &Path,
122    package_name: &str,
123    script_used_packages: &FxHashSet<String>,
124) -> DependencyTrace {
125    trace_impl::trace_dependency(graph.as_graph(), root, package_name, script_used_packages)
126}
127
128/// Trace duplicate-code groups that contain a source location.
129#[must_use]
130pub fn trace_clone(
131    report: &DuplicationReport,
132    root: &Path,
133    file_path: &str,
134    line: usize,
135) -> CloneTrace {
136    trace_impl::trace_clone(report, root, file_path, line)
137}
138
139/// Trace a duplicate-code group by its stable content fingerprint.
140#[must_use]
141pub fn trace_clone_by_fingerprint(
142    report: &DuplicationReport,
143    root: &Path,
144    fingerprint: &str,
145) -> CloneTrace {
146    trace_impl::trace_clone_by_fingerprint(report, root, fingerprint)
147}
148
149/// Trace the impact closure for a file.
150#[must_use]
151pub fn trace_impact_closure(
152    graph: &RetainedModuleGraph,
153    root: &Path,
154    file_path: &str,
155) -> Option<ImpactClosureTrace> {
156    trace_impl::trace_impact_closure(graph.as_graph(), root, file_path)
157}
fallow_engine/trace.rs

fallow_engine/
trace.rs
