eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan relative import destination implementation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-14 16:53:50 +00:00
parent b2db3233b2
commit 7248a8bd95
6 changed files with 537 additions and 668 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
docs/roadmap/relative-import-destinations.md
View File

@@ -1,10 +1,11 @@
# Relative Import Destinations Roadmap
Status: planned; implementation has not started. Execute the stages below in
order. This roadmap addresses only the relative-import-destination addition in
Status: planned; syntax selected and implementation has not started. The
[implementation plan](implementation.md) owns sequencing and completion evidence.
This roadmap addresses only the relative-import-destination addition in
the [PromptKit request](promptkit-feature-request.md#requested-addition-relative-import-destinations).
Independent source specification headers are deferred for reconsideration after
this work is implemented; they are not a prerequisite or part of these stages.
this work is implemented; they are not a prerequisite or part of this feature.
## Targeted end state
@@ -114,105 +115,6 @@ Reviewed baseline: `315f464`, with input destinations implemented. The
The change extends traversal and directive parsing. It should reuse existing
placement and assembly rather than introduce a second merge or validation model.
## Ordered implementation plan
### 1. Document the selected syntax and semantic extension
Use the Selected Design Decision below to specify valid shapes, literal key
handling, and structured failures. Preserve existing `path`/`glob` and `optional`
behavior.
Validate declared destination syntax even when an optional import has no match;
optionality suppresses missing input, not malformed directives.
Record the extension to ADR 0011's inherited-destination model in a new ADR
without rewriting the accepted decision. Distinguish the new declarative syntax
from unchanged input placement and version ownership. Review compatibility
under the release policy without choosing or publishing a release in this work.
Completion: the syntax and parent-relative semantics are explicit, with source
specification headers still deferred and no additional merge or namespace rules.
### 2. Parse destinations and carry effective placement through traversal
Extend private import declarations and parser validation with the selected
relative destination representation and useful declaration locations. Reuse
existing key validation rather than maintaining a competing path convention.
Compute each child's effective destination from the immediate parent's placement.
Pass that context through path imports, glob expansion, and recursive traversal.
Explicit per-call state is a straightforward implementation option; the public
contract need not prescribe a parameter, stack, or allocation layout. Ensure
nested placement cannot leak into siblings, subsequent glob matches, or inputs.
Use the resulting destination when placing the body, checking effective version
claims, accounting for limits, and creating source records. Remove or narrow
uniform post-traversal source-destination assignment. Retain original physical
identity and resource contexts; do not include destination in repetition keys.
Completion: nested and sibling imports, glob matches, and source records all use
the right effective destination, with structured errors and existing bounds.
### 3. Verify integration with assembly and inspection
Check that placed source applications feed existing strict composition, tier
precedence, inheritance, and final typed loading. Confirm conflicts report the
effective path and contributing physical locations, including imports that
collide with explicitly wrapped input or a destination ancestor.
Verify protected version claims after destination accumulation, and ordinary
version payload away from the protected path. Confirm history, sensitivity,
rendering, and diffs use placed data without reconstructing placement in callers.
Exercise inherited and surviving lower-tier resource references through existing
source-context APIs. Preserve detached source records and existing failure
behavior; do not add promises about collecting every error or exact failure
ordering merely to simplify tests.
Completion: imports with explicit destinations agree with equivalent existing
placement for application behavior, while actual source attribution stays intact.
### 4. Add acceptance coverage and consumer guidance
Use parser tests for declaration shape, engine tests for traversal and placement,
and public tests/examples for complete consumer workflows. Reuse existing tests
where they already protect unchanged behavior. Cover the following distinct risks:
| Scenario | Evidence required |
| --- | --- |
| Omitted destination and `[]` | Existing inherited placement, including root imports |
| Entry, child, and grandchild destinations | Placement accumulates from the immediate importer |
| Nested import followed by a sibling; multiple glob matches | Child state does not leak to peers |
| Literal slash, dot, numeric-looking, and empty keys | Existing mapping-key meaning is preserved |
| Invalid shapes and reserved keys, including optional unmatched imports | Structured directive failure with a real declaration location |
| Disjoint, overlapping, and ancestor-related destinations | Existing composition conflicts and tier precedence |
| Same physical source selected at different destinations in a group | Existing repetition/cycle policy is retained |
| Mounted import targeting a protected version path | Existing ownership checks use the accumulated path |
| Ordinary version payload elsewhere | No new checking, coercion, or consumption |
| Inheritance, overrides, and resource-relative fields | Effective paths and original resource bases agree |
| History, classified values, and diffs | Existing provenance and disclosure rules remain effective |
| Accumulated depth, wrapper nodes, empty bodies, and absent optional sources | Existing accounting and contribution behavior |
| Host/native filesystem imports and supported entry source forms | Placement is independent of acquisition kind |
| Public source inspection and load failures | Accurate effective destinations and detached records |
Add an executable collection-entry example that imports metadata and mounts
prompt/profile fragments. It must use no source header checker or consumer-side
parsing, merging, or provenance reconstruction. Demonstrate ordinary root loading
as well as a representative layered mounted entry without duplicating all cases.
Update the owning configuration contract and consumer guide as behavior lands;
update source-record declaration documentation and internal overview only where
their descriptions change. Keep the header proposal deferred for later review.
Run focused tests, then the everyday check and appropriate ownership race checks
from the [development guide](../development.md), following the
[testing policy](../policy/testing.md). Validate documentation links. No independent
performance benchmarks are part of this roadmap.
Completion: the relative-import acceptance scenarios in the PromptKit request
are covered, the combined workflow works without source headers, validation
passes, and implemented documentation matches the behavior. Source specification
headers can then be reconsidered as a separate feature; their implementation is
not required to complete this roadmap.
## Selected Design Decision
### YAML destination representation