91 lines
5.8 KiB
Markdown
91 lines
5.8 KiB
Markdown
# Internal Component Overview
|
|
|
|
ConfigKit exposes the root `configkit` package and keeps its document and YAML
|
|
representations private. The implemented components and their owners are:
|
|
|
|
- immutable semantic `Path` construction and strict JSON Pointer parsing;
|
|
- detached effective presence/origin and chronological history queries in
|
|
`metadata.go`, with provenance and diagnostic record types;
|
|
- canonical, control-safe diagnostic rendering and structured `LoadError` access;
|
|
- opaque file, byte, reader, and no-input source construction in `source.go`,
|
|
with shared regular-file checks and bounded read mechanics in `source_file.go`;
|
|
- a parser-independent ordered tree in `internal/document`, with root-private
|
|
semantic lookup, indexing, and value traversal in `document_walk.go`;
|
|
- the sole upstream YAML integration in `internal/yaml`, which translates validated
|
|
input into that owned tree and exposes no parser types outside its boundary;
|
|
`parse.go` owns shared translation into detached, ordered public diagnostics;
|
|
- a private strict composer in `compose.go` that joins only disjoint document-tree
|
|
definitions, retains ordered claims and composite mapping origins, reports every
|
|
conflicting location, and never aliases an input tree;
|
|
- fixed selected-profile loading in `profile.go` and recursive, non-aliasing overlay
|
|
with displacement records in `overlay.go`; overlay records retain origins,
|
|
while value explanation uses separate history applications;
|
|
- CLI override validation/preparation in `override.go`, parser-neutral values in
|
|
`override_value.go`, and synthetic-source application in `override_apply.go`,
|
|
sharing overlay, source, byte, node, and depth policies;
|
|
- a per-operation private reflection descriptor graph in `schema.go` for supported
|
|
types, YAML field binding, inlining, secret tags, recursion, and semantic paths;
|
|
- descriptor-driven canonical projection in `projection.go`, detached typed
|
|
cloning with explicit secret-state modes in `clone.go`, shared reflection and
|
|
cycle/limit state in `value_operation.go`, and configuration-value comparison
|
|
in `document_compare.go`; validation separately audits sensitivity and secrets;
|
|
- strict schema-driven decoding over detached defaults in `decode.go`, including
|
|
mapping/sequence semantics, null and numeric policy, safe codec errors, presence,
|
|
baseline/final trees, and initial default/input origins;
|
|
- public lifecycle coordination in `load.go`, option selection in `options.go`,
|
|
input assembly in `load_input.go`, typed phases/publication in `load_result.go`,
|
|
bounded canonical import DFS in `imports.go`, filesystem context/containment in
|
|
`filesystem.go`, directive parsing/restrictions in `directives.go`,
|
|
pattern-directed glob expansion in `glob.go`, schema-version checking and report
|
|
contexts in `validation.go`, and layered metadata/history assembly in
|
|
`load_metadata.go`;
|
|
- recorded application defaulting and normalization in `resolution.go`, including
|
|
callback-scoped fixed entry metadata/source queries, explicitness queries, helper
|
|
verification, structural mutation audit, coalesced intent, private before/after
|
|
snapshots, and resolution metadata integration;
|
|
- post-resolution schema-aware report collection and validator mutation detection in
|
|
`validation.go`, completing the public callback lifecycle after composed input;
|
|
- opaque typed environment references and per-load name resolution in
|
|
`secret_reference.go`, including credential-free projection/cloning and private
|
|
validator-state auditing;
|
|
- explicit bounded startup environment bootstrap and safe partial reporting in
|
|
`secrets.go`;
|
|
- fixed-point tag/predicate/dependency sensitivity classification in `secret.go`;
|
|
- canonical effective output in `render.go`, using frozen-snapshot redaction
|
|
shared with explanation in `snapshot.go`;
|
|
- detached public explanation records and coordination in `explain.go`, immutable
|
|
input applications/replay and retained-node budgeting in `history.go`, shared
|
|
safe snapshot projection in `snapshot.go`, and deterministic human output in
|
|
`explain_render.go`; the only upstream dumper integration remains isolated in
|
|
`internal/yaml/write.go`;
|
|
- a separate maintained `examples/consumers` package with four sanitized consumer
|
|
shapes, fixtures, domain validators, and runtime-boundary functions; and
|
|
- an everyday single-toolchain check in `scripts/check.sh` and a stricter
|
|
source-candidate checker in `scripts/release-check.sh`, with local
|
|
documentation-link and public import-boundary gates owned by root-package tests.
|
|
|
|
Dependency direction remains inward: the public lifecycle coordinates private
|
|
source, document, schema, and inspection helpers. Semantic paths stay in the root
|
|
package; `internal/document` owns only representation and cloning and never imports
|
|
the root package. Only `internal/yaml` imports the upstream YAML package. Maintained
|
|
consumer examples use the public package and standard library.
|
|
|
|
The [configuration contract](../config.md) owns implemented input, schema, decoding,
|
|
loading lifecycle, path imports, composition, profile/CLI overlay, version checking,
|
|
recorded resolution, typed secret references/bootstrap, semantic validation,
|
|
metadata, secret classification, redacted effective rendering, historical
|
|
explanation, and ownership behavior.
|
|
The [consumer adoption guide](../consumers/README.md) owns current application-fit
|
|
and migration guidance.
|
|
|
|
The source-extraction inventory records the application foundations used by the
|
|
implementation:
|
|
|
|
- [Extraction inventory](extraction.md)
|
|
|
|
The [architecture policy](../policy/architecture.md) owns binding boundaries and
|
|
invariants. The [deferred scope](../roadmap/deferred.md) records deliberate
|
|
exclusions. See the
|
|
[development guide](../development.md) for contributor orientation and validation
|
|
and the [release procedure](../release.md) for source-candidate gates.
|