Development

Development

Common commands

dart pub get                                          # Install dependencies
dart analyze                                          # Lint
dart test                                             # Run all tests
dart test test/features/analysis/build_tree_metrics_test.dart   # Run a single test file
dart test --name "extracts await-related features"    # Run tests matching a name

Testing layout

• test/features/analysis/ holds integration-style tests that exercise real Dart files through the analyzer. Fixtures live in test/fixtures/analysis/ (~20 realistic Dart source files). When adding an extractor or visitor, add a corresponding fixture and test here.
• test/features/analysis/utils/test_helper.dart provides getResultsForFixture(relativePath). Prefer it over re-wiring the analysis pipeline in each test.
• test/features/isolation/ holds tests for the isolation pipeline. Fixtures in test/fixtures/isolation/ cover builder patterns, external deps, and runnable targets. test/fixtures/isolation_third_party/ui_kit/ is a small package that sits outside the project on purpose, so the third-party gate actually fires; the suites that use it build a throwaway project at run time through test/features/isolation/utils/temp_project.dart, because a checked-in file importing package:ui_kit resolves for nobody and reads as an undeclared dependency.
• test/features/validation/ holds tests for the validate gate. Fixtures in test/fixtures/validation/<case>/{base.dart, mutation.dart}, where each case proves one expected violation code. Run with dart test test/features/validation/.

Testing conventions

• Use hand-written fakes only, never mocks. Implement the repository/data-source interface directly.
• Repository fakes expose givenSuccess() / givenFailure(Failure); data-source fakes expose givenSuccess() / givenThrows(Exception).
• When capturing call arguments in a fake, copy list references: List.of(targets).
• Async exception tests must be async and await the call inside a try/catch.
• For file-I/O tests, use Directory.systemTemp.createTempSync(...) in setUp and delete in tearDown.
• When testing through the DI layer, call the relevant DI class's reset() in setUp/tearDown to clear singletons.

Conventions recap

• Use the type aliases in src/core/types.dart (Result<T>, AsyncResult<T>, JsonRecord); never spell out the full types inline.
• Return Either<Failure, T> in data/domain layers; throw only at the outermost CLI boundary.
• Log through SpmLogger, never print.

See Architecture for the full layer and error-handling model.