dart-decimate 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/Cargo.lock +572 -0
  2. package/Cargo.toml +41 -0
  3. package/LICENSE +21 -0
  4. package/README.md +617 -0
  5. package/assets/dart-decimate-banner.png +0 -0
  6. package/npm/bin/dart-decimate-mcp.js +48 -0
  7. package/npm/bin/dart-decimate.js +48 -0
  8. package/npm/scripts/postinstall.js +46 -0
  9. package/npm/scripts/test-npx-local.js +54 -0
  10. package/npm/scripts/test-npx-mcp-local.js +56 -0
  11. package/package.json +45 -0
  12. package/src/baseline.rs +643 -0
  13. package/src/bin/dart-decimate-mcp.rs +11 -0
  14. package/src/boundaries/tests.rs +60 -0
  15. package/src/boundaries.rs +317 -0
  16. package/src/changed_scope.rs +117 -0
  17. package/src/ci_template.rs +399 -0
  18. package/src/cli/analyze.rs +462 -0
  19. package/src/cli/analyzer_options.rs +82 -0
  20. package/src/cli/audit_run.rs +327 -0
  21. package/src/cli/boundary_args.rs +44 -0
  22. package/src/cli/ci_template_run.rs +196 -0
  23. package/src/cli/command_name.rs +20 -0
  24. package/src/cli/common_args.rs +167 -0
  25. package/src/cli/config_run.rs +78 -0
  26. package/src/cli/coverage_run.rs +393 -0
  27. package/src/cli/decision_surface_run.rs +99 -0
  28. package/src/cli/default_command.rs +69 -0
  29. package/src/cli/dupes_args.rs +150 -0
  30. package/src/cli/entry_points.rs +121 -0
  31. package/src/cli/error.rs +149 -0
  32. package/src/cli/error_output.rs +68 -0
  33. package/src/cli/explain_run.rs +72 -0
  34. package/src/cli/fix_run.rs +162 -0
  35. package/src/cli/flags_args.rs +23 -0
  36. package/src/cli/health_args.rs +200 -0
  37. package/src/cli/hooks_run.rs +191 -0
  38. package/src/cli/impact_run.rs +95 -0
  39. package/src/cli/init_run.rs +49 -0
  40. package/src/cli/inspect_args.rs +20 -0
  41. package/src/cli/inspect_run.rs +66 -0
  42. package/src/cli/issue_filter_args.rs +240 -0
  43. package/src/cli/list_run.rs +311 -0
  44. package/src/cli/mode_args.rs +72 -0
  45. package/src/cli/output_format.rs +62 -0
  46. package/src/cli/regression_args.rs +156 -0
  47. package/src/cli/request_args.rs +175 -0
  48. package/src/cli/schema_commands.rs +72 -0
  49. package/src/cli/scope_args.rs +174 -0
  50. package/src/cli/security_args.rs +175 -0
  51. package/src/cli/security_gate_run.rs +66 -0
  52. package/src/cli/security_summary_run.rs +43 -0
  53. package/src/cli/summary_args.rs +12 -0
  54. package/src/cli/tests.rs +516 -0
  55. package/src/cli/trace_args.rs +67 -0
  56. package/src/cli/trace_run.rs +131 -0
  57. package/src/cli/trace_tests.rs +235 -0
  58. package/src/cli/unsupported_run.rs +116 -0
  59. package/src/cli/watch_run.rs +153 -0
  60. package/src/cli.rs +603 -0
  61. package/src/config/boundary_config.rs +235 -0
  62. package/src/config/cache.rs +25 -0
  63. package/src/config/dependencies.rs +114 -0
  64. package/src/config/health.rs +237 -0
  65. package/src/config/jsonc.rs +66 -0
  66. package/src/config/policy.rs +91 -0
  67. package/src/config/rule_aliases.rs +487 -0
  68. package/src/config/rules.rs +339 -0
  69. package/src/config.rs +635 -0
  70. package/src/coverage.rs +469 -0
  71. package/src/dart_parser.rs +673 -0
  72. package/src/decision_surface.rs +405 -0
  73. package/src/dependencies/analyze.rs +218 -0
  74. package/src/dependencies/codegen.rs +118 -0
  75. package/src/dependencies/discovery.rs +60 -0
  76. package/src/dependencies/overrides.rs +76 -0
  77. package/src/dependencies/private_src_imports.rs +32 -0
  78. package/src/dependencies/pubspec_document.rs +86 -0
  79. package/src/dependencies/pubspec_entry.rs +96 -0
  80. package/src/dependencies/tests.rs +544 -0
  81. package/src/dependencies/usage.rs +33 -0
  82. package/src/dependencies.rs +553 -0
  83. package/src/dependency_scripts.rs +91 -0
  84. package/src/dupes/lex.rs +236 -0
  85. package/src/dupes/tests.rs +119 -0
  86. package/src/dupes.rs +625 -0
  87. package/src/explain.rs +692 -0
  88. package/src/extract/directives.rs +252 -0
  89. package/src/extract/error_tests.rs +25 -0
  90. package/src/extract/members.rs +210 -0
  91. package/src/extract/primary_constructors.rs +421 -0
  92. package/src/extract/references.rs +151 -0
  93. package/src/extract/routes.rs +691 -0
  94. package/src/extract/signatures.rs +266 -0
  95. package/src/extract/string_tests.rs +18 -0
  96. package/src/extract/strings.rs +107 -0
  97. package/src/extract/tests.rs +697 -0
  98. package/src/extract.rs +680 -0
  99. package/src/feature_flags/tests.rs +76 -0
  100. package/src/feature_flags.rs +453 -0
  101. package/src/finding_identity.rs +60 -0
  102. package/src/fix.rs +551 -0
  103. package/src/generated.rs +53 -0
  104. package/src/graph/augment_tests.rs +212 -0
  105. package/src/graph/conditionals.rs +74 -0
  106. package/src/graph/package_config_tests.rs +100 -0
  107. package/src/graph/parts.rs +248 -0
  108. package/src/graph/pubspec_tests.rs +119 -0
  109. package/src/graph/tests.rs +837 -0
  110. package/src/graph/uri_tests.rs +102 -0
  111. package/src/graph.rs +644 -0
  112. package/src/health/coverage.rs +309 -0
  113. package/src/health/ownership.rs +175 -0
  114. package/src/health/runtime_coverage.rs +616 -0
  115. package/src/health/runtime_intelligence.rs +511 -0
  116. package/src/health/scores.rs +296 -0
  117. package/src/health/tests.rs +240 -0
  118. package/src/health/threshold_types.rs +163 -0
  119. package/src/health/thresholds.rs +229 -0
  120. package/src/health/types.rs +636 -0
  121. package/src/health.rs +597 -0
  122. package/src/hooks/agent_settings.rs +175 -0
  123. package/src/hooks/templates.rs +51 -0
  124. package/src/hooks.rs +569 -0
  125. package/src/impact.rs +287 -0
  126. package/src/init.rs +237 -0
  127. package/src/inspect.rs +142 -0
  128. package/src/intelligence/tests.rs +232 -0
  129. package/src/intelligence.rs +305 -0
  130. package/src/lib.rs +198 -0
  131. package/src/main.rs +5 -0
  132. package/src/manifest/mcp.rs +565 -0
  133. package/src/manifest.rs +552 -0
  134. package/src/mcp/cli_args/value_args.rs +175 -0
  135. package/src/mcp/cli_args.rs +658 -0
  136. package/src/mcp/cli_args_tests.rs +522 -0
  137. package/src/mcp/code_execute.rs +671 -0
  138. package/src/mcp/tools.rs +660 -0
  139. package/src/mcp.rs +325 -0
  140. package/src/output/audit_risk.rs +135 -0
  141. package/src/output/dependency_findings.rs +327 -0
  142. package/src/output/duplication_findings.rs +114 -0
  143. package/src/output/feature_flag_findings.rs +122 -0
  144. package/src/output/format.rs +31 -0
  145. package/src/output/graph_findings.rs +461 -0
  146. package/src/output/health_findings.rs +612 -0
  147. package/src/output/human.rs +27 -0
  148. package/src/output/next_steps.rs +92 -0
  149. package/src/output/route_findings.rs +76 -0
  150. package/src/output/runtime_coverage.rs +515 -0
  151. package/src/output/scope.rs +183 -0
  152. package/src/output/security_findings.rs +390 -0
  153. package/src/output/security_sarif.rs +150 -0
  154. package/src/output/suppressions.rs +323 -0
  155. package/src/output/symbol_findings.rs +257 -0
  156. package/src/output/tests.rs +114 -0
  157. package/src/output/types.rs +604 -0
  158. package/src/output/widget_findings.rs +213 -0
  159. package/src/output.rs +682 -0
  160. package/src/package_map.rs +495 -0
  161. package/src/policy/packs.rs +232 -0
  162. package/src/policy/tests.rs +134 -0
  163. package/src/policy.rs +640 -0
  164. package/src/project_list.rs +376 -0
  165. package/src/report_schema/inventory.rs +418 -0
  166. package/src/report_schema.rs +488 -0
  167. package/src/routes.rs +354 -0
  168. package/src/scan/tests.rs +250 -0
  169. package/src/scan.rs +275 -0
  170. package/src/security/detect.rs +639 -0
  171. package/src/security/tests.rs +178 -0
  172. package/src/security.rs +373 -0
  173. package/src/security_gate.rs +555 -0
  174. package/src/symbols/path_filters.rs +27 -0
  175. package/src/symbols/private_type_leaks.rs +125 -0
  176. package/src/symbols/riverpod.rs +113 -0
  177. package/src/symbols/tests.rs +692 -0
  178. package/src/symbols.rs +693 -0
  179. package/src/trace/tests.rs +225 -0
  180. package/src/trace.rs +690 -0
  181. package/src/unsupported.rs +47 -0
  182. package/src/widgets/lifecycle.rs +484 -0
  183. package/src/widgets/params.rs +236 -0
  184. package/src/widgets/tests.rs +430 -0
  185. package/src/widgets/top_level.rs +110 -0
  186. package/src/widgets/unrendered.rs +374 -0
  187. package/src/widgets.rs +590 -0
  188. package/src/workspace_scope.rs +358 -0
