Record relative import destination decision and baseline
This commit is contained in:
@@ -3,8 +3,11 @@
|
|||||||
## Status
|
## Status
|
||||||
|
|
||||||
Accepted. The [input-destinations roadmap](../roadmap/input-destinations.md)
|
Accepted. The [input-destinations roadmap](../roadmap/input-destinations.md)
|
||||||
owns implementation status. The completed implementation plan and evidence are
|
owns implementation status for input placement. The accepted relative-import
|
||||||
preserved at `315f464:docs/roadmap/implementation.md` in Git history.
|
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
|
## Date
|
||||||
|
|
||||||
|
|||||||
76
docs/adr/0012-relative-import-destinations.md
Normal file
76
docs/adr/0012-relative-import-destinations.md
Normal file
@@ -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.
|
||||||
@@ -1,7 +1,7 @@
|
|||||||
# Implement relative import destinations
|
# Implement relative import destinations
|
||||||
|
|
||||||
Status: planned. Execute Stage 1 through Stage 9 in order, one focused stage per
|
Status: in progress. Execute Stage 1 through Stage 9 in order, one focused stage
|
||||||
Luna implementation prompt. The
|
per Luna implementation prompt. The
|
||||||
[feature roadmap](relative-import-destinations.md) owns the approved target and
|
[feature roadmap](relative-import-destinations.md) owns the approved target and
|
||||||
syntax; this document owns implementation decisions, sequencing, and evidence.
|
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
|
## 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
|
1. Read the feature roadmap, relative-import request/acceptance rows, applicable
|
||||||
policies, ADR 0011, and the owner map below. Confirm the worktree and baseline.
|
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
|
Validate: whitespace and local-documentation-link checks. Done: baseline and
|
||||||
decision are recorded; implemented behavior is unchanged.
|
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
|
## Stage 2 — Refactor traversal to explicit per-document placement
|
||||||
|
|
||||||
Status: planned. Scope: private context plumbing; old syntax remains unchanged.
|
Status: planned. Scope: private context plumbing; old syntax remains unchanged.
|
||||||
|
|||||||
Reference in New Issue
Block a user