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.

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.
• Construct new deterministic Compose documents through Compose-owned, parse-back-validated values.
• Preserve, merge, inspect, and generate service metadata labels without exposing sensitive values through debug output.
• Preserve, merge, inspect, and generate explicit runtime container names with field provenance.
• Preserve, merge, inspect, and generate explicit service hostnames with conservative RFC-1123 validation, deferred-expression retention, and no synthesized default.
• Preserve, merge, inspect, and generate service-level restart policies without confusing them with dependency-update or deploy restart settings.
• Preserve, merge, inspect, and generate service stdin_open choices without inferring terminal, runtime, or cross-format behavior.
• Preserve, merge, inspect, and generate service tty choices without inferring terminal, runtime, or cross-format behavior.
• Preserve, merge, inspect, and generate service privileged choices without inferring security, runtime, or cross-format behavior.
• Preserve, merge, and inspect service attach choices without a default, generated API, logging, runtime, provider, CLI, compatibility, or cross-format behavior.
• Preserve authored and effective service blkio_config scalar spelling and ordered device entries without defaults, controller, runtime, provider, I/O, or cross-format interpretation.
• Preserve authored and effective service cgroup namespace spelling, validity classification, and provenance without defaults, controller, runtime, provider, I/O, or cross-format interpretation.
• Preserve authored and effective raw service cgroup_parent strings with source and merge provenance without path, controller, runtime, provider, or cross-format interpretation.
• Preserve authored and effective service cpu_count YAML integer/string categories and exact spelling without numeric conversion, quota, host, runtime, provider, or cross-format interpretation.
• Preserve authored and effective service cpu_percent YAML integer/string categories, including out-of-range integer evidence, without percentage calculation, CPU, host, runtime, provider, or cross-format interpretation.
• Preserve authored and effective service cpu_period YAML number/string categories without numeric, duration, CPU, host, runtime, provider, or cross-format interpretation.
• Preserve authored and effective service cpu_quota YAML number/string categories without numeric, quota, duration, CPU, host, runtime, provider, or cross-format interpretation.
• Preserve authored and effective service cpu_rt_period YAML number, duration, expression, and other-string categories without CPU, scheduler, host, runtime, provider, or cross-format interpretation.
• Preserve, merge, and inspect service image pull policies and raw pull_refresh_after strings without inventing provider behavior, refresh semantics, or defaults.
• Preserve, merge, inspect, and generate independent service stop signals and raw Compose stop grace periods without normalizing them into another lifecycle manager's units.
• Preserve, merge, inspect, and generate service PID limits without fixed-width parsing, default injection, runtime probing, or conflation with deploy resource limits.
• Preserve, merge, inspect, and safely generate service shared-memory sizes without injecting the Podman default, normalizing provider-dependent values, or inspecting /dev/shm.
• Preserve, merge, inspect, and safely generate service memory limits without fixed-width parsing, provider/runtime enforcement, host/cgroup inspection, or conflation with deploy memory policy.
• Preserve, merge, inspect, and generate service-level tmpfs scalar/list forms, colon-delimited documented or raw options, duplicates, provenance, and sensitivity without conflating volume mounts.
• Preserve, merge, inspect, and safely generate service sysctls mapping/list forms, scalar spelling, order, provenance, and sensitivity without namespace or runtime interpretation.
• Preserve, recursively merge, inspect, and safely generate ordered service ulimits single and soft/hard forms without injecting defaults or claiming runtime enforcement.
• Preserve, merge, inspect, and generate independent ordered service cap_add and cap_drop strings with explicit empty state, exact-case uniqueness, provenance, and no capability whitelist or target normalization.
• Preserve, target-key merge, inspect, and safely generate ordered mixed short/long service devices, including raw CDI/deferred/opaque short forms, explicit empty state, duplicates, nested provenance, and no host-device, permissions, or runtime-access validation.
• Preserve, merge, inspect, and safely generate raw service DNS settings and exposed ports without resolver, network, or runtime access.
• Preserve and safely generate keyed service annotations without losing mapping/list syntax or ambiguous key-only entries.
• Preserve, recursively merge, inspect, and safely generate service logging drivers and ordered string/number/null options without interpreting provider semantics.
• Preserve Build no_cache YAML boolean/string distinctions, interpolation provenance, and recovery without inferring defaults, builder behavior, or cache behavior.
• Preserve Build sbom YAML boolean/string distinctions, interpolation provenance, and recovery without parsing generators, exposing generated SBOM data, or inferring builder behavior.
• Preserve Build privileged literal booleans and deferred expressions through authored and effective views without inferring privilege, platform, runtime, or build behavior.
• Preserve sensitive BuildKit build.ssh mapping/list forms, complete provenance, and redacted inspection without parsing grants or accessing sockets, agents, files, or a builder.
• Preserve opaque Build isolation YAML strings with interpolation, provenance, and recovery without validating modes, platforms, privileges, or builder behavior.
• Preserve raw ordered Build cache_from and cache_to descriptors with source spans, interpolation provenance, and generic sequence merge behavior without interpreting cache types or locations.
• Preserve opaque ordered Build entitlements strings with interpolation, provenance, and recovery without inferring allowlists, privilege state, BuildKit/platform support, execution, or runtime effect.
• Preserve exact Build dockerfile_inline string scalars with source spans, interpolation, provenance, recovery, and conflict diagnostics without parsing Containerfiles or building.
• Preserve Build shm_size through authored and effective views with the same raw scalar, lowercase-unit, zero, deferred-expression, and provider-dependent states as service shm_size, without default, host, allocation, or builder inference.
• Preserve Build ulimits through authored and effective views with the same ordered single and soft/hard forms, scalar spelling, recursive merge, and source evidence as service ulimits, without defaults, normalization, host-limit validation, or builder/runtime inference.
• Preserve Build-specific extra_hosts list/map forms, raw host/address spelling, nested address lists, interpolation provenance, and generic merge evidence without conflating service hosts or performing address validation, DNS/host access, build generation, or conversion.
• Preserve Deploy endpoint_mode, mode, raw replicas scalars, and distinct map/list deployment labels through authored and effective views while retaining malformed, extension, and future-unknown deploy evidence and inferring no count, container, platform, discovery, or runtime behavior.
• Preserve deploy restart-policy members with raw condition, duration, and attempt spellings without service-restart defaults, precedence, simulation, or runtime interpretation.
• Preserve deploy update_config member spelling, malformed evidence, and merge provenance without rollout, scheduling, runtime, or conversion interpretation.
• Preserve distinct deploy rollback_config member spelling, malformed evidence, and merge provenance without rollout, scheduling, runtime, or conversion interpretation.
• Preserve deploy placement constraints, preferences, and max-replicas-per-node spelling through authored and effective views with append/reset/override provenance, malformed recovery, and no scheduling, node-selection, default, runtime, or conversion interpretation.
• Preserve deploy resource-limit CPU number/string, memory string, and PID integer/string spelling, plus reservation CPU number/string and memory string spelling, through authored and effective views with nested merge/reset/override provenance and no service, host, cgroup, runtime, or conversion interpretation.
• Preserve schema-backed reservation generic-resource lists with raw nested kind/value spelling, collection/item/member provenance, and no scheduling, device, runtime, or conversion interpretation.
• Preserve schema-only reservation device lists with raw counts, IDs, map/list options, capabilities, drivers, conflict and malformed evidence, merge provenance, and no device selection, runtime, or conversion interpretation.
• Preserve service credential-spec mappings and raw config/file/registry references through authored and effective views without resolving configurations, files, registries, accounts, platforms, or runtime behavior.
• Preserve raw service extends short references and long service/file mappings through authored and effective views, including provenance and recovery, without expanding referenced services or resolving files, paths, cycles, resources, providers, platforms, runtimes, or conversion behavior.
• Preserve raw service provider mappings with strict-string types, scalar/sequence options, provenance, and recovery without execution, discovery, provider grammar, compatibility, or conversion behavior.
• Preserve ordered service post_start, pre_stop, and pre_start hooks plus raw runtime, pull_refresh_after, and platform strings with provenance and recovery without executing, scheduling, or otherwise interpreting lifecycle, refresh, or OCI behavior.
• Preserve raw service security options and expose conflict-aware lexical candidates without selecting policy, inspecting the host, or claiming runtime behavior.
• Preserve, inspect, and generate ordered service env_file short/long syntax and options; retain interpolation and multi-file provenance without reading environment files.
• 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
• Generated documents
• Phase 2 typed model
• Native coverage
• Roadmap and exact specification gaps
• Testing strategy
• Development environment
• Compose implementation conformance
• Real-world fixture corpus
• Cross-repository implementation plan
• API stability policy
• 0.1.16 release notes — Build, Deploy, source-aware service configuration, and generated network/volume support
• 0.1.15 release notes — DNS, expose, annotations, and security options
• 0.1.14 release notes
• Release process
• Changelog
• 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.