Dart API
Everything the CLI does is available from package:arch_guard/arch_guard.dart, for custom reports, dashboards or editor tooling. The full reference is on pub.dev. For checks inside dart test, use expectArchitecture() instead.
Run a full analysis
ArchAnalysis.run() does what the CLI does: reads arch_guard.yaml, scans, finds cycles, checks every rule and compares with the baseline. The CLI derives its exit code from the same result.
import 'package:arch_guard/arch_guard.dart';
Future<void> main() async {
final analysis = await ArchAnalysis.run(
projectPath: '.', // defaults shown
scanDirs: ['lib'],
useBaseline: true,
// since: 'origin/main', // only problems in files changed on the branch
);
// What would make `arch_guard` exit 1, as readable lines.
for (final problem in analysis.failures()) {
print(problem);
}
// Or the typed results. The `new…` lists leave out what the baseline knows.
print('Cycles: ${analysis.newCycles.length}');
print('Layer violations: ${analysis.newLayerViolations.length}');
print('Most coupled: ${analysis.hotspots.take(3).map((m) => m.file)}');
}
| Field | Contents |
|---|---|
scan, graph, config |
The ScanResult, DependencyGraph and loaded ArchGuardConfig. |
cycles, newCycles, oversizedCycles |
Circular dependency groups; the new ones; those over max_scc_size. |
layerViolations, packageViolations, workspaceViolations, moduleViolations, metricViolations |
Rule failures. Each has a new… getter too. |
unusedFiles, newUnusedFiles |
Files no entry point reaches, when unused_files: is on. |
fileMetrics, hotspots |
Fan-in and fan-out per file; the most coupled first (by commits × coupling with churn_since). |
churn |
Commits per file since metrics: churn_since, or null. |
coverage |
Which files fall into which layer, and which into none. |
baseline |
The comparison with the baseline file, or null without one. |
warnings |
Configuration warnings, as the CLI prints on stderr. |
Build your own pipeline
Use the pieces directly when you don’t want a config file or a baseline:
import 'package:arch_guard/arch_guard.dart';
Future<void> main() async {
// 1. Scan the project (or workspace) into files and directives.
final result = await ProjectScanner(
rootPath: '.',
scanDirs: ['lib'],
exclude: ['*.g.dart', '*.freezed.dart'],
enableWorkspace: true,
).scan();
// 2. Build the graph and find cycles (Tarjan's strongly connected components).
final graph = DependencyGraph.fromScanResult(result);
final cycles = graph.findCircularDependencies();
// 3. Check layers defined in code.
const config = ArchGuardConfig(
layers: {
'domain': LayerDefinition(
name: 'domain',
patterns: ['lib/domain/**'],
allowedImports: ['domain'],
),
'presentation': LayerDefinition(
name: 'presentation',
patterns: ['lib/presentation/**'],
allowedImports: ['presentation', 'domain'],
),
},
);
final violations = LayerValidator.validate(result: result, config: config);
// 4. Render any report.
print(MermaidExporter.export(result: result, cycles: cycles));
print('${cycles.length} cycles, ${violations.length} layer violations');
}
To read arch_guard.yaml instead of building the config in code, use ArchGuardConfig.load('.').
Classes
Analysis
| Class | Purpose |
|---|---|
ArchAnalysis |
A full run in one call. See above. |
expectArchitecture() |
In package:arch_guard/testing.dart. Runs ArchAnalysis and throws ArchitectureViolationException on failures. See Tests. |
ArchGuardConfig |
Loads arch_guard.yaml or the pubspec.yaml section (load), presets included. |
Baseline |
Reads, writes and compares against arch_guard_baseline.json. |
GitChanges |
Files changed since a git ref (since), as used by --since. |
Scanning and the graph
| Class | Purpose |
|---|---|
ProjectScanner |
Finds Dart files and workspace packages and reads their directives into a ScanResult. scanSources() scans in-memory content. |
DependencyGraph |
Builds the graph and finds cycles (findCircularDependencies). |
CycleBreaker |
Suggests the import to remove to break a cycle (suggest). The graph attaches it as SccComponent.suggestedBreak. |
DependencyExplainer |
One file’s imports, importers and cycle membership, as --explain prints. |
ImportPath |
Shortest import chain between files, folders or packages (find), as why prints. |
AffectedFiles |
Files and tests reachable backwards from changed files (find), as affected prints. |
LayoutDetector |
Guesses a preset from the folder layout, as init does. |
Rules
| Class | Checks | Yields |
|---|---|---|
LayerValidator |
Imports against layers (validate); layer coverage (coverage). |
LayerViolation |
PackageValidator |
ScanResult.packageImports against forbidden_packages (validate), or one import at a time (checker). |
PackageViolation |
WorkspaceValidator |
Imports between workspace members against workspace_rules (validate), or one import at a time (checker, with memberResolver or your own file → member function). |
WorkspaceViolation |
ModuleValidator |
Imports between modules against modules: (public files, allowed). checker() checks one import. |
ModuleViolation |
MetricValidator |
FileMetrics against metrics: limits. |
MetricViolation |
FileMetrics |
Fan-in, fan-out and instability per file (compute), most coupled first. |
– |
UnusedFiles |
Files no entry point reaches (find). |
– |
Reports
TextReporter, HtmlExporter, MermaidExporter, DotExporter, JsonExporter, SarifExporter and MarkdownExporter render the results in each output format. GroupedGraph.build(analysis, groupBy: 'layer') groups an ArchAnalysis by layer, module, package or folder (each GroupEdge has an import count and a violation count); MermaidExporter.exportGrouped, DotExporter.exportGrouped and HtmlExporter.export(grouped: ...) draw it.