uv-sbom: Instructions file for Codex

AGENTS.md - Codebase Context for AI Agents

1. Project Overview

Project: uv-sbom Purpose: CLI tool to generate SBOM (Software Bill of Materials) from Python projects managed by uv.

Key Features:

• Parse uv.lock and extract dependency information
• Fetch license info from PyPI API (with retry logic)
• Check known vulnerabilities via OSV API (Markdown format only)
• Output formats: CycloneDX 1.6 JSON, Markdown (with direct/transitive dependency separation)
• Standalone Rust binary, progress display, robust error handling

Distribution:

• Cargo: cargo install uv-sbom
• PyPI: pip install uv-sbom-bin
• GitHub Releases: macOS / Linux / Windows binaries

Tech Stack: Rust 2021 edition, Hexagonal Architecture + DDD

---

2. Directory Structure

uv-sbom/
├── src/
│   ├── main.rs                    # Entry point (DI wiring only)
│   ├── lib.rs                     # Library root (public API)
│   ├── cli.rs                     # CLI parsing (clap)
│   ├── config.rs                  # YAML config file support
│   ├── sbom_generation/           # Domain layer (pure business logic)
│   │   ├── domain/
│   │   │   ├── package.rs         # Package, PackageName, Version
│   │   │   ├── license_info.rs    # LicenseInfo value object
│   │   │   ├── dependency_graph.rs # DependencyGraph aggregate
│   │   │   ├── sbom_metadata.rs   # SbomMetadata (timestamp, UUID)
│   │   │   ├── vulnerability.rs   # Vulnerability, Severity, CvssScore
│   │   │   ├── enriched_package.rs    # EnrichedPackage struct
│   │   │   ├── uv_lock_simulator.rs   # UvLockSimulator trait (domain-owned port), SimulationResult
│   │   │   └── services/
│   │   │       └── vulnerability_checker.rs  # Threshold evaluation
│   │   ├── services/              # Domain services (pure functions)
│   │   │   ├── dependency_analyzer.rs  # Dependency analysis, cycle detection
│   │   │   ├── package_filter.rs       # Package filtering
│   │   │   └── sbom_generator.rs       # SBOM metadata generation
│   │   └── policies/
│   │       └── license_priority.rs     # License selection rules
│   ├── application/               # Application layer (use cases)
│   │   ├── use_cases/
│   │   │   ├── generate_sbom/     # Main use case + tests
│   │   │   └── check_vulnerabilities.rs
│   │   ├── dto/                   # Data transfer objects
│   │   │   ├── output_format.rs   # OutputFormat enum (Json/Markdown)
│   │   │   ├── sbom_request.rs    # SbomRequest + builder
│   │   │   └── sbom_response.rs   # SbomResponse
│   │   ├── factories/             # Factory pattern implementations
│   │   │   ├── formatter_factory.rs
│   │   │   └── presenter_factory.rs
│   │   └── read_models/           # CQRS read models
│   │       ├── component_view.rs
│   │       ├── dependency_view.rs
│   │       ├── vulnerability_view.rs
│   │       ├── sbom_read_model.rs
│   │       └── sbom_read_model_builder.rs
│   ├── ports/                     # Port interfaces (traits)
│   │   ├── outbound/
│   │   │   ├── lockfile_reader.rs          # LockfileReader trait
│   │   │   ├── project_config_reader.rs    # ProjectConfigReader trait
│   │   │   ├── license_repository.rs       # LicenseRepository trait
│   │   │   ├── vulnerability_repository.rs # VulnerabilityRepository trait
│   │   │   ├── formatter.rs               # SbomFormatter trait
│   │   │   ├── output_presenter.rs        # OutputPresenter trait
│   │   │   └── progress_reporter.rs       # ProgressReporter trait
│   │   └── inbound/               # (reserved for future use)
│   ├── adapters/                  # Infrastructure implementations
│   │   └── outbound/
│   │       ├── filesystem/
│   │       │   ├── file_reader.rs   # FileSystemReader (LockfileReader + ProjectConfigReader)
│   │       │   └── file_writer.rs   # FileSystemWriter, StdoutPresenter
│   │       ├── network/
│   │       │   ├── pypi_client.rs          # PyPiLicenseRepository
│   │       │   ├── caching_pypi_client.rs  # CachingPyPiLicenseRepository
│   │       │   └── osv_client.rs           # OsvClient
│   │       ├── formatters/
│   │       │   ├── cyclonedx_formatter.rs  # CycloneDX JSON output
│   │       │   └── markdown_formatter.rs   # Markdown output
│   │       └── console/
│   │           └── progress_reporter.rs    # StderrProgressReporter
│   └── shared/                    # Shared kernel
│       ├── error.rs               # Domain errors, ExitCode enum
│       ├── result.rs              # Result type alias
│       └── security.rs            # Security validation
├── tests/
│   ├── integration_test.rs        # Use case-level integration tests
│   ├── e2e_test.rs                # Fixture-based E2E tests
│   ├── e2e_vulnerability_threshold.rs  # Vulnerability threshold E2E
│   ├── test_utilities/mocks/      # Mock objects
│   └── fixtures/                  # Test fixtures (sample projects)
│       ├── sample-project/
│       ├── safe_project/
│       ├── vulnerable_project/
│       └── expected-outputs/
├── python-wrapper/                # PyPI distribution wrapper
├── .github/workflows/             # CI/CD (ci.yml, release.yml)
├── .claude/                       # Claude Code config & skills
├── docs/                          # Additional documentation
├── ARCHITECTURE.md                # Architecture details (English)
├── DEVELOPMENT.md                 # Development guide
├── README.md                      # User documentation (English)
└── AGENTS.md                      # This file