diff --git a/docs/adr/0011-input-destinations.md b/docs/adr/0011-input-destinations.md index 6476da4..06860f4 100644 --- a/docs/adr/0011-input-destinations.md +++ b/docs/adr/0011-input-destinations.md @@ -3,8 +3,11 @@ ## Status Accepted. The [input-destinations roadmap](../roadmap/input-destinations.md) -owns implementation status. The completed implementation plan and evidence are -preserved at `315f464:docs/roadmap/implementation.md` in Git history. +owns implementation status for input placement. The accepted relative-import +extension is recorded in [ADR 0012](0012-relative-import-destinations.md), with +delivery status in its implementation plan. The completed implementation plan +and evidence are preserved at `315f464:docs/roadmap/implementation.md` in Git +history. ## Date diff --git a/docs/adr/0012-relative-import-destinations.md b/docs/adr/0012-relative-import-destinations.md new file mode 100644 index 0000000..d1f4fe8 --- /dev/null +++ b/docs/adr/0012-relative-import-destinations.md @@ -0,0 +1,76 @@ +# ADR 0012: Place Imported Configuration at Relative Destinations + +## Status + +Accepted. The [relative-import destinations roadmap](../roadmap/relative-import-destinations.md) +owns the approved public behavior; the implementation plan records delivery +status and evidence. + +## Date + +2026-10-14 + +## Context + +ConfigKit can place an input document at a literal mapping path while retaining +source identity, composition, and inspection in its normal loading lifecycle. +An importing document can currently bring in other documents, but those +contributions inherit only the importing input's destination. Consumers that +assemble a collection therefore cannot declare the layout of imported +fragments alongside the import itself without rewriting source documents or +performing another merge outside ConfigKit. + +The extension should reuse input placement and the existing import lifecycle. +Logical application placement must remain independent from physical path +resolution, source identity, precedence, and resource ownership. + +## Decision + +Add an optional `destination` field to each YAML import declaration. Its value +is a sequence of strings representing literal mapping-key segments. Omission +and an empty sequence add no segments. A non-empty destination appends to the +effective destination of the immediately importing document; nested imports +continue from the resulting child destination. Every match of one glob +declaration receives the same computed destination. + +Use the existing input-destination validation and reserved-key rules. Do not +interpret destination segments as filesystem paths, separators, sequence +indices, or root-reset instructions. Physical import paths continue to resolve +from their declaring source under existing containment rules. + +Imports remain in their existing strict-composition group. A destination does +not grant precedence, bypass cycle or repeated-source rules, or change source +identity. Existing placement, version ownership, source records, diagnostics, +resource contexts, inheritance, history, and inspection mechanisms continue to +govern the placed contributions. No public Go entry point or independent +specification-header behavior is introduced. + +This is additive YAML functionality and is minor-release work. Version +selection, release notes, roadmap retirement, and publication remain separate +release-preparation work. + +## Alternatives Considered + +- **Require complete application-root destinations on every import.** This + avoids inherited context but repeats collection prefixes in nested source + declarations and does not express placement relative to the importing + document. +- **Encode destinations as dotted or slash-delimited strings.** This introduces + separator and escaping rules even though existing paths already represent + literal mapping keys as segments. +- **Rewrite or merge imported documents in consumers.** This duplicates source + placement, strict composition, attribution, and inspection behavior outside + ConfigKit's loading lifecycle. +- **Add independent specification headers or collection-specific validation.** + These are separate design questions and are not required to declare relative + placement. + +## Consequences + +Import declarations can describe the logical placement of their contributions +while preserving the physical source and existing composition lifecycle. +Placement is immediate-parent-relative, so nested imports accumulate their +declared segments and sibling declarations remain independent. The feature is +implemented behind the existing public loading surface; detailed validation, +diagnostic, accounting, and inspection requirements are tracked by the +implementation roadmap. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 9fe8bc2..cc1bf06 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,7 +1,7 @@ # Implement relative import destinations -Status: planned. Execute Stage 1 through Stage 9 in order, one focused stage per -Luna implementation prompt. The +Status: in progress. Execute Stage 1 through Stage 9 in order, one focused stage +per Luna implementation prompt. The [feature roadmap](relative-import-destinations.md) owns the approved target and syntax; this document owns implementation decisions, sequencing, and evidence. @@ -130,7 +130,7 @@ also proposes independent specification headers, which are outside this plan. ## Stage 1 — Capture the baseline and record the extension -Status: planned. Scope: baseline evidence and one ADR; no production code. +Status: complete. Scope: baseline evidence and one ADR; no production code. 1. Read the feature roadmap, relative-import request/acceptance rows, applicable policies, ADR 0011, and the owner map below. Confirm the worktree and baseline. @@ -152,6 +152,21 @@ Status: planned. Scope: baseline evidence and one ADR; no production code. Validate: whitespace and local-documentation-link checks. Done: baseline and decision are recorded; implemented behavior is unchanged. +Baseline evidence (2026-10-14): revision `934c1022e038115475c1d33dd85216855b8be522` +on `main`; the worktree was clean and four commits ahead of `origin/main`. +Local toolchain: `go1.26.8 linux/amd64`. `./scripts/check.sh` passed, including +format/whitespace checks, all Go tests, vet, build, examples, local links, and +package-boundary checks. No environmental limitations. Existing coverage is +centered in `internal/engine/parse_test.go`, `imports_test.go`, `glob_test.go`, +`native_filesystem_test.go`, `version_path_test.go`, and the `destination_*_test.go` +files; public/lifecycle coverage includes `facade_destination_test.go`, +`facade_layered_test.go`, `facade_version_test.go`, +`facade_resource_context_test.go`, `facade_inheritance_test.go`, and +`facade_diff_test.go`, with engine resource and history coverage in +`resource_context_test.go` and `inheritance_history_test.go`. + +Done: baseline and decision are recorded; implemented behavior is unchanged. + ## Stage 2 — Refactor traversal to explicit per-document placement Status: planned. Scope: private context plumbing; old syntax remains unchanged.