Expose input destinations through the public facade

This commit is contained in:
2026-10-14 13:56:22 +00:00
parent 751787ec24
commit 53601e68ed
7 changed files with 429 additions and 16 deletions

View File

@@ -149,6 +149,33 @@ have index zero. Explicit empty groups and `NoSource` consume no source ID.
Byte, source, node, and glob-entry budgets are shared across the load, while
the existing per-source and import-depth bounds still apply.
#### Input destinations
`Input.Destination` places the source's application mapping beneath a path
relative to the configuration root. Its zero or empty value means root, so
existing inputs keep their behavior. Main inputs and underlay inputs use the
same destination model. Destination segments are literal mapping keys: dots,
slashes, and numeric-looking text are not split or interpreted as sequence
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.
`SourceInfo.Destination` reports the placement for each acquired input source,
including imports. Placement does not change source IDs, acquisition identity,
physical source locations, or passive resource contexts. Introduced ancestor
mappings use the contributing document's root location as a source fallback;
authored content retains its original source coordinates. Returned source
records are detached copies.
The maintained [layered consumer example](consumers/README.md#native-filesystem-and-layered-input)
shows a main host file, two underlay tiers, embedded defaults, a mapping source,
and explicit resource access without a second configuration pass.

View File

@@ -423,7 +423,7 @@ pass.
## Stage 10 — Expose the root-owned facade and public acceptance tests
Status: planned. Scope: the two public fields and complete consumer behavior.
Status: complete. Scope: the two public fields and complete consumer behavior.
1. Add `Input.Destination Path` and `SourceInfo.Destination Path` to root types.
Extend `toEngineInput`, `fromEngineSourceInfo`, `toEngineSourceInfo`, and all
@@ -443,9 +443,25 @@ Status: planned. Scope: the two public fields and complete consumer behavior.
matrices; public tests demonstrate supported integration rather than every
private branch. Confirm failed loads expose detached source destinations.
Validate: `go test . -run 'Destination|Facade|PublicFacadeBoundary|DependencyImportBoundary'`,
`go test -race ./...`, and everyday check. Done: the requested workflow is usable
entirely through ConfigKit's supported import path and documented surface.
Validated with `go test . -run 'Destination|FacadeLayered|PublicFacadeBoundary|DependencyImportBoundary' -count=1`,
`go test -race ./...`, and `./scripts/check.sh` (go1.26.8 linux/amd64); all
passed.
`TestFacadeInputDestinationsAcrossSourceKinds` exercises host, native
filesystem, bytes, reader, and mapping inputs with literal escaped and
numeric-looking mapping keys. `TestFacadeDestinationRootEmptyMappingNoSourceAndInvalidPaths`
covers omitted/empty root placement, empty mapping presence, absent `NoSource`,
invalid index/reserved destinations, and reader preflight. `TestFacadeImportedSourcesRetainInputDestination`
checks public transitive import placement. `TestFacadeMountedMainAndUnderlayInspectionResourcesAndDiff`
ties mounted main/underlay values to metadata, both source destinations, callback
source context, relative-resource access during and after loading, history, safe
effective/explanation rendering, and bilateral diff redaction; it also mutates
returned records and confirms later queries and comparisons remain unchanged.
`TestFacadeFailedLoadExposesDetachedSourceDestination` verifies failure records,
and `TestSourceInfoDestinationConversionsAndCopies` covers root/engine source
record conversion. Existing public-boundary tests pass with the new root-owned
fields. Done: destination selection and inspection are available through the
supported ConfigKit import path.
## Stage 11 — Add maintained simple and collection-style consumer examples