# Architecture

High-level overview of the sbom-tools codebase (~87K LOC, ~200 Rust files).

## Module Structure

```
src/
  cli/            Command handlers (clap-based, 18 subcommands)
  config/         YAML/JSON configuration, presets, validation, schema generation
  model/          Canonical SBOM representation (NormalizedSbom, Component, CanonicalId)
  parsers/        Format detection + parsing (streaming for >512MB)
  matching/       Multi-tier fuzzy matching (PURL, alias, ecosystem, adaptive, LSH)
  diff/           Semantic diffing engine + graph diff + incremental section-selective diff
  enrichment/     OSV/KEV vulnerability data, EOL detection, VEX (feature-gated)
  quality/        8-category scoring engine v2.0 + 9 compliance standards
  pipeline/       Orchestration: parse -> enrich -> diff -> report + shared enrichment pipeline
  reports/        9 output format generators + streaming reporter
  tui/            Interactive terminal UI (ratatui) — diff, view, multi-diff, timeline, matrix
  verification/   File hash verification + component hash auditing
  license/        License policy engine (allow/deny/review) + propagation analysis
  serialization/  Raw JSON enrichment, tailoring (filter), merging with dedup
  watch/          Continuous SBOM monitoring (file watcher, vulnerability alerts)
```

## Data Flow

```
Input SBOMs (CycloneDX/SPDX)
    |
    v
  Parsers ──> NormalizedSbom (canonical model)
    |
    v
  Enrichment (OSV, KEV, EOL)  [optional, feature-gated]
    |
    v
  Matching Engine ──> Component pairs
    |
    v
  Diff Engine ──> ChangeSet (added/removed/modified)
    |
    v
  Reports / TUI
```

## Key Design Decisions

### Canonical Model (`model/`)
All SBOM formats are normalized into `NormalizedSbom` with `Component`, `Vulnerability`, and `Dependency` types. This allows format-agnostic diffing and analysis.

### Multi-Tier Matching (`matching/`)
Components are matched across SBOMs using a tiered strategy:
1. Exact PURL match
2. Alias lookup (known package renames)
3. Ecosystem-specific normalization
4. String similarity with adaptive thresholds
5. LSH indexing for large SBOMs

### Quality Scoring (`quality/`)
8-category scoring engine (v2.0) with 6 profiles. N/A-aware weight renormalization handles missing data gracefully. Hard caps enforce minimum standards (e.g., EOL components cap grade at D).

### Compliance (`quality/`)
9 standards: NTIA, CRA Phase 1/2, FDA, NIST SSDF, EO 14028, plus Minimum and Comprehensive. Each standard defines required fields and produces SARIF-compatible findings.

### TUI (`tui/`)
Built on ratatui with crossterm backend. Unified `App` struct with `ViewState` trait pattern:
- **Diff mode** — 10 tabs: Summary, Components, Dependencies, Licenses, Vulnerabilities, Quality, Compliance, Side-by-Side, Graph Changes, Source
- **View mode** — 8 tabs: Overview, Tree, Vulnerabilities, Licenses, Dependencies, Quality, Compliance, Source
- **Multi-modes** — Full-screen views for diff-multi (1:N), timeline, and matrix (NxN) comparisons
- All tabs implement `ViewState` trait for modular event handling
- `RenderContext` provides read-only rendering decoupled from state mutation
- Features: regex search (Ctrl+R), composable vulnerability filters, version downgrade detection, cached grouped rendering

### Streaming Parser (`parsers/`)
SBOMs larger than 512MB are parsed with a streaming strategy to avoid memory exhaustion.

### Diff Engine (`diff/`)
- Section-selective incremental diffing: only recomputes changed sections (components, dependencies, licenses, vulnerabilities) when cache detects partial changes
- `QualityDelta` tracks per-category quality score changes across SBOM versions
- `VexStatusChange` detects VEX state transitions for persistent vulnerabilities
- `MatchMetrics` records matching quality statistics (exact/fuzzy/rule match counts)
- Cost model with presets (default, security-focused, compliance-focused)

### Pipeline (`pipeline/`)
`PipelineError` provides structured errors across stages. Shared enrichment pipeline (`pipeline/enrich.rs`) composes OSV + EOL + VEX enrichment into a single `enrich_sbom_full()` call used by all commands.

## Error Handling

- `thiserror` for library error types
- `anyhow` for CLI error propagation
- `PipelineError` for pipeline stage errors
- Zero `unwrap()` in production; ~22 `expect()` calls, all safe-by-construction

## Feature Flags

- `enrichment` (default) — enables OSV/KEV vulnerability enrichment, EOL detection, and VEX support

## Go and Swift Bindings MVP

The repository now includes a C-compatible ABI layer in [src/ffi.rs](src/ffi.rs) for the Go and Swift MVP bindings.

- The ABI surface is intentionally narrow: format detection, parse from path/string, diffing, quality scoring, and ABI version reporting.
- All complex values cross the ABI as JSON strings rather than field-by-field structs. This keeps the ABI stable for both `cgo` and Swift while allowing the Rust data model to evolve internally.
- The stable header lives at [bindings/swift/Sources/CSbomTools/include/sbom_tools.h](bindings/swift/Sources/CSbomTools/include/sbom_tools.h). Both wrappers consume that same header.
- The Go wrapper lives in [bindings/go](bindings/go) and the Swift package lives in [bindings/swift](bindings/swift).
- Errors are mapped into stable numeric codes plus UTF-8 messages, and every ABI result must be released with `sbom_tools_string_result_free`.
- Both wrappers expose opt-in deduplication helpers for normalized payloads. Components deduplicate by canonical identifier, edges deduplicate by full edge shape, and last occurrence wins in both cases.
- Dedup regression checks are centralized in [scripts/test-bindings-dedup.sh](scripts/test-bindings-dedup.sh) and are invoked by bindings CI to keep Go and Swift helper behavior aligned.

## Testing

- 912+ tests (unit + integration)
- Property-based testing via `proptest` (matching symmetry, score range, self-match)
- Fuzz targets for all parser formats (`cargo-fuzz`)
- Golden fixture tests for format compatibility
- Integration tests in `tests/` covering pipeline, CLI, CRA, query, VEX, watch, and graph

## CI/CD

- 10 CI jobs: lint, MSRV, 4 platform tests, 2 cargo-deny, security audit, gate
- CodeQL for static analysis
- OpenSSF Scorecard for security posture
- Trusted Publishing (OIDC) for crates.io releases
- SLSA Build Level 3 provenance for releases
