From c98435ce8efc4e140b7ed2c15e33e33b9206dbc7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 12 Sep 2026 17:24:44 +0000 Subject: [PATCH] Restore public API reference documentation --- diagnostic.go | 9 ++++++++- docs/roadmap/remediation.md | 10 ++++++++-- path.go | 12 ++++++++++-- secret.go | 1 + source.go | 8 +++++--- 5 files changed, 32 insertions(+), 8 deletions(-) diff --git a/diagnostic.go b/diagnostic.go index ad02794..9e6ca4f 100644 --- a/diagnostic.go +++ b/diagnostic.go @@ -7,14 +7,18 @@ import ( ) // LoadError reports safe structured diagnostics for a failed configuration load. +// It intentionally does not expose or unwrap parser and application errors. type LoadError struct{ value *engine.LoadError } +// Error implements error without rendering diagnostic messages or input values. func (e *LoadError) Error() string { if e == nil || e.value == nil { return "configkit: configuration load failed" } return e.value.Error() } + +// Diagnostics returns a deep copy of the error's canonical diagnostics. func (e *LoadError) Diagnostics() []Diagnostic { if e == nil || e.value == nil { return nil @@ -29,6 +33,8 @@ func (e *LoadError) Diagnostics() []Diagnostic { } return result } + +// Sources returns a deep copy of sources discovered before loading failed. func (e *LoadError) Sources() []SourceInfo { if e == nil || e.value == nil { return nil @@ -44,7 +50,8 @@ func (e *LoadError) Sources() []SourceInfo { return result } -// WriteDiagnostics writes diagnostics in canonical order. +// WriteDiagnostics writes diagnostics in canonical order. It escapes terminal +// control characters and propagates writer errors, including short writes. func WriteDiagnostics(output io.Writer, diagnostics []Diagnostic) error { return engine.WriteDiagnostics(output, toEngineDiagnostics(diagnostics)) } diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index f8454ed..c92157a 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -2,7 +2,7 @@ Review baseline: `5dc7e18`. Reviewed commits `f81def9` through `5dc7e18` against `eb7de8e`, the agreed [roadmap](public.md), and [implementation plan](implementation.md). -Status: two open findings; F1 and F2 resolved. Review evidence below describes the +Status: one open finding; F1–F3 resolved. Review evidence below describes the original baseline; resolution records describe the subsequent fixes. The previous provenance finding remains resolved; its record is preserved at @@ -108,7 +108,13 @@ the everyday check. ## F3 — Restore consumer contracts on public Go declarations -Priority: medium. Status: open. +Priority: medium. Status: resolved. + +Resolution: restored the baseline comments on root source, path, secret, and +diagnostic declarations. The complete `go doc -all .` output now matches the +pre-refactor `eb7de8e` reference, with no missing declarations or contract prose. +Documentation-link and whitespace checks passed. No behavior or new guarantee +was introduced. ### Evidence and impact diff --git a/path.go b/path.go index 939fbd9..0d0c35b 100644 --- a/path.go +++ b/path.go @@ -5,7 +5,12 @@ import ( ) // Path identifies a configuration value using YAML field names. Its textual form -// is a JSON Pointer. Paths are immutable; the zero value is the root path. +// is a JSON Pointer: the root is empty, ~ escapes as ~0, and / escapes as ~1. +// Paths are semantic rather than filesystem or URL paths: empty, dot, dot-dot, +// percent-containing, and numeric keys retain their literal meaning. Parsed +// numeric tokens are resolved only when traversal knows their containing type. +// +// Paths are immutable. The zero value is the root path. type Path struct { value engine.Path } @@ -13,7 +18,9 @@ type Path struct { // Keys constructs a path of mapping keys. Keys with no arguments returns the root path. func Keys(keys ...string) Path { return Path{value: engine.Keys(keys...)} } -// ParsePath parses a JSON Pointer while preserving context-dependent numeric tokens. +// ParsePath parses a JSON Pointer. Numeric tokens remain unresolved until schema +// or document traversal determines whether the containing value is a mapping or +// sequence. func ParsePath(pointer string) (Path, error) { value, err := engine.ParsePath(pointer) return Path{value: value}, err @@ -23,6 +30,7 @@ func ParsePath(pointer string) (Path, error) { func (p Path) Key(key string) Path { return Path{value: p.value.Key(key)} } // Index returns a new path with index appended as a sequence-index segment. +// A negative index produces an invalid path that configuration operations reject. func (p Path) Index(index int) Path { return Path{value: p.value.Index(index)} } // String returns the path's canonical JSON Pointer spelling. diff --git a/secret.go b/secret.go index 6a033de..82ed76a 100644 --- a/secret.go +++ b/secret.go @@ -18,6 +18,7 @@ type Secret struct { } // SecretEnv constructs an unresolved environment-backed secret reference. +// Invalid names are reported if the reference survives a configuration load. func SecretEnv(name string) Secret { return Secret{name: name, specified: true} } // EnvName returns the public environment-variable name. diff --git a/source.go b/source.go index 154edff..abf1467 100644 --- a/source.go +++ b/source.go @@ -13,13 +13,15 @@ type Source struct{ value engine.Source } // File returns a source that reopens path for every load attempt. func File(path string) Source { return Source{value: engine.File(path)} } -// Bytes snapshots data immediately. +// Bytes snapshots data immediately. Label must be nonempty and safe to display; +// constructor problems are reported when the source is consumed. func Bytes(label string, data []byte) Source { return Source{value: engine.Bytes(label, data)} } -// Reader returns a single-use source. Copies share the same single-use claim. +// Reader returns a single-use source. ConfigKit consumes input but never closes it. +// Copies of the returned Source share the same single-use claim. func Reader(label string, input io.Reader) Source { return Source{value: engine.Reader(label, input)} } -// NoSource explicitly selects defaults-only input. +// NoSource explicitly selects a defaults-only input. It creates no source record. func NoSource() Source { return Source{value: engine.NoSource()} } func (s Source) toEngine() engine.Source { return s.value }