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

Settle relative import destination syntax

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-14 16:44:11 +00:00
parent edb6d05ec1
commit b2db3233b2
1 changed files with 18 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -14,7 +14,7 @@ effective destination, then processes the imported application content through
the existing placement and loading lifecycle. Applications continue to select the existing placement and loading lifecycle. Applications continue to select
entry sources, input destinations, filesystem contexts, and precedence tiers. entry sources, input destinations, filesystem contexts, and precedence tiers.
Proposed syntax, pending the syntax decision below: Selected YAML syntax:
```yaml ```yaml
configkit: configkit:
@@ -43,6 +43,9 @@ The feature must preserve these requested and existing behaviors:
- Omission and an empty destination list retain the importing document's - Omission and an empty destination list retain the importing document's
destination. Each glob match receives the same relative placement. Transitive destination. Each glob match receives the same relative placement. Transitive
imports accumulate destinations from their immediate parents. imports accumulate destinations from their immediate parents.
- An explicit `destination` is a sequence of strings. Null, scalar values, and
non-string members are invalid directive shapes; values are not coerced.
For a numeric-looking key, use a string such as `destination: ["0"]`.
- Segments are mapping keys under the existing `Input.Destination` rules. Dots, - Segments are mapping keys under the existing `Input.Destination` rules. Dots,
slashes, and numeric-looking text within a key are literal. There is no slashes, and numeric-looking text within a key are literal. There is no
filesystem-style normalization, parent traversal, or application-root reset. filesystem-style normalization, parent traversal, or application-root reset.
@@ -113,10 +116,11 @@ placement and assembly rather than introduce a second merge or validation model.
## Ordered implementation plan ## Ordered implementation plan
### 1. Select syntax and document the semantic extension ### 1. Document the selected syntax and semantic extension
Resolve the Open Decision below and specify valid shapes, literal key handling, Use the Selected Design Decision below to specify valid shapes, literal key
and structured failures. Preserve existing `path`/`glob` and `optional` behavior. handling, and structured failures. Preserve existing `path`/`glob` and `optional`
behavior.
Validate declared destination syntax even when an optional import has no match; Validate declared destination syntax even when an optional import has no match;
optionality suppresses missing input, not malformed directives. optionality suppresses missing input, not malformed directives.
@@ -209,23 +213,17 @@ passes, and implemented documentation matches the behavior. Source specification
headers can then be reconsidered as a separate feature; their implementation is headers can then be reconsidered as a separate feature; their implementation is
not required to complete this roadmap. not required to complete this roadmap.
## Open Decisions ## Selected Design Decision
### YAML destination representation ### YAML destination representation
Recommendation: adopt `destination` as a sequence of strings, for example Use `destination` as a sequence of strings, for example
`destination: [prompts, "0"]`. Omission and `[]` inherit placement. Treat null, `destination: [prompts, "0"]`. Omission and `[]` inherit placement. Null, scalar
scalar destinations, and non-string members as invalid shapes rather than destinations, and non-string members are invalid shapes rather than values to
coercing them. Permit every string key allowed by existing destination rules, coerce. Every string key allowed by existing destination rules remains valid,
including the empty string. This directly expresses literal segments, matches including the empty string.
the request's example, and keeps numeric key text distinct from YAML numbers.
These shape choices are proposed syntax, not pre-existing restrictions.
Alternative: also accept a scalar JSON-pointer representation using existing This representation directly expresses literal segments and keeps numeric key
`ParsePath` conventions, while retaining the sequence form. This is viable and text distinct from YAML numbers. It provides one explicit notation consistent
may be convenient for users already familiar with public paths, but introduces with the existing mapping-destination model. These shape rules define the new
two spellings and escaping rules for one operation. A leading slash would still directive syntax; other configuration values retain their existing semantics.
describe relative segments, not reset to the application root, which could be
surprising. Prefer the sequence-only form unless consumer evidence justifies
the additional notation. A null-as-inherit shorthand is also viable but adds a
third spelling for behavior already covered by omission and an empty list.