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

Consolidate refactoring roadmaps and record open questions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-24 22:04:26 +00:00
parent fbaaaf18cd
commit 26771dc03e
4 changed files with 176 additions and 537 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
docs/roadmap/consolidation.md
View File

@@ -2,7 +2,8 @@
Status: proposed scope and target state for review. This document recommends
refactors; it does not record implementation progress or authorize a release.
Prepare the staged implementation plan after reviewing this roadmap.
Prepare the staged implementation plan after reviewing this roadmap and settling
the [open questions](#open-questions).
## Purpose
@@ -20,13 +21,22 @@ unused reverse inspection conversions. No public signature or configuration
semantic change is currently recommended. This is an assessment of the reviewed
consumer workflows, not a requirement to preserve every beta API in perpetuity.
## Evidence And Relationship To Existing Work
## Evidence And Baseline
Reviewed worktree: `c9574ef`, immediately after the `v0.10.0` release at `5959537`.
The inputs are the earlier [complexity roadmap](complexity.md), whose reviewed
baseline predates discovery, and the new [complexity audit](remediation.md).
The older roadmap already acknowledges implemented discovery, but its selected
work is narrower than this proposal.
This document replaces the earlier `complexity.md` roadmap and `remediation.md`
audit record. Their recommendations and relevant evidence are incorporated here;
the original documents remain available in Git history:
```sh
git show fbaaaf1:docs/roadmap/complexity.md
git show fbaaaf1:docs/roadmap/remediation.md
```
The earlier roadmap reviewed `7a83704f43ef9870db33661231cdff5d6ee502f7`, before
discovery. The audit reviewed `5959537d1adc2516e7f7e8881df72b707ec48c3f`, including
implemented discovery. The consolidation review checked their recommendations
against that newer baseline and also considered the public API.
This review inspected the current public load/input/discovery declarations and
maintained consumer examples, the shared request executor and acquisition flow,
@@ -34,24 +44,65 @@ import parsing and selection, inheritance execution, reflective projection and
cloning, schema field construction, and filesystem-context derivation. Graph
caller traces and text-reference checks confirmed the unused reverse conversion
chain. This was source review, not a new runtime correctness or performance audit.
The audit's complexity scores locate candidates; they are not standardized
acceptance thresholds or evidence of a runtime defect.
Neither this review nor the audit established a runtime correctness defect.
| Audit finding | Assessment and recommended treatment |
| --- | --- |
| 1. Import entry points and responsibilities | Main refactor. Include shared acquisition normalization, import-default ownership, declaration parsing, and directory admission. |
| 2. Shared inheritance executor | Main refactor. Expose meaningful phases and explicit combination results while retaining one executor. |
| 3. Projection and cloning | Main refactor for projection; bounded follow-up for substantial clone handlers, preserving the distinction between the operations. |
| 4. Schema field discovery and inline assembly | Include a focused refactor coordinated with projection. Keep one schema builder and its two descriptor views. |
| 5. Resolved filesystem context | Include alongside acquisition work. Reuse resolved facts without merging resource lifetimes or changing validation timing. |
| 6. Unused reverse inspection conversions | Include as an independent cleanup in the root facade and engine. Retain useful forward-conversion and detached-result coverage. |
### Audit Measurements
This is the combined proposal for scope review, rather than a second independent
implementation of the earlier roadmap. Keep the audit as evidence; its findings
are not closed by adopting this document. Completed correctness and algorithmic
remediations remain part of the baseline, including sequence records preserved
at `ea46001:docs/roadmap/remediation.md` and discovery records preserved at
`0369111:docs/roadmap/remediation.md`.
The audit refreshed the codebase-memory graph and used function size, cognitive
complexity, branch counts, and parameter counts to rank candidates for source
inspection. It indexed 901 non-test functions/methods and 928 test-file
declarations. Its fast index excludes examples, documentation, and scripts; a
tracked-file inventory covered those separately. Standalone `gocyclo`, `gocognit`,
`scc`, and `cloc` tools were unavailable.
These are the graph tool's reported measurements at the audited revision.
Function spans include comments and blank lines. The scores support relative
triage; they are not standardized acceptance thresholds or evidence of a defect.
| Function | Source | Lines | Cognitive score |
| --- | --- | ---: | ---: |
| `valueOperation.project` | [projection.go](../../internal/engine/projection.go) | 195 | 174 |
| `parseImportDeclarationSpec` | [import_spec.go](../../internal/engine/import_spec.go) | 127 | 129 |
| `valueOperation.clone` | [clone.go](../../internal/engine/clone.go) | 130 | 104 |
| `schemaBuilder.describeFields` | [schema.go](../../internal/engine/schema.go) | 99 | 100 |
| `assembleBaseInputTrackedForRole` | [load_input.go](../../internal/engine/load_input.go) | 188 | 96 |
| `selectDirectoryImportCandidates` | [import_selection.go](../../internal/engine/import_selection.go) | 154 | 96 |
| `valueBuilder.build` | [value.go](../../internal/engine/value.go) | 104 | 93 |
| `decodeValue` | [decode.go](../../internal/engine/decode.go) | 115 | 85 |
| `applyInheritanceScopeTemplates` | [inheritance_schedule.go](../../internal/engine/inheritance_schedule.go) | 219 | 75 |
| `contextsForAcquiredSources` | [source_context.go](../../internal/engine/source_context.go) | 102 | 72 |
At that revision, the engine contained 88 production Go files and approximately
20,144 physical lines; the root facade contained 16 files and 1,861 lines.
`imports.go` was the largest production file at 1,195 lines. These measurements
locate concentrated responsibilities. They do not establish a need for more
packages or make the smaller document/YAML visitors and explicit facade
conversions maintenance defects.
### Findings And Recommended Treatment
The finding numbers below preserve the audit's identifiers. All six remain open
work; retiring their original documents does not mark them implemented.
| Audit finding | Maintenance priority | Assessment and recommended treatment |
| --- | --- | --- |
| 1. Import entry points and responsibilities | Higher | Main refactor. Include shared acquisition normalization, import-default ownership, declaration parsing, and directory admission. |
| 2. Shared inheritance executor | Higher | Main refactor. Expose meaningful phases and explicit combination results while retaining one executor. |
| 3. Projection and cloning | Higher for projection; secondary for cloning | Main refactor for projection; conditional, bounded follow-up for substantial clone handlers, preserving the distinction between the operations. |
| 4. Schema field discovery and inline assembly | Medium | Include a focused refactor coordinated with projection. Keep one schema builder and its two descriptor views. |
| 5. Resolved filesystem context | Medium | Include alongside acquisition work. Reuse resolved facts without merging resource lifetimes or changing validation timing. |
| 6. Unused reverse inspection conversions | Small, independently reviewable cleanup | Include in the root facade and engine. Retain useful forward-conversion and detached-result coverage. |
Findings 1–3 confirm the earlier roadmap's main opportunities; findings 4–6 add
focused work. The following sections own their rationale and intended changes.
Implementation and validation will establish each finding's disposition.
Completed correctness and algorithmic remediations remain part of the baseline,
including sequence records preserved at `ea46001:docs/roadmap/remediation.md`
and discovery records preserved at `0369111:docs/roadmap/remediation.md`.
Item-scope application matching and inheritance policy localization are examples
of completed corrections that overlap this work and whose regressions should
remain protected.
The [architecture policy](../policy/architecture.md),
[configuration contract](../config.md), and exported declaration comments own
@@ -140,6 +191,16 @@ processing, version rules, imports, placement, accounting, and contexts. Import
entry points carry long positional lists through several forwarding variants.
This repeats the representation of information already normalized for a load.
In [imports.go](../../internal/engine/imports.go), the
`loadImportedDocumentsTrackedWithVersion`,
`loadImportedDocumentsTrackedWithProcessing`, and
`loadImportedDocumentsTrackedWithProcessingDeferred` variants have corresponding
`loadImportedWithAccess...` variants. Both final signatures carry 13 parameters.
Placement, processing results, sequence policy, accounting, repetition tracking,
namespace identity, and deferred assembly must stay aligned through the chain.
The same file's `importTraversal.visitPath` combines source-admission decisions
in 174 lines, alongside acquisition, pending-item assembly, and evidence work.
Introduce cohesive private acquisition inputs and explicit state ownership,
reusing `loadRequest`, `loadInput`, `acquisitionScope`, and `importTraversal`
where they fit. Translate ordinary and layered public declarations into the
@@ -165,8 +226,7 @@ The state boundaries are especially important:
| One composition scope | Peer contributions, pending collection declarations, item-local helpers, and deferred item placement. Nested scopes do not become separate precedence tiers. |
| Retained result | Source records, effective destinations, origins, history, and passive resource-context descriptions. |
The older roadmap's broad description of load-wide repetition state should not
be implemented as a global visited-file restriction. In the current code,
Keep repetition tracking tier-scoped. In the current code,
`acquireUnderlayGroupScopes` creates a fresh visited map per group. Preserve valid
reuse across tiers while keeping shared aggregate limits. Namespace equality,
candidate spelling, and stable scheduling keys also serve different purposes.
@@ -178,14 +238,15 @@ source IDs and source-local version processing in acquisition order, even when
composition uses a different dependency-ready order. The layered main is acquired
before underlays; lower-tier identity can still inform its later strict assembly.
Within import parsing, extract boolean/collection/placement field handling and
selector-value parsing where it clarifies responsibilities. Keep field presence,
authored error locations, selector applicability, and the order of consequential
validation visible. Within directory selection, separate entry admission and
descent decisions from traversal orchestration. Retain the existing root
deduplication, candidate union, exclusions, sorting, and active-path cycle rules.
No shared abstraction should conflate literal first-match main discovery with
multi-file import selection.
Within `parseImportDeclarationSpec`, extract boolean/collection/placement field
handling and selector-value parsing where it clarifies responsibilities. Keep
field presence, authored error locations, selector applicability, and the order
of consequential validation visible. Within `selectDirectoryImportCandidates` and
`importTraversal.visitPath`, separate admission and descent decisions from
traversal orchestration where they represent distinct work. Retain the existing
root deduplication, candidate union, exclusions, sorting, and active-path cycle
rules. No shared abstraction should conflate literal first-match main discovery
with multi-file import selection.
### 2. Share Resolved Filesystem Facts Without Sharing Live Handles
@@ -193,6 +254,8 @@ multi-file import selection.
derive overlapping root/base/namespace facts. The latter reconstructs context
from combinations of source kind and optional fields, including absent input.
Discovery and independent layered overlays make these combinations consequential.
Context construction is used by ordinary acquisition and both selected-overlay
paths, so those callers need to use the same applicable derivation rules.
Use a small engine-owned resolved-context description for the facts actually
needed by acquisition and passive views: namespace identity/kind, resolved root,
@@ -255,8 +318,9 @@ Struct projection needs particular care: physical members drive traversal,
flattened fields drive name lookup and sensitivity, and an inline container is
not retained as an extra output node. Preserve declaration order, deterministic
map order, nil/empty distinctions, collision diagnostics, codec failures, and
secret classification. Keep cycle entries active through child traversal and
balance their release on every exit.
secret classification. Scalar projection retains the existing number, duration,
text-codec, and secret-reference representations. Keep cycle entries active
through child traversal and balance their release on every exit.
In `schemaBuilder.describeFields`, separate field discovery and tag parsing from
inline struct assembly, inline map assembly, and ordinary field registration.
@@ -265,9 +329,14 @@ Retain one builder/cache and its recursion detection. Make the paired updates to
Keep index-path construction and inherited secret flags intact. These descriptor
views are both needed; combining them into one collection would shift complexity
into decoding and projection.
Keep pointer-chain and recursive-inline decisions explicit, preserve supported
field/tag forms and ambiguity paths, and retain cache/building-state behavior.
Follow with a bounded cleanup of substantial clone handlers where it makes their
ownership behavior easier to read. Keep cloning distinct from projection:
Provisionally treat clone cleanup as a conditional follow-up, as recommended in
[OQ-2](#oq-2-how-much-clone-cleanup-should-this-effort-commit-to). Extract substantial
handlers where they make ownership behavior easier to read after the projection
and schema work; completing this scope need not require clone edits if the
remaining flow is already clear. Keep cloning distinct from projection:
cloning reconstructs typed values, preserves physical fields, round-trips text
codecs, and distinguishes unresolved from already validated secret state.
Projection builds a canonical document and charges output nodes. Extract common
@@ -277,19 +346,25 @@ visitor solely because it has a high complexity score.
### 5. Remove Unused Inspection Conversions And Consolidate Real Adapters
Remove `toEngineSourceInfo`, `toEngineOrigin`, the exclusive reverse version and
import-selection converters, and the engine adapters used only by that chain.
Remove `toEngineSourceInfo`, `toEngineOrigin`, `toEngineSourceVersionCheck`, and
`toEngineImportSelections` from [conversion.go](../../conversion.go), along with
the engine adapters used only by that chain.
At the reviewed revision, the three callers of `toEngineSourceInfo` are tests;
`toEngineOrigin` has none. `SourceInfoWithPlacement`,
`SourceInfoWithImportSelections`, and their exclusive string-to-enum helpers
have no production role beyond that reverse chain. Recheck callers at the
implementation baseline before removal.
`SourceInfoWithImportSelections`, `importSelectorFromString`, and
`importSelectionOutcomeFromString` in [records.go](../../internal/engine/records.go)
have no production role beyond that reverse chain. Consumers receive inspection
records; production facade operations do not send those records back to the
engine. The unused inverse path adds another ownership mapping to maintain as
inspection evidence grows. Recheck callers at the implementation baseline before
removal.
Rewrite the affected record tests around real engine-to-public conversion and
detached public inspection. Preserve useful placement, version evidence,
import-selection, and copy-isolation assertions. Avoid manufacturing replacement
production setters solely to keep an old round-trip fixture working. Existing
facade loads already provide genuine sources and inspection records.
Rewrite the affected [record tests](../../records_test.go) around real
engine-to-public conversion and detached public inspection. Preserve useful
placement, version evidence, import-selection, and copy-isolation assertions.
Avoid manufacturing replacement production setters solely to keep an old
round-trip fixture working. Existing facade loads already provide genuine sources
and inspection records.
Retain reverse conversions that serve real inputs: `toEngineDiagnostics`, for
example, supports `WriteDiagnostics`. Consolidate repeated override/input
@@ -301,9 +376,10 @@ the boundary rather than simplify it.
## Scope, Compatibility, And Policy Consequences
The proposed work spans private engine code, private root-facade conversions,
affected tests, consumer guidance, and implementation documentation. This is a
deliberate expansion beyond the older engine-only roadmap. Preserve public
types/signatures and the behavior owned by the current contracts, including:
affected tests, consumer guidance, and implementation documentation. Under the
recommended answer to [OQ-1](#oq-1-should-the-public-loading-apis-change-in-this-effort),
preserve public types/signatures and the behavior owned by the current contracts,
including:
- Acquisition versus composition ordering, strict scopes versus precedence
tiers, identity ownership, placement, and source-version protection.
@@ -339,8 +415,8 @@ or is required to claim readability improvements.
This is dependency guidance for the later plan, not a commit-by-commit schedule:
1. Confirm the reviewed revision and public-surface direction; map the retained
behavior to existing tests and record concrete coverage gaps.
1. Confirm the implementation baseline and answers to the open questions; map
retained behavior to existing tests and record concrete coverage gaps.
2. Remove unused reverse inspection conversions and adjust their tests. This is
small and independently reviewable.
3. Normalize acquisition inputs and separate import-default ownership. Develop
@@ -349,7 +425,8 @@ This is dependency guidance for the later plan, not a commit-by-commit schedule:
4. Refactor inheritance around explicit preparation and combination results,
retaining completed correctness and algorithmic regressions.
5. Refactor projection and schema field assembly in separate reviewable changes;
complete the bounded clone cleanup where it improves the remaining flow.
assess and, where useful, complete bounded clone cleanup under the scope
selected in OQ-2.
6. Consolidate real facade adapters, finish consumer/internal navigation, and run
the applicable integration and ownership checks on the combined result.
@@ -402,6 +479,47 @@ Completion requires reviewable evidence that:
the resulting implementation. Current contracts continue to own behavior.
Private type/helper names, final file splits, and exact stage boundaries belong
in the implementation plan. The public-surface recommendation and scope above
are ready for review; no additional feature semantics are needed to carry out
the recommended refactors.
in the implementation plan. The questions below concern the public direction and
scope of the work. No additional feature semantics are needed to carry out the
recommended refactors.
## Open Questions
The target above follows the recommended answers below, pending discussion.
Existing behavior and accepted architectural boundaries remain the baseline;
routine private design choices can be settled in the implementation plan.
### OQ-1: Should The Public Loading APIs Change In This Effort?
**Recommendation:** retain `Load`/`Options` and `LoadLayered`/`LayeredOptions`,
and consolidate their private inputs, conversions, and acquisition machinery.
The current simple call needs little setup, while layered loading makes input
groups and independent overlay context explicit. The maintained consumer examples
demonstrate useful roles for both. Better guidance and shared private machinery
address the observed duplication without adding public concepts.
**Alternative:** introduce one public request model for main input, underlays,
and load-wide options, with a convenience entry for simple loading. This could
reduce repeated option declarations and make a consumer's move to layered loading
more uniform. It is viable before 1.0, but needs concrete simple and advanced
examples to show an improvement, plus a deliberate choice about ordinary versus
layered overlay-context behavior. It would expand this effort into public API
design and consumer migration. If selected, revise the public target before
preparing the internal implementation plan.
### OQ-2: How Much Clone Cleanup Should This Effort Commit To?
**Recommendation:** commit to projection and schema refactoring, then assess
clone handlers as a bounded follow-up. Include extractions that clarify typed
copy ownership, secret-state handling, or codec behavior; allow the review to
conclude that no clone changes are needed. Projection and schema have identified
mixed responsibilities, while part of cloning's size is ordinary type dispatch.
This keeps the effort focused on demonstrated maintenance benefit. Record the
assessment under audit finding 3 so conditional work is not silently omitted.
**Alternative:** include a focused clone-handler refactor as committed scope
alongside projection and schema. Reviewing the related traversals together could
give maintainers more consistent places to find struct, map, and sequence handling.
The tradeoff is additional ownership-sensitive code movement when extraction may
not simplify the flow. Cloning and projection would still retain their distinct
semantics and operation state; a common visitor is not needed for either choice.