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

Demonstrate source-aware path normalization

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-12 13:21:21 +00:00
parent cc98be8f0a
commit b9e4dfac92
9 changed files with 242 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/consumers/README.md
View File

@@ -56,6 +56,24 @@ validate keys and ranges and convert only at their runtime boundary. Neither sha
needs YAML reserialization, a parser hook, a ConfigKit registry, or a generic subtree
conversion API.
## Source-aware application path policy
[`LoadNotariusPaths`](../../examples/consumers/consumers.go) is the maintained
path-bearing example. Its application resolver uses `Resolution.InputInfo` and
`Resolution.Source` before normalizing: relative CLI input uses an explicitly
supplied invocation directory, retained defaults use the canonical main source,
and a file-authored scalar uses its one declaring source. Absolute paths remain
unchanged. Its executable test covers the matching effective YAML and explanation
history, source-file ownership, and a symlink opened through an alias; canonical
target-file directories, rather than the alias directory or process working
directory, are the selected bases.
The selected example policy leaves a relative value unchanged and emits a warning
when a CLI base is absent or file provenance is missing or composite. That is an
application choice, not a ConfigKit fallback: consumers can instead reject it or
choose another explicit base. The example intentionally performs neither target
existence checks nor confinement checks.
## Intentional migration changes
The examples preserve domain meaning while adopting one configuration convention:

16
docs/roadmap/implementation.md
View File

@@ -218,7 +218,7 @@ remaining Stage 3 risks were identified.
## Stage 4 — Demonstrate source-aware normalization and safe inspection
Status: not started. Dependencies: Stage 3.
Status: complete (2026-09-12). Dependencies: Stage 3.
Scope: maintained Notarius-shaped example code/fixtures, executable examples,
explanation/secret integration tests, and consumer guidance.
@@ -260,6 +260,20 @@ workflows. Filesystem policy stays in the example application, not the root libr
Validation: `go test ./examples/consumers`,
`go test . -run 'Resolution|Explain|Secret|Example'`, then the everyday checker.
Completion record (2026-09-12): added the maintained `NotariusPathConfig` example
and fixtures. Its application-owned resolver uses `InputInfo`/`Source` only: file
values use their exact declaring file, defaults use `source-1`, CLI values use the
explicit invocation directory, and absolute values remain unchanged. Missing CLI
bases or missing/composite file provenance retain the relative value and report an
application warning. Tests prove imported-file, default, CLI, absolute, and canonical
symlink-target bases without changing process CWD; the symlink test explicitly skips
when the platform cannot create it. They also prove effective/explanation agreement,
retained original declaration and reason, sensitive redaction, and that provenance
queries do not re-read a reader source or resolve credentials before normal lookup.
The consumer guide links to the executable artifact. `go test ./examples/consumers`,
`go test . -run 'Resolution|Explain|Secret|Example'`, and `./scripts/check.sh` passed
with Go 1.26.7 on Linux. No deviations or remaining Stage 4 risks were identified.
## Stage 5 — Audit the complete contract and hand off release readiness
Status: not started. Dependencies: Stage 4.