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
@@ -0,0 +1,604 @@
1
+ use serde::{Deserialize, Serialize};
2
+
3
+ use super::{
4
+ JsonAttackSurfaceEntry, JsonCloneGroup, JsonComplexityFinding, JsonFeatureFlag,
5
+ JsonFileHealthScore, JsonHealthHotspot, JsonRefactoringTarget, JsonRuntimeCoverage,
6
+ JsonSecurityCandidate, JsonThresholdOverride,
7
+ };
8
+
9
+ /// Command that produced a report.
10
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11
+ #[serde(rename_all = "kebab-case")]
12
+ pub enum ReportCommand {
13
+ /// Combined project check.
14
+ Check,
15
+ /// Changed-code project audit.
16
+ Audit,
17
+ /// Dead-code reachability command.
18
+ DeadCode,
19
+ /// Circular dependency command.
20
+ Cycles,
21
+ /// File trace command.
22
+ TraceFile,
23
+ /// Symbol trace command.
24
+ TraceSymbol,
25
+ /// Pub dependency trace command.
26
+ TraceDependency,
27
+ /// Code duplication command.
28
+ Dupes,
29
+ /// Code health command.
30
+ Health,
31
+ /// Clone trace command.
32
+ TraceClone,
33
+ /// Targeted evidence bundle command.
34
+ Inspect,
35
+ /// Feature flag inventory command.
36
+ Flags,
37
+ /// Security candidate command.
38
+ Security,
39
+ }
40
+
41
+ impl ReportCommand {
42
+ /// CLI command name.
43
+ #[must_use]
44
+ pub const fn as_str(self) -> &'static str {
45
+ match self {
46
+ Self::Check => "check",
47
+ Self::Audit => "audit",
48
+ Self::DeadCode => "dead-code",
49
+ Self::Cycles => "cycles",
50
+ Self::TraceFile => "trace-file",
51
+ Self::TraceSymbol => "trace-symbol",
52
+ Self::TraceDependency => "trace-dependency",
53
+ Self::Dupes => "dupes",
54
+ Self::Health => "health",
55
+ Self::TraceClone => "trace-clone",
56
+ Self::Inspect => "inspect",
57
+ Self::Flags => "flags",
58
+ Self::Security => "security",
59
+ }
60
+ }
61
+
62
+ /// Typed JSON envelope discriminator.
63
+ #[must_use]
64
+ pub const fn kind(self) -> &'static str {
65
+ match self {
66
+ Self::Check => "combined",
67
+ Self::Audit => "audit",
68
+ Self::DeadCode => "dead-code",
69
+ Self::Cycles => "cycles",
70
+ Self::Dupes => "dupes",
71
+ Self::Health => "health",
72
+ Self::Flags => "flags",
73
+ Self::Security => "security",
74
+ Self::TraceFile
75
+ | Self::TraceSymbol
76
+ | Self::TraceDependency
77
+ | Self::TraceClone
78
+ | Self::Inspect => self.as_str(),
79
+ }
80
+ }
81
+ }
82
+
83
+ /// Pass/fail verdict for CI and agents.
84
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
85
+ #[serde(rename_all = "kebab-case")]
86
+ pub enum Verdict {
87
+ /// No findings were produced.
88
+ Pass,
89
+ /// One or more findings were produced.
90
+ Fail,
91
+ }
92
+
93
+ /// Audit review risk band.
94
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
95
+ #[serde(rename_all = "kebab-case")]
96
+ pub enum AuditRiskLevel {
97
+ /// No visible audit risk.
98
+ Pass,
99
+ /// Visible findings need review but were not introduced as errors.
100
+ Warn,
101
+ /// The change introduced at least one error-severity finding.
102
+ Fail,
103
+ }
104
+
105
+ /// Introduced/pre-existing audit finding split.
106
+ #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
107
+ pub struct AuditAttribution {
108
+ /// Findings touching files changed since the audit base.
109
+ pub introduced: AuditAttributionCounts,
110
+ /// Findings surfaced only through related unchanged files.
111
+ pub pre_existing: AuditAttributionCounts,
112
+ }
113
+
114
+ /// Audit attribution counters.
115
+ #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
116
+ pub struct AuditAttributionCounts {
117
+ /// Findings in this attribution bucket.
118
+ pub findings: usize,
119
+ /// Error-severity findings.
120
+ pub error_findings: usize,
121
+ /// Warning-severity findings.
122
+ pub warning_findings: usize,
123
+ /// Findings marked safe to delete from graph evidence alone.
124
+ pub safe_to_delete: usize,
125
+ /// Distinct files referenced by these findings.
126
+ pub files: usize,
127
+ }
128
+
129
+ /// JSON report emitted by `--format json`.
130
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
131
+ pub struct JsonReport {
132
+ /// Schema identifier.
133
+ pub schema_version: String,
134
+ /// Typed JSON envelope discriminator.
135
+ pub kind: String,
136
+ /// Tool name.
137
+ pub tool: String,
138
+ /// Command that produced this report.
139
+ pub command: ReportCommand,
140
+ /// CI and agent verdict.
141
+ pub verdict: Verdict,
142
+ /// Numeric rollup.
143
+ pub summary: ReportSummary,
144
+ /// Machine-actionable findings.
145
+ pub findings: Vec<Finding>,
146
+ /// Duplicate-code clone groups, populated by `check` and `dupes`.
147
+ pub clone_groups: Vec<JsonCloneGroup>,
148
+ /// Complexity findings, populated by `check` and `health`.
149
+ pub complexity: Vec<JsonComplexityFinding>,
150
+ /// File health scores, populated by `health --file-scores`.
151
+ pub file_scores: Vec<JsonFileHealthScore>,
152
+ /// Health hotspots, populated by `health --hotspots`.
153
+ pub hotspots: Vec<JsonHealthHotspot>,
154
+ /// Refactoring targets, populated by `health --targets`.
155
+ pub refactoring_targets: Vec<JsonRefactoringTarget>,
156
+ /// Health threshold override states, populated when configured.
157
+ pub threshold_overrides: Vec<JsonThresholdOverride>,
158
+ /// Feature flag inventory, populated by `flags`.
159
+ pub feature_flags: Vec<JsonFeatureFlag>,
160
+ /// Security review candidates, populated by `security`.
161
+ pub security_candidates: Vec<JsonSecurityCandidate>,
162
+ /// Attack-surface inventory, populated by `security --surface`.
163
+ pub attack_surface: Vec<JsonAttackSurfaceEntry>,
164
+ /// Runtime coverage intelligence, populated by `--runtime-coverage`.
165
+ #[serde(skip_serializing_if = "Option::is_none")]
166
+ pub runtime_coverage: Option<JsonRuntimeCoverage>,
167
+ /// Read-only follow-up commands agents should run before acting.
168
+ pub next_steps: Vec<NextStep>,
169
+ }
170
+
171
+ /// Report summary.
172
+ #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
173
+ pub struct ReportSummary {
174
+ /// Dart files parsed.
175
+ pub files: usize,
176
+ /// Resolved graph edges.
177
+ pub edges: usize,
178
+ /// Local dependencies that did not resolve to parsed files.
179
+ pub unresolved_dependencies: usize,
180
+ /// Dart part files whose `part of` relationship is invalid.
181
+ pub part_of_violations: usize,
182
+ /// Declared pub dependencies not imported by Dart files.
183
+ pub unused_dependencies: usize,
184
+ /// Declared dev dependencies not imported by Dart files.
185
+ pub unused_dev_dependencies: usize,
186
+ /// Runtime dependencies imported only from dev/test files.
187
+ pub test_only_dependencies: usize,
188
+ /// Dependency override findings across all override hygiene classes.
189
+ pub dependency_overrides: usize,
190
+ /// Dependency overrides absent from the resolved lockfile package graph.
191
+ pub unused_dependency_overrides: usize,
192
+ /// Dependency override entries Pub cannot honor.
193
+ pub misconfigured_dependency_overrides: usize,
194
+ /// Imported pub packages absent from pubspec dependencies.
195
+ pub unlisted_dependencies: usize,
196
+ /// Imports into another package's private `lib/src` implementation tree.
197
+ pub private_src_imports: usize,
198
+ /// Unreachable files.
199
+ pub dead_files: usize,
200
+ /// Unused public top-level declarations.
201
+ pub unused_exports: usize,
202
+ /// Unused public top-level type aliases.
203
+ pub unused_types: usize,
204
+ /// Public signatures exposing same-library private Dart types.
205
+ pub private_type_leaks: usize,
206
+ /// Unused enum constants.
207
+ pub unused_enum_members: usize,
208
+ /// Unused private class-like members.
209
+ pub unused_class_members: usize,
210
+ /// Public API symbols exported from multiple declarations.
211
+ pub duplicate_exports: usize,
212
+ /// Typed `GoRouter` route path or name collisions.
213
+ pub route_collisions: usize,
214
+ /// Private classes extending Flutter widget bases.
215
+ pub private_widget_classes: usize,
216
+ /// Top-level Flutter widget helper functions.
217
+ pub widget_top_level_functions: usize,
218
+ /// Flutter widget constructor params that are never read.
219
+ pub unused_widget_params: usize,
220
+ /// Flutter widget classes with no reachable object construction.
221
+ pub unrendered_widgets: usize,
222
+ /// Widget or `State` awaits missing an immediate `context.mounted` guard.
223
+ pub missing_context_mounted_after_await: usize,
224
+ /// Duplicated Dart code clone groups.
225
+ pub code_duplications: usize,
226
+ /// Dart source lines included in duplicate analysis.
227
+ pub duplication_analyzed_lines: usize,
228
+ /// Unique Dart lines covered by duplicate clone groups.
229
+ pub duplicated_lines: usize,
230
+ /// Duplicated line percentage in percentage basis points.
231
+ pub duplication_percentage_basis_points: u32,
232
+ /// Duplicate threshold percentage in percentage basis points.
233
+ #[serde(default, skip_serializing_if = "Option::is_none")]
234
+ pub duplication_threshold_basis_points: Option<u32>,
235
+ /// Whether duplicated lines exceeded the configured threshold.
236
+ pub duplication_threshold_exceeded: bool,
237
+ /// Aggregate 0-100 project health score; higher is healthier.
238
+ pub quality_score: usize,
239
+ /// Dart source files included in health analysis.
240
+ pub health_files: usize,
241
+ /// Function-like declarations included in health analysis.
242
+ pub functions: usize,
243
+ /// Functions exceeding complexity thresholds.
244
+ pub complex_functions: usize,
245
+ /// Highest cyclomatic complexity.
246
+ pub max_cyclomatic_complexity: usize,
247
+ /// Highest cognitive complexity.
248
+ pub max_cognitive_complexity: usize,
249
+ /// Files represented in the loaded LCOV report.
250
+ pub coverage_files: usize,
251
+ /// Dart files with no observed covered executable lines.
252
+ pub coverage_gaps: usize,
253
+ /// Functions exceeding the CRAP threshold.
254
+ pub crap_functions: usize,
255
+ /// Highest CRAP score.
256
+ pub max_crap_score: usize,
257
+ /// File health scores reported.
258
+ pub file_scores: usize,
259
+ /// Health hotspots reported.
260
+ pub hotspots: usize,
261
+ /// Refactoring targets reported.
262
+ pub refactoring_targets: usize,
263
+ /// Feature flags reported.
264
+ pub feature_flags: usize,
265
+ /// Total feature flag occurrences detected before `--top` truncation.
266
+ pub feature_flag_occurrences: usize,
267
+ /// Security candidate groups reported.
268
+ pub security_candidates: usize,
269
+ /// Total security candidate occurrences detected before `--top` truncation.
270
+ pub security_candidate_occurrences: usize,
271
+ /// Attack-surface inventory entries.
272
+ pub attack_surface: usize,
273
+ /// Missing requested entry points.
274
+ pub missing_entry_points: usize,
275
+ /// Circular dependency components.
276
+ pub cycles: usize,
277
+ /// Export-only circular dependency components.
278
+ pub re_export_cycles: usize,
279
+ /// Architecture boundary violations.
280
+ pub boundary_violations: usize,
281
+ /// Dart files outside every configured architecture boundary zone.
282
+ pub boundary_coverage: usize,
283
+ /// Forbidden direct calls from configured architecture zones.
284
+ pub boundary_call_violations: usize,
285
+ /// Declarative policy rule-pack violations.
286
+ pub policy_violations: usize,
287
+ /// Suppression comments missing required justification text.
288
+ pub missing_suppression_reasons: usize,
289
+ /// Changed-code audit risk score from 0-100.
290
+ #[serde(default, skip_serializing_if = "Option::is_none")]
291
+ pub risk_score: Option<usize>,
292
+ /// Changed-code audit risk band.
293
+ #[serde(default, skip_serializing_if = "Option::is_none")]
294
+ pub risk_level: Option<AuditRiskLevel>,
295
+ /// Changed-code finding attribution split.
296
+ #[serde(default, skip_serializing_if = "Option::is_none")]
297
+ pub attribution: Option<AuditAttribution>,
298
+ /// Total finding count.
299
+ pub findings: usize,
300
+ }
301
+
302
+ /// Agent-actionable finding.
303
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
304
+ pub struct Finding {
305
+ /// Stable rule id.
306
+ pub rule_id: String,
307
+ /// Stable finding fingerprint when the rule exposes one.
308
+ pub fingerprint: Option<String>,
309
+ /// Finding category.
310
+ pub kind: FindingKind,
311
+ /// Severity for gates.
312
+ pub severity: Severity,
313
+ /// Human-readable description.
314
+ pub message: String,
315
+ /// Primary file path, root-relative where possible.
316
+ pub path: String,
317
+ /// 1-based line.
318
+ pub line: usize,
319
+ /// 0-based byte column.
320
+ pub column: usize,
321
+ /// Whether the finding can be deleted safely from graph evidence alone.
322
+ pub safe_to_delete: bool,
323
+ /// Related files, root-relative where possible.
324
+ pub files: Vec<String>,
325
+ /// Related dependency edge when applicable.
326
+ pub edge: Option<FindingEdge>,
327
+ /// Suggested agent actions.
328
+ pub actions: Vec<FindingAction>,
329
+ }
330
+
331
+ /// Finding category.
332
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
333
+ #[serde(rename_all = "kebab-case")]
334
+ pub enum FindingKind {
335
+ /// Unreachable Dart file.
336
+ DeadFile,
337
+ /// Unused public top-level declaration.
338
+ UnusedExport,
339
+ /// Unused public top-level type alias.
340
+ UnusedType,
341
+ /// Public API signature exposes a same-library private type.
342
+ PrivateTypeLeak,
343
+ /// Unused enum constant.
344
+ UnusedEnumMember,
345
+ /// Unused private class-like member.
346
+ UnusedClassMember,
347
+ /// Public API entry exposes multiple declarations with the same name.
348
+ DuplicateExport,
349
+ /// Typed `GoRouter` routes declare the same path or route name.
350
+ RouteCollision,
351
+ /// Private class extends a Flutter widget base.
352
+ PrivateWidgetClass,
353
+ /// Top-level function belongs behind a Flutter widget boundary.
354
+ WidgetTopLevelFunctionBoundary,
355
+ /// Flutter widget constructor param is never read by the widget.
356
+ UnusedWidgetParam,
357
+ /// Flutter widget class is never constructed from reachable production code.
358
+ UnrenderedWidget,
359
+ /// Widget or `State` await lacks an immediate `context.mounted` guard.
360
+ MissingContextMountedAfterAwait,
361
+ /// Missing entry point.
362
+ MissingEntryPoint,
363
+ /// Strongly connected dependency component.
364
+ CircularDependency,
365
+ /// Strongly connected component composed only of export edges.
366
+ ReExportCycle,
367
+ /// Directory boundary violation.
368
+ BoundaryViolation,
369
+ /// Source file not covered by a configured boundary zone.
370
+ BoundaryCoverage,
371
+ /// Zoned file calls a forbidden callee.
372
+ BoundaryCallViolation,
373
+ /// Declarative policy pack violation.
374
+ PolicyViolation,
375
+ /// Local import/export/part/augment target was absent.
376
+ UnresolvedDependency,
377
+ /// Dart `part` and `part of` directives disagree about library membership.
378
+ PartOfViolation,
379
+ /// Declared pub dependency has no Dart import/export usage.
380
+ UnusedDependency,
381
+ /// Declared dev dependency has no Dart import/export usage.
382
+ UnusedDevDependency,
383
+ /// Runtime dependency is imported only from dev/test files.
384
+ TestOnlyDependency,
385
+ /// Dependency override is absent from the resolved lockfile package graph.
386
+ UnusedDependencyOverride,
387
+ /// Dependency override key or value cannot be honored by Pub.
388
+ MisconfiguredDependencyOverride,
389
+ /// Imported pub package is missing from pubspec.
390
+ UnlistedDependency,
391
+ /// Import reaches into another package's private `lib/src` implementation tree.
392
+ PrivateSrcImport,
393
+ /// Duplicated Dart code block.
394
+ CodeDuplication,
395
+ /// Function exceeded the cyclomatic complexity threshold.
396
+ HighCyclomaticComplexity,
397
+ /// Function exceeded the cognitive complexity threshold.
398
+ HighCognitiveComplexity,
399
+ /// Function exceeded both complexity thresholds.
400
+ HighComplexity,
401
+ /// Dart file has no observed covered executable lines.
402
+ CoverageGap,
403
+ /// Function exceeded the CRAP threshold.
404
+ HighCrapScore,
405
+ /// File is a low-scoring health hotspot.
406
+ HealthHotspot,
407
+ /// File is a prioritized refactoring target.
408
+ RefactoringTarget,
409
+ /// Feature flag reference.
410
+ FeatureFlag,
411
+ /// Security review candidate.
412
+ SecurityCandidate,
413
+ /// Suppression comment did not match any finding.
414
+ StaleSuppression,
415
+ /// Suppression comment is missing a required reason.
416
+ MissingSuppressionReason,
417
+ }
418
+
419
+ /// Finding severity.
420
+ #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
421
+ #[serde(rename_all = "kebab-case")]
422
+ pub enum Severity {
423
+ /// Fails the command verdict.
424
+ Error,
425
+ /// Reports without failing the command verdict.
426
+ Warning,
427
+ }
428
+
429
+ /// Dependency edge attached to a finding.
430
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
431
+ pub struct FindingEdge {
432
+ /// Source file.
433
+ pub from: String,
434
+ /// Target file when resolved, or attempted target when unresolved.
435
+ pub to: String,
436
+ /// Raw import/export/part/augment URI.
437
+ pub specifier: String,
438
+ /// `import`, `export`, `part`, or `augment`.
439
+ pub kind: String,
440
+ }
441
+
442
+ /// Suggested follow-up action.
443
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
444
+ pub struct FindingAction {
445
+ /// Stable action id.
446
+ pub action: String,
447
+ /// Fallow-compatible action discriminator.
448
+ #[serde(rename = "type")]
449
+ action_type: String,
450
+ /// Human-readable action description.
451
+ pub description: String,
452
+ /// Whether an agent can apply the action without semantic review.
453
+ pub auto_fixable: bool,
454
+ /// Read-only command to collect more evidence before acting.
455
+ #[serde(default, skip_serializing_if = "Option::is_none")]
456
+ pub command: Option<String>,
457
+ /// Argument vector for executing `command` without shell parsing.
458
+ #[serde(default, skip_serializing_if = "Vec::is_empty")]
459
+ pub argv: Vec<String>,
460
+ /// Root-relative file path targeted by the action.
461
+ #[serde(default, skip_serializing_if = "Option::is_none")]
462
+ pub target_path: Option<String>,
463
+ /// Top-level symbol targeted by the action.
464
+ #[serde(default, skip_serializing_if = "Option::is_none")]
465
+ pub target_symbol: Option<String>,
466
+ /// Pub dependency targeted by the action.
467
+ #[serde(default, skip_serializing_if = "Option::is_none")]
468
+ pub target_dependency: Option<String>,
469
+ /// 1-based last source line targeted by the action.
470
+ #[serde(default, skip_serializing_if = "Option::is_none")]
471
+ pub target_end_line: Option<usize>,
472
+ /// Inline suppression comment an agent can insert after review.
473
+ #[serde(default, skip_serializing_if = "Option::is_none")]
474
+ pub suppression_comment: Option<String>,
475
+ /// Configuration key targeted by the action.
476
+ #[serde(default, skip_serializing_if = "Option::is_none")]
477
+ pub config_key: Option<String>,
478
+ /// Human-readable value schema for config-edit actions.
479
+ #[serde(default, skip_serializing_if = "Option::is_none")]
480
+ pub value_schema: Option<String>,
481
+ }
482
+
483
+ impl FindingAction {
484
+ /// Build a stable finding action.
485
+ #[must_use]
486
+ pub fn new(
487
+ action: impl Into<String>,
488
+ description: impl Into<String>,
489
+ auto_fixable: bool,
490
+ ) -> Self {
491
+ let action = action.into();
492
+ Self {
493
+ action_type: action.clone(),
494
+ action,
495
+ description: description.into(),
496
+ auto_fixable,
497
+ command: None,
498
+ argv: Vec::new(),
499
+ target_path: None,
500
+ target_symbol: None,
501
+ target_dependency: None,
502
+ target_end_line: None,
503
+ suppression_comment: None,
504
+ config_key: None,
505
+ value_schema: None,
506
+ }
507
+ }
508
+
509
+ /// Attach a Dart Decimate command with both shell-safe text and argv forms.
510
+ #[must_use]
511
+ pub fn with_dart_decimate_args<I, S>(mut self, args: I) -> Self
512
+ where
513
+ I: IntoIterator<Item = S>,
514
+ S: Into<String>,
515
+ {
516
+ self.argv = std::iter::once("dart-decimate".to_owned())
517
+ .chain(args.into_iter().map(Into::into))
518
+ .collect();
519
+ self.command = Some(shell_command(&self.argv));
520
+ self
521
+ }
522
+
523
+ /// Attach a root-relative target file path.
524
+ #[must_use]
525
+ pub fn with_target_path(mut self, path: impl Into<String>) -> Self {
526
+ self.target_path = Some(path.into());
527
+ self
528
+ }
529
+
530
+ /// Attach a top-level target symbol.
531
+ #[must_use]
532
+ pub fn with_target_symbol(mut self, symbol: impl Into<String>) -> Self {
533
+ self.target_symbol = Some(symbol.into());
534
+ self
535
+ }
536
+
537
+ /// Attach a pub dependency target.
538
+ #[must_use]
539
+ pub fn with_target_dependency(mut self, dependency: impl Into<String>) -> Self {
540
+ self.target_dependency = Some(dependency.into());
541
+ self
542
+ }
543
+
544
+ /// Attach a 1-based last source line for range edits.
545
+ #[must_use]
546
+ pub fn with_target_end_line(mut self, line: usize) -> Self {
547
+ self.target_end_line = Some(line);
548
+ self
549
+ }
550
+
551
+ /// Attach an inline suppression comment.
552
+ #[must_use]
553
+ pub fn with_suppression_comment(mut self, comment: impl Into<String>) -> Self {
554
+ self.suppression_comment = Some(comment.into());
555
+ self
556
+ }
557
+
558
+ /// Attach a config key.
559
+ #[must_use]
560
+ pub fn with_config_key(mut self, config_key: impl Into<String>) -> Self {
561
+ self.config_key = Some(config_key.into());
562
+ self
563
+ }
564
+
565
+ /// Attach a human-readable value schema for config-edit actions.
566
+ #[must_use]
567
+ pub fn with_value_schema(mut self, value_schema: impl Into<String>) -> Self {
568
+ self.value_schema = Some(value_schema.into());
569
+ self
570
+ }
571
+ }
572
+
573
+ fn shell_command(argv: &[String]) -> String {
574
+ argv.iter()
575
+ .map(|arg| shell_escape(arg))
576
+ .collect::<Vec<_>>()
577
+ .join(" ")
578
+ }
579
+
580
+ fn shell_escape(arg: &str) -> String {
581
+ if arg.chars().all(is_shell_safe) {
582
+ return arg.to_owned();
583
+ }
584
+ format!("'{}'", arg.replace('\'', "'\"'\"'"))
585
+ }
586
+
587
+ fn is_shell_safe(character: char) -> bool {
588
+ character.is_ascii_alphanumeric()
589
+ || matches!(
590
+ character,
591
+ '/' | '.' | ':' | '_' | '-' | '=' | '+' | ',' | '@'
592
+ )
593
+ }
594
+
595
+ /// Read-only follow-up command.
596
+ #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
597
+ pub struct NextStep {
598
+ /// Stable next-step id.
599
+ pub id: String,
600
+ /// Runnable command from the project root.
601
+ pub command: String,
602
+ /// Why this command should be run.
603
+ pub reason: String,
604
+ }