scan library

Programmatic scan API for saropa_lints.

Use this when you want to run a scan from code (e.g. from another package or script) without invoking the CLI. The types and functions here are part of the public API and follow semver.

Example:

import 'package:saropa_lints/scan.dart';

void main() {
  final runner = ScanRunner(
    targetPath: '/path/to/project',
    tier: 'recommended',           // optional: override config with a tier
    dartFiles: ['lib/main.dart'],   // optional: scan only these files
    messageSink: (msg) => log(msg), // optional: redirect/suppress output
  );
  final diagnostics = runner.run();
  if (diagnostics != null) {
    // process diagnostics or serialize with scanDiagnosticsToJson(diagnostics)
  }
}

ScanRunner.run is a fast syntactic pass; rules on instance-creation expressions and type-based rules under-report there. Use the async ScanRunner.runResolved to scan with full resolution when those rules matter (slower, and the target must have had pub get run).

Classes

AnalysisContextCollection: A collection of analysis contexts.
ScanConfig: Rule configuration loaded from a project's config files.
ScanDiagnostic: A single lint diagnostic found during scanning.
ScanRunner: Scans Dart files using saropa_lints rules without the plugin framework.
StaleIgnore: A single stale ignore finding: an ignore directive whose suppressed rule did not produce a diagnostic on the target line.
StaleIgnoreFixResult: Result of fixing stale ignores in a single file: tracks the count of removed ignore directives and the rewritten file content.

Functions

buildSarifReport(List<Map<String, dynamic>> diagnostics, {required String rootPath, required String toolVersion}) → Map<String, dynamic>: Builds a full SARIF 2.1.0 log for diagnostics (enriched diagnostic maps as produced by scanDiagnosticsToJson + audit's tier/category enrichment). rootPath anchors the relative artifactLocation.uri values. toolVersion should be saropaLintsVersion from package:saropa_lints/saropa_lints.dart — passed in rather than read here so this module has no dependency on the package's own export graph.
categoryForRule(String ruleName) → String?: Returns the category slug for ruleName (e.g. core, security, packages), derived from the source file's parent directory. Returns null if the rule is not in the generated category map.
categoryIndexForRules(Set<String> ruleNames) → Map<String, String>: Returns the category for every rule in ruleNames, keyed by rule name. Rules not in the category map are omitted from the result.
detectStaleIgnores({required List<ScanDiagnostic> diagnostics, required List<String> files}) → List<StaleIgnore>: Detects stale // ignore: comments across the given files by comparing them against diagnostics from a scan run.
fixStaleIgnores(List<StaleIgnore> staleIgnores) → List<StaleIgnoreFixResult>: Removes stale ignore directives from the source files they appear in.
gitChangedDartFiles(String repoPath, String ref) → List<String>: Returns the list of .dart files changed between ref and HEAD in the repository at repoPath.
loadScanConfig(String projectRoot) → ScanConfig?: Attempts to load rule config from the project at projectRoot.
sarifLevelForSeverity(String? severity) → String: Maps this project's three-level LintImpact/severity scale (error, warning, info — see saropa_lint_rule.dart) onto SARIF's level enum (error, warning, note, none). There is no finer-grained scale in the codebase to draw from, so this is a direct 1:1 mapping, not an invented scale. Unrecognized values fall back to warning rather than none, because none means "not evaluated as a problem" in the SARIF spec — a worse default for an unknown diagnostic than surfacing it visibly.
sarifReportToJsonString(List<Map<String, dynamic>> diagnostics, {required String rootPath, required String toolVersion}) → String: Encodes diagnostics as a pretty-printed SARIF 2.1.0 JSON string. Mirrors scanDiagnosticsToJsonString's encoding convention (2-space indent) so both output formats look consistent to a human reading --output files side by side.
scanDiagnosticsToJson(List<ScanDiagnostic> diagnostics, {Map<String, Object>? failOn}) → Map<String, Object>: Serializes diagnostics to the same JSON structure used by dart run saropa_lints scan --format json.
scanDiagnosticsToJsonString(List<ScanDiagnostic> diagnostics, {Map<String, Object>? failOn}) → String: Encodes diagnostics to a JSON string (pretty-printed).
staleIgnoresToJsonString(List<StaleIgnore> staleIgnores) → String: Serializes staleIgnores to the JSON format compatible with the scan CLI's --format json output convention.
tierForRule(String ruleName) → String?: Returns the tier name for ruleName, or null if the rule is not registered in any tier set.
tierIndexForRules(Set<String> ruleNames) → Map<String, String>: Returns the tier name for every rule in ruleNames, keyed by rule name. Rules not in any tier are omitted from the result.

Typedefs

ScanMessageSink = void Function(String message): Optional sink for progress and error messages. When null, output goes to stdout (messages) and stderr (progress). When set, all output is sent to this callback so callers can suppress or redirect.

scan library

Classes

Functions

Typedefs

saropa_lints package

scan library