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

Add relative destinations to import declarations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-14 17:24:57 +00:00
parent 49c0c6d908
commit 4635ef08d5
5 changed files with 285 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
docs/config.md
View File

@@ -160,14 +160,21 @@ indexes. Explicit index segments and paths that introduce the reserved
`configkit` or mapping-valued `extends` structure are invalid input options and
produce a structured `LoadError` before source acquisition.
Source-root `configkit.imports` directives are processed before placement, and
each imported application contribution inherits its input's destination,
including transitive imports. A valid destination on `NoSource()` contributes
nothing; an actual empty mapping materializes its destination containers. Once
placed, contributions follow the same strict composition within a tier and
recursive precedence behavior described above. A selected overlay and CLI
overrides remain rooted at the application root and are not moved beneath the
main input's destination.
Source-root `configkit.imports` directives are processed before placement. An
import without an explicit destination inherits the effective destination of
its importing document, including through nested imports. An import may instead
declare a relative destination as a sequence of literal mapping keys; its keys
append to the importing document's effective destination. Omission and `[]`
add no keys. Nested imports continue relative to their immediate importing
document, each declaration is independent of its siblings, and all matches of
one glob receive the same resulting destination. This logical placement does
not change how the physical import path resolves from its declaring file.
A valid destination on `NoSource()` contributes nothing; an actual empty
mapping materializes its destination containers. Once placed, contributions
follow the same strict composition within a tier and recursive precedence
behavior described above. A selected overlay and CLI overrides remain rooted at
the application root and are not moved beneath the main input's destination.
`SourceInfo.Destination` reports the placement for each acquired input source,
including imports. Placement does not change source IDs, acquisition identity,
@@ -778,9 +785,13 @@ zero.
Imports are opt-in. With `Options.Imports` enabled, a document may reserve its root
`configkit` mapping for an `imports` sequence. ConfigKit removes that mapping before
application decoding. Each sequence item is a mapping with exactly one nonempty
string `path` or `glob` plus an optional boolean `optional`; all other shapes and
fields are `import.invalid`. A `configkit` key below the root is invalid. With
imports disabled, any occurrence remains `import.disabled`.
string `path` or `glob`, an optional boolean `optional`, and an optional
`destination` sequence of strings. Every destination string is one literal
mapping key and follows the input-destination validation rules above; quote
numeric-looking keys so YAML reads them as strings. Null, scalar destinations,
and non-string members are `import.invalid`, as are all other unsupported shapes
and fields. A `configkit` key below the root is invalid. With imports disabled,
any occurrence remains `import.disabled`.
The directive key is `configkit`, not the `_configkit` spelling used in v0.1.0.
There is no legacy alias: `_configkit` is ordinary application data, subject to

10
docs/roadmap/implementation.md
View File

@@ -202,7 +202,7 @@ placement survives import-context and imported-parse errors. No limitations.
## Stage 3 — Accept and document the selected YAML syntax
Status: planned. Scope: directive parsing and first complete public behavior.
Status: complete. Scope: directive parsing and first complete public behavior.
1. Parse sequence-of-strings `destination` in `parseImportDeclaration`.
Construct literal keys, normalize with existing destination validation, and
@@ -227,6 +227,14 @@ tests, local links, and everyday check. Done: syntax works across existing
import-capable entry points and acquisition forms, not a silently ignored or
root/path-only subset.
Evidence (2026-10-14): based on `49c0c6d908c0746a0ae49a332691c383ac3ff941`,
using `go1.26.8 linux/amd64`. Engine import/glob/destination tests, root public
destination and mounted-load tests, `TestLocalDocumentationLinks`, and
`./scripts/check.sh` all passed. Coverage includes literal keys, malformed
shapes and members with source-local coordinates, validation before optional
missing/unmatched suppression, and ordinary-root plus mounted layered loads.
No limitations.
## Stage 4 — Verify composition and effective version ownership
Status: planned. Scope: assembly interactions; reuse existing algorithms.