Files
configkit/docs/roadmap/remediation.md

7.9 KiB
Raw Blame History

Result value and focused inspection review

Reviewed implementation: 7a9ce01 (against planning baseline b3799be). Scope: the nine stages of implementation.md, the settled result-value roadmap, and accepted ADR 0024.

No implementation changes were made during this review. Both findings below remain open.

1. Terminal availability still depends on recursive schema validity

Priority: P2. Status: Open. Plan stages: 1–2.

Relevant code: ResultValue, especially its descriptor construction at line 33; the recursive map/slice/array and struct branches of schemaBuilder.describe.

The roadmap requires a reached terminal to be returned as its actual current Go value without conversion or revalidation. This applies to manually constructed results and post-load changes. Unsupported shapes matter when navigation must continue through them, not simply when returning them.

Before selecting a map entry or sequence element, ResultValue describes its entire static type, including its element type. Struct description recursively describes ordinary child types too. Lookup mode makes unsupported primitive/codec types opaque leaves, but errors such as ambiguous fields, malformed tags, or invalid inline declarations still propagate from a descendant. Consequently an otherwise ordinary map lookup can fail because the terminal's internal schema is invalid. An unrelated descendant can also prevent lookup of an available sibling value.

For example, this disposable public-API probe returned (nil, false):

type Terminal struct {
    A int `yaml:"same"`
    B int `yaml:"same"`
}
r := &configkit.Result[map[string]Terminal]{
    Config: map[string]Terminal{"item": {A: 1, B: 2}},
}
value, found := r.Value(configkit.Keys("item"))

Expected: Terminal{A: 1, B: 2} and true. No binding inside Terminal is needed to select or return the existing map entry. Continuing into that ambiguous struct may legitimately fail. The same probe with a dynamic outer struct having an ordinary child Terminal field and a good int field returned false for both /dynamic/child and /dynamic/good. These are not inputs that Load must accept; they exercise the expressly supported current-value and hand-built-result boundary.

Impact: the implementation adds a recursive schema-validity prerequisite to value availability beyond the selected contract. Existing load validation is not at issue. The current channel-terminal test passes because lookup mode suppresses only selected schema errors; it does not protect this broader terminal case.

Remediation: make current-value navigation require only the containing shape and bindings needed for each step. Collection membership/bounds checks should not require the terminal element's descriptor. Reuse struct binding rules while keeping ordinary child types opaque until navigation actually continues into them; retain necessary validation of the current container's own field bindings and inline flattening. Do not fix this by accepting ambiguous bindings during continued navigation or weakening Load's schema checks. Add focused public regressions for terminal invalid-binding structs in a collection and beneath a dynamic container, including an available sibling. Existing valid-load and unsupported-navigation behavior must remain unchanged.

2. The exported Value documentation omits essential settled semantics

Priority: P3. Status: Open. Plan stage: 9.

Relevant documentation: the declaration comment in result_value.go, with the existing configuration ownership contract and schema binding rules as supporting owners.

The comment documents current values, trusted access, aliasing and frozen inspection, but does not explain several consequential API choices: the root selects Config, a present nil value succeeds, a terminal pointer retains its type, intermediate nils prevent further navigation, and manually constructed results work without load evidence. It also supplies no reference to the shared YAML-name, inline-field and scalar-leaf navigation rules. The configuration reference adds some of these facts, but still does not establish the full lookup contract. Important details currently remain primarily in the soon-to-be-retired roadmap.

Impact: consumers cannot reliably distinguish unavailable paths from present nil values or learn terminal-pointer and field-navigation behavior from the public API documentation. This is a documentation gap rather than evidence of a second runtime defect.

Remediation: complete the Value declaration comment with the root, nil, terminal-pointer, manual-result, and no-conversion/no-revalidation behavior. Reference shared schema/path rules rather than reproducing their complete tables. State that scalar descriptors remain leaves and lookup does not run codecs. Keep ordinary Go typed-nil behavior explicit where needed; do not promise deep copies, frozen execution settings or concurrent mutation safety. Align the wording with finding 1's corrected implementation, without redefining the intended contract.

Stage-by-stage disposition

Stage Review result
1 — Private current-value navigation Finding 1. Descriptor/field/path reuse, nil-safe field access, operation-local state and pointer-loop handling otherwise follow the plan.
2 — Public Value and tests Finding 1 is not covered by the existing terminal tests. Current values, named types, ordinary assignment, nil availability and trusted Secret access otherwise follow the selected design.
3 — View and canonical scope No additional finding. Canonical normalization plus existing token-spelling containment implements reporting scope; explicit queries and catalogs remain unfiltered.
4 — Focused rendering No additional finding. Frozen document selection preserves native-path ancestor sensitivity, absent/null distinctions and writer failure behavior.
5 — View comparison No additional finding. Complete original snapshots use existing paired redaction and atomic difference regions before scope filtering; cross-root-type comparison follows ADR 0024.
6 — History/provenance/ownership integration No additional finding. Tests exercise removed paths, numeric shape changes, source contexts through placement/inheritance, detached query records and frozen reports after Config mutation.
7 — One-library example No additional finding. One load, typed registration, owned settings capture, effective resource context and a library inspection facade are demonstrated.
8 — Two-library example No additional finding. Application and component callbacks/identities compose explicitly; tests cover preserved false input, repeated loads, validation and inherited resource context.
9 — Documentation and validation Finding 2. Architecture comparison wording, consumer navigation and implementation inventory reflect the accepted model.

Validation and limits

Using the locally installed Go 1.27.4 toolchain with GOTOOLCHAIN=local, GOPROXY=off and GOTELEMETRY=off:

  • ./scripts/check.sh passed: formatting, whitespace, full tests, vet and build.
  • go test -race ./... passed, including engine and consumer examples.
  • A disposable program outside the repository reproduced finding 1 through the public API; no new repository tests or production changes were introduced.
  • Local Markdown file targets and heading anchors were checked across the changed documentation; all 441 checked local links resolved.

No other required correctness, architecture, or strengthened-contract finding was identified. This review does not claim real downstream adoption, concurrent mutation support, narrower subtree diff cost, or a release/publication check.