223 lines
12 KiB
Markdown
223 lines
12 KiB
Markdown
# Internal Complexity Refactoring Roadmap
|
|
|
|
Status: proposed target state. This roadmap defines a behavior-preserving
|
|
refactor; a later implementation plan will define stages and exact private
|
|
signatures and file names.
|
|
|
|
## Purpose
|
|
|
|
Make ConfigKit's import, inheritance, and projection implementation easier to
|
|
understand, review, and change while preserving its public APIs and configuration
|
|
behavior. Concentrate on functions that coordinate several responsibilities and
|
|
carry substantial shared state.
|
|
|
|
The target is clearer responsibility and ownership. Adding a few well-named
|
|
helpers, private records, or focused files can serve that target even when total
|
|
line count increases. Complexity measurements help locate candidates; they do
|
|
not establish function-size limits, score thresholds, or release gates.
|
|
|
|
The [architecture policy](../policy/architecture.md) owns package and ownership
|
|
constraints. The [configuration contract](../config.md) and exported Go comments
|
|
remain authoritative for consumer behavior.
|
|
|
|
## Current Baseline
|
|
|
|
Reviewed baseline: `7a83704f43ef9870db33661231cdff5d6ee502f7`.
|
|
|
|
The root facade delegates to a cohesive private engine, supported by the ordered
|
|
document representation and YAML adapter. Most functions are small. The
|
|
complexity audit identified these concentrated maintenance costs:
|
|
|
|
| Area | Current implementation | Required improvement |
|
|
| --- | --- | --- |
|
|
| Imports | `imports.go` spans acquisition, item-local composition, and evidence projection. Private loading variants pass long positional argument lists. Source admission and directory selection contain substantial mixed control flow. | Give import entry points explicit, cohesive inputs and separate the responsibilities of acquisition, scope assembly, and evidence projection. |
|
|
| Inheritance | `applyInheritanceScopeTemplates` coordinates payload preparation, parent combination, policy ownership, origins, history, and accounting in one executor. | Keep one readable executor with focused operations and explicit state handoffs. |
|
|
| Projection | `valueOperation.project` combines type dispatch with struct flattening, map and sequence traversal, scalar conversion, sensitivity, and accounting. | Retain clear dispatch while moving substantial value-kind handling into focused helpers. |
|
|
|
|
The implemented inventory belongs to the
|
|
[component overview](../internal/overview.md). Existing import flow and scheduling
|
|
are described in [import internals](../internal/imports.md).
|
|
|
|
## Target Architecture
|
|
|
|
The refactor stays within `internal/engine`. The root facade, `internal/document`,
|
|
and `internal/yaml` retain their existing responsibilities and dependency
|
|
direction. Focused files and ordinary private functions express the new internal
|
|
organization. Package extraction is outside this roadmap's selected design.
|
|
|
|
`executeLoadRequest` remains the visible coordinator of the shared load lifecycle.
|
|
Its phase order should remain easy to follow. Helpers expose meaningful work and
|
|
results rather than distributing that order across a generic execution framework.
|
|
|
|
Existing shared mechanisms remain shared: recursive mapping combination,
|
|
identified-sequence operations, dependency-ready scheduling, schema descriptors,
|
|
and projection/accounting state. New helper boundaries make their ownership and
|
|
use clearer without creating parallel implementations.
|
|
|
|
### Imports: Cohesive Inputs And Scope Ownership
|
|
|
|
Import loading has a clear private entry surface using named request/context
|
|
fields for related inputs. Reuse the existing load-request, acquisition-scope,
|
|
and traversal models where they fit. Consolidate forwarding variants whose only
|
|
purpose is passing another optional positional argument through the chain.
|
|
Retain convenience helpers when they express a useful, distinct operation.
|
|
|
|
Keep these state lifetimes identifiable:
|
|
|
|
- Load-wide state: accounting, shared inclusion/repetition information,
|
|
namespaces, and source-version processing.
|
|
- Acquisition requests: source and filesystem context, placement, declarations,
|
|
applicable policy, and the relevant assembly handoff.
|
|
- Composition scopes: peer contributions, item-local helpers, record ownership,
|
|
and pending declarations.
|
|
- Evidence: physical source records, effective destinations, origins, and retained
|
|
history projections.
|
|
|
|
Group acquisition, pending-item assembly, and evidence projection in focused
|
|
files. A caller should be able to identify which operation acquires resources,
|
|
which composes already acquired content, and which projects retained evidence.
|
|
Shared mutable state has a visible owner; a request record need not duplicate
|
|
state already held by that owner.
|
|
|
|
Within dense admission, directory-selection, and declaration-parsing routines,
|
|
extract coherent operations where that reduces nested, mixed responsibilities.
|
|
Preserve the existing selection algorithms and host/native filesystem behavior.
|
|
Resource ownership and closure remain explicit across success and failure paths.
|
|
|
|
The resulting flow preserves the distinction among acquisition order, strict
|
|
scope scheduling, and precedence. Completing a helper scope before placing its
|
|
item remains part of the same import flow. Ordinary and layered loading continue
|
|
to share the applicable mechanisms.
|
|
|
|
### Inheritance: One Executor With Explicit Phases
|
|
|
|
Keep the mapping and identified-sequence adapters and their shared template
|
|
executor. The executor coordinates focused operations for:
|
|
|
|
- Preparing child payload, directives, and destination-local state.
|
|
- Preparing the resolved parent payload and applicable inherited policy.
|
|
- Combining values through the existing mapping and sequence mechanisms.
|
|
- Producing policy, origin, replacement, and replay evidence from that combination.
|
|
- Accounting for expansion and retained history under the existing budgets.
|
|
|
|
These are responsibility boundaries, not a required helper count or a new
|
|
scheduler. Small private result records are appropriate when related outputs
|
|
otherwise travel through long argument lists or implicit mutations.
|
|
|
|
Authored templates, resolved values, scoped policy, and inspection evidence remain
|
|
distinguishable. Immutable borrowed inputs and owned mutable results have clear
|
|
lifetimes. Nested instructions remain available for destination-local evaluation.
|
|
For identified-record inheritance, the child's own identity fields and origins
|
|
remain intact; the parent's identity fields are excluded from inherited payload
|
|
and its history, as the current contract requires.
|
|
|
|
One sequence-operation result continues to drive value construction, record
|
|
ownership, origins, and historical position projection. Helpers consume that
|
|
evidence directly. Scheduling remains dependency-ready, enclosing relationships
|
|
resolve before nested ones, and assembled sequence order remains unchanged.
|
|
|
|
### Projection: Explicit Value-Kind Handlers
|
|
|
|
Keep `projectConfiguration` as the schema-checked entry and `valueOperation` as
|
|
the owner of per-operation traversal and accounting state. The central dispatch
|
|
clearly selects the appropriate handling for pointers, dynamic values, structs,
|
|
maps, sequences, and scalars.
|
|
|
|
Substantial struct, map, and sequence work lives in focused handlers. Struct
|
|
projection retains declaration order, inline flattening, collision diagnostics,
|
|
and sensitivity propagation. Map projection retains deterministic key ordering.
|
|
Scalar conversion retains the existing number, duration, text-codec, and secret
|
|
reference representations.
|
|
|
|
Depth and node accounting retain their existing meaning, including flattened
|
|
containers. Cycle tracking stays active through recursive child traversal and
|
|
is balanced on error paths as well as success. Passing state through a helper
|
|
does not introduce another full-tree projection or an unnecessary ownership copy.
|
|
|
|
Cloning and source-value construction remain distinct operations with their
|
|
existing semantics. Reuse small helpers when the semantics coincide; keep the
|
|
projection refactor centered on making the existing traversal readable.
|
|
|
|
## Behavior And Scope Preservation
|
|
|
|
The implementation preserves:
|
|
|
|
- Root-owned public types, signatures, supported import paths, and facade boundaries.
|
|
- Supported source forms, opt-ins, import controls, placement, acquisition and
|
|
composition ordering, and source/version evidence.
|
|
- Strict peer composition, precedence operations, identity agreement and lifetime,
|
|
record ownership, and destination-local inheritance.
|
|
- The load lifecycle, including typed defaults, post-decode CLI assignment,
|
|
recorded application resolution, and final validation.
|
|
- Explicit presence, provenance, history, sensitivity, resource contexts, and
|
|
detached publication/query results.
|
|
- Established diagnostic codes, semantic paths, source coordinates, ordering,
|
|
resource lifetime, and existing limit behavior.
|
|
|
|
The owning contracts define the extent of these obligations. Incidental private
|
|
call sequences, exact helper names, and allocation counts do not acquire new
|
|
guarantees through this roadmap. The work adds no consumer options, configuration
|
|
syntax, dependencies, or complexity-based gates.
|
|
|
|
## Relationship To Remediation And Other Work
|
|
|
|
The completed remediation record at `ea46001:docs/roadmap/remediation.md`
|
|
documents the identified correctness and algorithmic efficiency findings.
|
|
Several overlap these files, particularly item-scope application matching and
|
|
inheritance policy localization.
|
|
|
|
Use the documented contract and completed remediation as the behavioral baseline.
|
|
Keep corrective changes reviewable under their findings, and retain their
|
|
regressions through this refactor. The later implementation plan should coordinate
|
|
overlapping work and select its starting revision rather than duplicating the
|
|
remediation plan here. These structural changes do not close a finding merely
|
|
because its function moved or became smaller.
|
|
|
|
The pending [discovery roadmap](discovery.md) remains separate feature work.
|
|
Import cleanup should leave clear private boundaries for future use without
|
|
implementing discovery behavior as part of this refactor.
|
|
|
|
## Work Needed And Validation
|
|
|
|
Implementation needs to consolidate import inputs and adapters, separate import
|
|
responsibilities, extract inheritance operations with explicit outputs, and
|
|
decompose projection handling. Remove superseded private plumbing as its callers
|
|
migrate. Review the resulting call flow for repeated traversals, policy scans,
|
|
copies, or hidden state transitions introduced by extraction.
|
|
|
|
Reuse the existing behavioral suites under the
|
|
[development guide](../development.md) and [testing policy](../policy/testing.md):
|
|
|
|
- Imports: selection, scheduling, source/version evidence, placement, helper scopes,
|
|
ordinary/layered equivalence, filesystem failures, and resource lifetime.
|
|
- Inheritance: mapping and record relationships, nested destination resolution,
|
|
cancellation and replacement, policy ownership, history, sensitivity, and
|
|
independent loads.
|
|
- Projection: schema/decoding agreement, inline fields, text codecs, nil/empty
|
|
values, cycles and budgets, secrets, and detached results.
|
|
|
|
Add focused regressions only where a consequential handoff risk lacks coverage.
|
|
Tests should continue to describe behavior as private functions and files move.
|
|
Use the existing everyday check and applicable ownership race checks during
|
|
implementation. Complexity measurements can inform review; acceptance does not
|
|
depend on numerical scores or a new benchmark campaign.
|
|
|
|
Update the component overview and import internals to describe the implemented
|
|
ownership and file responsibilities when the refactor lands. Update contributor
|
|
navigation and test-owner references where moves affect them. Public behavior
|
|
continues to be defined by its current canonical owners.
|
|
|
|
## Completion Criteria
|
|
|
|
- Import callers pass cohesive named inputs, with clearly owned load-wide and
|
|
scope-local state and fewer redundant forwarding variants.
|
|
- Import acquisition, item assembly, and evidence projection are easy to locate
|
|
and follow across focused private files.
|
|
- Inheritance orchestration exposes value, policy, evidence, and accounting work
|
|
without requiring readers to reconstruct their interaction from one large body.
|
|
- Projection dispatch and substantial value-kind handlers have clear boundaries
|
|
and share the original operation state correctly.
|
|
- Existing APIs and contracted behavior, including completed remediation, remain
|
|
covered by the relevant behavioral and ownership checks.
|
|
- Internal documentation matches the resulting implementation.
|