ComposeLens

ComposeLens is a Rust library for reading, understanding, transforming, validating, and rendering real-world Compose documents.

It is designed for tools that need more than strict deserialization: source-aware diagnostics, implementation extensions, optional interpolation, multi-file projects, profiles, and round-trip-safe transformations.

[!IMPORTANT] ComposeLens 0.1.x is the first supported pre-1.0 release line. Its API covers loss-aware YAML syntax, the source-aware native model, explicit project processing, version-aware compatibility profiles, deterministic merged-project rendering, presentation-only formatting, and atomic value-scalar editing. A native merged/profile-selected project view retains complete multi-file provenance for adapters. The typed boundary includes the first BoxFerry conversion fields plus issue-derived host mappings, identities, limits, health-gated dependencies, container paths, and field-level build/deploy models. Structural editing, the complete Compose model, and reviewed runtime-effect results are not yet available.

Goals

• Parse Compose YAML without forcing immediate normalization or interpolation.
• Represent syntax, typed Compose concepts, extensions, and unknown fields explicitly.
• Preserve field-specific short and long syntax when their defaults or runtime behavior can differ.
• Preserve enough source information for actionable diagnostics and safe editing.
• Support multi-file project loading, merging, profile selection, and configurable interpolation.
• Model behavior found in real Docker Compose and Podman Compose projects.
• Render deterministic Compose documents.
• Allow callers to choose strict, implementation-specific, or tolerant validation profiles.

Non-goals

• Running a Compose project
• Reimplementing Docker or Podman
• Converting Compose directly to Quadlet or Kubernetes
• Enforcing OCI rules that real Compose implementations do not enforce
• Treating the Compose Specification as the only source of real-world behavior

Cross-format conversion belongs to BoxFerry. Quadlet handling belongs to QuadletLens.

Processing levels

source text
  → loss-aware syntax document
  → typed Compose document
  → loaded multi-file project
  → optional per-file interpolation
  → provenance-preserving merged project
  → optional profile selection and native project view
  → references, paths, defaults, and compatibility
  → validated semantic view
  → rendered Compose document

Callers may stop at any appropriate level. Parsing a document must not implicitly read environment variables or contact a runtime.

Documentation

• Published Rust API documentation
• Documentation index
• Software architecture
• Target project structure
• Processing model
• Preservation-oriented editing
• Render formatting
• Phase 2 typed model
• Testing strategy
• Development environment
• Compose implementation conformance
• Real-world fixture corpus
• Cross-repository implementation plan
• API stability policy
• 0.1.1 release notes
• Release process
• Changelog
• Roadmap
• Architecture decisions

Repository-specific guidance for coding agents is in AGENTS.md.

Origin

ComposeLens is implemented from scratch. It is not a fork of compose_spec_rs and does not copy or mechanically translate its source code.

Stewardship

ComposeLens is created and maintained by Martin “Becks” Beckert through Strukturpiloten OHG. The project is part of Strukturpiloten's work on open, maintainable, and portable container infrastructure.

License

ComposeLens is licensed under the Mozilla Public License 2.0.