package/src/trace.rs ADDED
@@ -0,0 +1,690 @@
1
+ use std::collections::BTreeSet;
2
+ use std::fmt::Write as _;
3
+ use std::path::{Path, PathBuf};
4
+
5
+ use serde::{Deserialize, Serialize};
6
+
7
+ use crate::dependencies::{
8
+ DeclaredPackageDependency, LocalPubPackage, declared_package_dependencies, local_pub_packages,
9
+ };
10
+ use crate::dependency_scripts::package_used_in_tooling;
11
+ use crate::graph::normalize_against;
12
+ use crate::output::TRACE_SCHEMA_VERSION;
13
+ use crate::{
14
+ DartCombinatorKind, DeadCodeReport, DeclarationKind, DependencyHygieneError, DependencyKind,
15
+ DependencySection, ScannedProject, TopLevelDeclaration,
16
+ };
17
+
18
+ /// File trace JSON envelope.
19
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
20
+ pub struct FileTraceReport {
21
+ /// Schema identifier.
22
+ pub schema_version: String,
23
+ /// Typed JSON envelope discriminator.
24
+ pub kind: String,
25
+ /// Tool name.
26
+ pub tool: String,
27
+ /// Trace command name.
28
+ pub command: String,
29
+ /// Traced file path.
30
+ pub path: String,
31
+ /// Whether the file exists in the module graph.
32
+ pub found: bool,
33
+ /// Whether the file is reachable from entry points.
34
+ pub reachable: bool,
35
+ /// Whether the file is an entry point.
36
+ pub entry_point: bool,
37
+ /// Top-level declarations in the file.
38
+ pub declarations: Vec<TraceDeclaration>,
39
+ /// Outgoing non-export dependencies from the file.
40
+ pub imports_from: Vec<TraceDependency>,
41
+ /// Incoming dependencies to the file.
42
+ pub imported_by: Vec<TraceDependency>,
43
+ /// Outgoing export dependencies from the file.
44
+ pub re_exports: Vec<TraceDependency>,
45
+ /// Unresolved dependencies declared by the file.
46
+ pub unresolved: Vec<TraceDependency>,
47
+ /// Short trace interpretation.
48
+ pub reason: String,
49
+ }
50
+
51
+ /// Symbol trace JSON envelope.
52
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
53
+ pub struct SymbolTraceReport {
54
+ /// Schema identifier.
55
+ pub schema_version: String,
56
+ /// Typed JSON envelope discriminator.
57
+ pub kind: String,
58
+ /// Tool name.
59
+ pub tool: String,
60
+ /// Trace command name.
61
+ pub command: String,
62
+ /// File that should declare the symbol.
63
+ pub path: String,
64
+ /// Symbol being traced.
65
+ pub symbol: String,
66
+ /// Whether the declaration exists in the requested file.
67
+ pub found: bool,
68
+ /// Whether the declaration file is reachable from entry points.
69
+ pub reachable_file: bool,
70
+ /// Whether the declaration file is an entry point.
71
+ pub entry_point: bool,
72
+ /// Matched top-level declaration, if any.
73
+ pub declaration: Option<TraceDeclaration>,
74
+ /// Syntactic references to the symbol.
75
+ pub direct_references: Vec<TraceReference>,
76
+ /// Export chains that expose this file through barrels.
77
+ pub re_export_chains: Vec<Vec<String>>,
78
+ /// Short trace interpretation.
79
+ pub reason: String,
80
+ }
81
+
82
+ /// Dependency trace JSON envelope.
83
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
84
+ #[allow(clippy::struct_excessive_bools)]
85
+ pub struct DependencyTraceReport {
86
+ /// Schema identifier.
87
+ pub schema_version: String,
88
+ /// Typed JSON envelope discriminator.
89
+ pub kind: String,
90
+ /// Tool name.
91
+ pub tool: String,
92
+ /// Trace command name.
93
+ pub command: String,
94
+ /// Dependency package being traced.
95
+ pub dependency: String,
96
+ /// Whether the dependency was found as either a declaration or Dart usage.
97
+ pub found: bool,
98
+ /// Whether the dependency is declared in at least one local pubspec.
99
+ pub declared: bool,
100
+ /// Local pubspec declarations for this dependency.
101
+ pub declared_in: Vec<TracePubspecDependency>,
102
+ /// Dart import/export directives that reference the package.
103
+ pub importing_files: Vec<TraceDependencyDirective>,
104
+ /// Dart has no type-only import directive; kept for Fallow-compatible shape.
105
+ pub type_only_importers: Vec<TraceDependencyDirective>,
106
+ /// Number of Dart import/export directives referencing the package.
107
+ pub total_import_count: usize,
108
+ /// Whether non-Dart scripts reference the package. Not scanned yet.
109
+ pub used_in_scripts: bool,
110
+ /// Whether Dart source references the package in import/export directives.
111
+ pub is_used: bool,
112
+ /// Short trace interpretation.
113
+ pub reason: String,
114
+ }
115
+
116
+ /// Declaration included in trace output.
117
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
118
+ pub struct TraceDeclaration {
119
+ /// Declaration kind.
120
+ pub kind: DeclarationKind,
121
+ /// Declared name.
122
+ pub name: String,
123
+ /// 1-based line.
124
+ pub line: usize,
125
+ /// 0-based byte column.
126
+ pub column: usize,
127
+ }
128
+
129
+ /// Dependency edge included in trace output.
130
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
131
+ pub struct TraceDependency {
132
+ /// Source file.
133
+ pub from: String,
134
+ /// Target file or unresolved attempted target.
135
+ pub to: String,
136
+ /// Raw import/export/part/augment URI.
137
+ pub specifier: String,
138
+ /// `import`, `export`, or `part`.
139
+ pub kind: String,
140
+ /// 1-based line.
141
+ pub line: usize,
142
+ /// 0-based byte column.
143
+ pub column: usize,
144
+ }
145
+
146
+ /// Symbol reference included in trace output.
147
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
148
+ pub struct TraceReference {
149
+ /// Referencing file.
150
+ pub path: String,
151
+ /// 1-based line.
152
+ pub line: usize,
153
+ /// 0-based byte column.
154
+ pub column: usize,
155
+ /// Whether the referencing file is reachable from entry points.
156
+ pub reachable: bool,
157
+ }
158
+
159
+ /// Pubspec declaration included in dependency trace output.
160
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
161
+ pub struct TracePubspecDependency {
162
+ /// Package declaring the dependency.
163
+ pub package: String,
164
+ /// Pubspec path, root-relative where possible.
165
+ pub pubspec_path: String,
166
+ /// Dependency package name.
167
+ pub dependency: String,
168
+ /// Pubspec dependency section.
169
+ pub section: DependencySection,
170
+ /// 1-based line.
171
+ pub line: usize,
172
+ /// 0-based byte column.
173
+ pub column: usize,
174
+ }
175
+
176
+ /// Import/export directive included in dependency trace output.
177
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
178
+ pub struct TraceDependencyDirective {
179
+ /// Package containing the directive, when a local pubspec owns the file.
180
+ pub package: Option<String>,
181
+ /// File containing the directive.
182
+ pub path: String,
183
+ /// `import`, `export`, `part`, or `augment`.
184
+ pub kind: String,
185
+ /// Raw package URI.
186
+ pub specifier: String,
187
+ /// Optional import prefix after `as`.
188
+ pub prefix: Option<String>,
189
+ /// Whether the import uses `deferred as`.
190
+ pub deferred: bool,
191
+ /// 1-based line.
192
+ pub line: usize,
193
+ /// 0-based byte column.
194
+ pub column: usize,
195
+ }
196
+
197
+ /// Build a read-only trace for one Dart file.
198
+ #[must_use]
199
+ pub fn trace_file(
200
+ project: &ScannedProject,
201
+ dead_code: &DeadCodeReport,
202
+ path: impl AsRef<Path>,
203
+ ) -> FileTraceReport {
204
+ let path = normalize_against(&project.root, path.as_ref());
205
+ let found = project.graph.node_index(&path).is_some();
206
+ let reachable = dead_code.reachable_files.iter().any(|file| file == &path);
207
+ let entry_point = dead_code.entry_points.iter().any(|file| file == &path);
208
+ let dependencies = project.graph.dependencies();
209
+
210
+ let declarations = project
211
+ .files
212
+ .iter()
213
+ .find(|file| normalize_against(&project.root, &file.path) == path)
214
+ .map_or_else(Vec::new, |file| declarations(&file.declarations));
215
+ let imports_from = dependencies
216
+ .iter()
217
+ .filter(|dependency| {
218
+ dependency.from_path == path && dependency.kind != DependencyKind::Export
219
+ })
220
+ .map(|dependency| trace_resolved_dependency(&project.root, dependency))
221
+ .collect();
222
+ let re_exports = dependencies
223
+ .iter()
224
+ .filter(|dependency| {
225
+ dependency.from_path == path && dependency.kind == DependencyKind::Export
226
+ })
227
+ .map(|dependency| trace_resolved_dependency(&project.root, dependency))
228
+ .collect();
229
+ let imported_by = dependencies
230
+ .iter()
231
+ .filter(|dependency| dependency.to_path == path)
232
+ .map(|dependency| trace_resolved_dependency(&project.root, dependency))
233
+ .collect();
234
+ let unresolved = project
235
+ .graph
236
+ .unresolved()
237
+ .iter()
238
+ .filter(|dependency| dependency.from_path == path)
239
+ .map(|dependency| TraceDependency {
240
+ from: display_path(&project.root, &dependency.from_path),
241
+ to: display_path(&project.root, &dependency.attempted_path),
242
+ specifier: dependency.specifier.clone(),
243
+ kind: dependency_kind(dependency.kind),
244
+ line: dependency.location.line,
245
+ column: dependency.location.column,
246
+ })
247
+ .collect();
248
+
249
+ FileTraceReport {
250
+ schema_version: TRACE_SCHEMA_VERSION.to_owned(),
251
+ kind: "trace-file".to_owned(),
252
+ tool: "dart-decimate".to_owned(),
253
+ command: "trace-file".to_owned(),
254
+ path: display_path(&project.root, &path),
255
+ found,
256
+ reachable,
257
+ entry_point,
258
+ declarations,
259
+ imports_from,
260
+ imported_by,
261
+ re_exports,
262
+ unresolved,
263
+ reason: file_reason(found, reachable, entry_point),
264
+ }
265
+ }
266
+
267
+ /// Build a read-only trace for one top-level symbol in one Dart file.
268
+ #[must_use]
269
+ pub fn trace_symbol(
270
+ project: &ScannedProject,
271
+ dead_code: &DeadCodeReport,
272
+ path: impl AsRef<Path>,
273
+ symbol: &str,
274
+ ) -> SymbolTraceReport {
275
+ let path = normalize_against(&project.root, path.as_ref());
276
+ let reachable_files = dead_code
277
+ .reachable_files
278
+ .iter()
279
+ .cloned()
280
+ .collect::<BTreeSet<_>>();
281
+ let declaration = find_declaration(project, &path, symbol);
282
+ let found = declaration.is_some();
283
+ let reachable_file = reachable_files.contains(&path);
284
+ let entry_point = dead_code.entry_points.iter().any(|file| file == &path);
285
+ let direct_references = direct_references(project, &reachable_files, symbol);
286
+ let re_export_chains = re_export_chains(project, &path, symbol);
287
+
288
+ SymbolTraceReport {
289
+ schema_version: TRACE_SCHEMA_VERSION.to_owned(),
290
+ kind: "trace-symbol".to_owned(),
291
+ tool: "dart-decimate".to_owned(),
292
+ command: "trace-symbol".to_owned(),
293
+ path: display_path(&project.root, &path),
294
+ symbol: symbol.to_owned(),
295
+ found,
296
+ reachable_file,
297
+ entry_point,
298
+ declaration,
299
+ reason: symbol_reason(found, reachable_file, entry_point, &direct_references),
300
+ direct_references,
301
+ re_export_chains,
302
+ }
303
+ }
304
+
305
+ /// Build a read-only trace for one pub dependency.
306
+ ///
307
+ /// # Errors
308
+ ///
309
+ /// Returns [`DependencyHygieneError`] if local pubspec discovery or parsing fails.
310
+ pub fn trace_dependency(
311
+ project: &ScannedProject,
312
+ dependency: &str,
313
+ ) -> Result<DependencyTraceReport, DependencyHygieneError> {
314
+ let packages = local_pub_packages(&project.root)?;
315
+ let mut importing_files = dependency_directives(project, &packages, dependency);
316
+ importing_files.sort_by(|left, right| {
317
+ (
318
+ &left.path,
319
+ left.line,
320
+ left.column,
321
+ &left.kind,
322
+ &left.specifier,
323
+ )
324
+ .cmp(&(
325
+ &right.path,
326
+ right.line,
327
+ right.column,
328
+ &right.kind,
329
+ &right.specifier,
330
+ ))
331
+ });
332
+
333
+ let declared_in = declared_package_dependencies(&project.root, dependency)?
334
+ .iter()
335
+ .map(|declaration| trace_pubspec_dependency(&project.root, declaration))
336
+ .collect::<Vec<_>>();
337
+ let declared = !declared_in.is_empty();
338
+ let total_import_count = importing_files.len();
339
+ let used_in_scripts = packages
340
+ .iter()
341
+ .any(|package| package_used_in_tooling(&package.root, dependency));
342
+ let is_used = total_import_count > 0 || used_in_scripts;
343
+
344
+ Ok(DependencyTraceReport {
345
+ schema_version: TRACE_SCHEMA_VERSION.to_owned(),
346
+ kind: "trace-dependency".to_owned(),
347
+ tool: "dart-decimate".to_owned(),
348
+ command: "trace-dependency".to_owned(),
349
+ dependency: dependency.to_owned(),
350
+ found: declared || is_used,
351
+ declared,
352
+ declared_in,
353
+ importing_files,
354
+ type_only_importers: Vec::new(),
355
+ total_import_count,
356
+ used_in_scripts,
357
+ is_used,
358
+ reason: dependency_reason(declared, is_used),
359
+ })
360
+ }
361
+
362
+ /// Render a concise human file trace.
363
+ #[must_use]
364
+ pub fn render_file_trace(report: &FileTraceReport) -> String {
365
+ let mut rendered = String::new();
366
+ let _ = writeln!(
367
+ rendered,
368
+ "trace-file {}: found={} reachable={} entry_point={}",
369
+ report.path, report.found, report.reachable, report.entry_point
370
+ );
371
+ let _ = writeln!(rendered, "{}", report.reason);
372
+ rendered
373
+ }
374
+
375
+ /// Render a concise human symbol trace.
376
+ #[must_use]
377
+ pub fn render_symbol_trace(report: &SymbolTraceReport) -> String {
378
+ let mut rendered = String::new();
379
+ let _ = writeln!(
380
+ rendered,
381
+ "trace-symbol {}:{}: found={} reachable_file={} references={}",
382
+ report.path,
383
+ report.symbol,
384
+ report.found,
385
+ report.reachable_file,
386
+ report.direct_references.len()
387
+ );
388
+ let _ = writeln!(rendered, "{}", report.reason);
389
+ rendered
390
+ }
391
+
392
+ /// Render a concise human dependency trace.
393
+ #[must_use]
394
+ pub fn render_dependency_trace(report: &DependencyTraceReport) -> String {
395
+ let mut rendered = String::new();
396
+ let _ = writeln!(
397
+ rendered,
398
+ "trace-dependency {}: found={} declared={} used={} imports={}",
399
+ report.dependency, report.found, report.declared, report.is_used, report.total_import_count
400
+ );
401
+ let _ = writeln!(rendered, "{}", report.reason);
402
+ rendered
403
+ }
404
+
405
+ fn declarations(declarations: &[TopLevelDeclaration]) -> Vec<TraceDeclaration> {
406
+ declarations
407
+ .iter()
408
+ .map(|declaration| TraceDeclaration {
409
+ kind: declaration.kind,
410
+ name: declaration.name.clone(),
411
+ line: declaration.location.line,
412
+ column: declaration.location.column,
413
+ })
414
+ .collect()
415
+ }
416
+
417
+ fn trace_resolved_dependency(
418
+ root: &Path,
419
+ dependency: &crate::ResolvedDependency,
420
+ ) -> TraceDependency {
421
+ TraceDependency {
422
+ from: display_path(root, &dependency.from_path),
423
+ to: display_path(root, &dependency.to_path),
424
+ specifier: dependency.specifier.clone(),
425
+ kind: dependency_kind(dependency.kind),
426
+ line: dependency.location.line,
427
+ column: dependency.location.column,
428
+ }
429
+ }
430
+
431
+ fn trace_pubspec_dependency(
432
+ root: &Path,
433
+ dependency: &DeclaredPackageDependency,
434
+ ) -> TracePubspecDependency {
435
+ TracePubspecDependency {
436
+ package: dependency.package.clone(),
437
+ pubspec_path: display_path(root, &dependency.pubspec_path),
438
+ dependency: dependency.dependency.clone(),
439
+ section: dependency.section,
440
+ line: dependency.location.line,
441
+ column: dependency.location.column,
442
+ }
443
+ }
444
+
445
+ fn dependency_directives(
446
+ project: &ScannedProject,
447
+ packages: &[LocalPubPackage],
448
+ dependency: &str,
449
+ ) -> Vec<TraceDependencyDirective> {
450
+ project
451
+ .files
452
+ .iter()
453
+ .flat_map(|file| {
454
+ let normalized = normalize_against(&project.root, &file.path);
455
+ let package = owning_package(packages, &normalized).map(|package| package.name.clone());
456
+ let path = display_path(&project.root, &normalized);
457
+ file.imports
458
+ .iter()
459
+ .filter(move |import| package_name(&import.uri) == Some(dependency))
460
+ .map({
461
+ let path = path.clone();
462
+ let package = package.clone();
463
+ move |import| TraceDependencyDirective {
464
+ package: package.clone(),
465
+ path: path.clone(),
466
+ kind: "import".to_owned(),
467
+ specifier: import.uri.clone(),
468
+ prefix: import.prefix.clone(),
469
+ deferred: import.deferred,
470
+ line: import.location.line,
471
+ column: import.location.column,
472
+ }
473
+ })
474
+ .chain(
475
+ file.exports
476
+ .iter()
477
+ .filter(move |export| package_name(&export.uri) == Some(dependency))
478
+ .map(move |export| TraceDependencyDirective {
479
+ package: package.clone(),
480
+ path: path.clone(),
481
+ kind: "export".to_owned(),
482
+ specifier: export.uri.clone(),
483
+ prefix: None,
484
+ deferred: false,
485
+ line: export.location.line,
486
+ column: export.location.column,
487
+ }),
488
+ )
489
+ })
490
+ .collect()
491
+ }
492
+
493
+ fn find_declaration(
494
+ project: &ScannedProject,
495
+ path: &Path,
496
+ symbol: &str,
497
+ ) -> Option<TraceDeclaration> {
498
+ project.files.iter().find_map(|file| {
499
+ if normalize_against(&project.root, &file.path) != path {
500
+ return None;
501
+ }
502
+ file.declarations
503
+ .iter()
504
+ .find(|declaration| declaration.name == symbol)
505
+ .map(|declaration| TraceDeclaration {
506
+ kind: declaration.kind,
507
+ name: declaration.name.clone(),
508
+ line: declaration.location.line,
509
+ column: declaration.location.column,
510
+ })
511
+ })
512
+ }
513
+
514
+ fn direct_references(
515
+ project: &ScannedProject,
516
+ reachable_files: &BTreeSet<PathBuf>,
517
+ symbol: &str,
518
+ ) -> Vec<TraceReference> {
519
+ let mut references = project
520
+ .files
521
+ .iter()
522
+ .flat_map(|file| {
523
+ let path = normalize_against(&project.root, &file.path);
524
+ file.references
525
+ .iter()
526
+ .filter(move |reference| reference.name == symbol)
527
+ .map(move |reference| TraceReference {
528
+ path: display_path(&project.root, &path),
529
+ line: reference.location.line,
530
+ column: reference.location.column,
531
+ reachable: reachable_files.contains(&path),
532
+ })
533
+ })
534
+ .collect::<Vec<_>>();
535
+
536
+ references.sort_by(|left, right| {
537
+ (&left.path, left.line, left.column).cmp(&(&right.path, right.line, right.column))
538
+ });
539
+ references
540
+ }
541
+
542
+ fn re_export_chains(project: &ScannedProject, target: &Path, symbol: &str) -> Vec<Vec<String>> {
543
+ let export_edges = project
544
+ .graph
545
+ .dependencies()
546
+ .into_iter()
547
+ .filter(|dependency| dependency.kind == DependencyKind::Export)
548
+ .collect::<Vec<_>>();
549
+ let mut chains = Vec::new();
550
+ collect_re_export_chains(
551
+ &project.root,
552
+ &export_edges,
553
+ target,
554
+ symbol,
555
+ &[target.to_path_buf()],
556
+ &mut chains,
557
+ );
558
+ chains.sort();
559
+ chains
560
+ }
561
+
562
+ fn collect_re_export_chains(
563
+ root: &Path,
564
+ export_edges: &[crate::ResolvedDependency],
565
+ current: &Path,
566
+ symbol: &str,
567
+ chain: &[PathBuf],
568
+ chains: &mut Vec<Vec<String>>,
569
+ ) {
570
+ if chain.len() > 8 {
571
+ return;
572
+ }
573
+
574
+ for edge in export_edges.iter().filter(|edge| {
575
+ edge.to_path == current && is_visible_through_export(symbol, &edge.visibility.combinators)
576
+ }) {
577
+ if chain.contains(&edge.from_path) {
578
+ continue;
579
+ }
580
+ let mut next = chain.to_owned();
581
+ next.push(edge.from_path.clone());
582
+ chains.push(
583
+ next.iter()
584
+ .rev()
585
+ .map(|path| display_path(root, path))
586
+ .collect(),
587
+ );
588
+ collect_re_export_chains(root, export_edges, &edge.from_path, symbol, &next, chains);
589
+ }
590
+ }
591
+
592
+ fn is_visible_through_export(name: &str, combinators: &[crate::DartCombinator]) -> bool {
593
+ let mut visible = true;
594
+ for combinator in combinators {
595
+ match combinator.kind {
596
+ DartCombinatorKind::Show => {
597
+ visible = combinator.names.iter().any(|shown| shown == name);
598
+ }
599
+ DartCombinatorKind::Hide => {
600
+ if combinator.names.iter().any(|hidden| hidden == name) {
601
+ visible = false;
602
+ }
603
+ }
604
+ }
605
+ }
606
+ visible
607
+ }
608
+
609
+ fn file_reason(found: bool, reachable: bool, entry_point: bool) -> String {
610
+ match (found, reachable, entry_point) {
611
+ (false, _, _) => "file is not in the module graph",
612
+ (true, _, true) => "file is configured as an entry point",
613
+ (true, true, false) => "file is reachable from an entry point",
614
+ (true, false, false) => "file is unreachable from configured entry points",
615
+ }
616
+ .to_owned()
617
+ }
618
+
619
+ fn symbol_reason(
620
+ found: bool,
621
+ reachable_file: bool,
622
+ entry_point: bool,
623
+ direct_references: &[TraceReference],
624
+ ) -> String {
625
+ if !found {
626
+ return "symbol declaration was not found in the requested file".to_owned();
627
+ }
628
+ if entry_point {
629
+ return "symbol is declared in an entry-point file".to_owned();
630
+ }
631
+ if !reachable_file {
632
+ return "symbol's declaring file is unreachable".to_owned();
633
+ }
634
+ if direct_references
635
+ .iter()
636
+ .any(|reference| reference.reachable)
637
+ {
638
+ return "symbol has reachable direct references".to_owned();
639
+ }
640
+ "symbol has no reachable direct references".to_owned()
641
+ }
642
+
643
+ fn dependency_reason(declared: bool, is_used: bool) -> String {
644
+ match (declared, is_used) {
645
+ (true, true) => "dependency is declared and referenced by Dart import/export directives",
646
+ (true, false) => "dependency is declared but no Dart import/export directives reference it",
647
+ (false, true) => {
648
+ "dependency is referenced by Dart source but not declared in a local pubspec"
649
+ }
650
+ (false, false) => "dependency is neither declared nor referenced by Dart source",
651
+ }
652
+ .to_owned()
653
+ }
654
+
655
+ fn package_name(specifier: &str) -> Option<&str> {
656
+ specifier
657
+ .strip_prefix("package:")
658
+ .and_then(|rest| rest.split_once('/'))
659
+ .map(|(package, _)| package)
660
+ }
661
+
662
+ fn owning_package<'package>(
663
+ packages: &'package [LocalPubPackage],
664
+ path: &Path,
665
+ ) -> Option<&'package LocalPubPackage> {
666
+ packages
667
+ .iter()
668
+ .filter(|package| path.starts_with(&package.root))
669
+ .max_by_key(|package| package.root.components().count())
670
+ }
671
+
672
+ fn dependency_kind(kind: DependencyKind) -> String {
673
+ match kind {
674
+ DependencyKind::Import => "import",
675
+ DependencyKind::Export => "export",
676
+ DependencyKind::Part => "part",
677
+ DependencyKind::Augment => "augment",
678
+ }
679
+ .to_owned()
680
+ }
681
+
682
+ fn display_path(root: &Path, path: &Path) -> String {
683
+ path.strip_prefix(root)
684
+ .unwrap_or(path)
685
+ .to_string_lossy()
686
+ .replace('\\', "/")
687
+ }
688
+
689
+ #[cfg(test)]
690
+ mod tests;