251 lines
15 KiB
Markdown
251 lines
15 KiB
Markdown
# Complexity Audit Findings
|
||
|
||
Status: open recommendations for consideration. This is an audit record, not an
|
||
implementation plan or a new release gate.
|
||
|
||
Reviewed revision: `5959537d1adc2516e7f7e8881df72b707ec48c3f`.
|
||
|
||
## Scope And Method
|
||
|
||
The review considered production Go code, package boundaries, private interfaces,
|
||
and supporting tests. The local codebase-memory graph was refreshed, and its
|
||
function-size, cognitive-complexity, branch, and parameter metrics were used to
|
||
rank candidates. Source inspection and inbound call traces then distinguished
|
||
mixed responsibilities from ordinary dispatch and deliberate boundary code.
|
||
Text-reference searches checked the apparently unused conversions in finding 6.
|
||
No benchmark campaign or runtime correctness testing was part of this audit.
|
||
|
||
The graph indexed 901 non-test functions/methods and 928 test-file declarations.
|
||
Its fast index excludes examples, documentation, and scripts; the tracked-file
|
||
inventory covered those separately. Standalone `gocyclo`, `gocognit`, `scc`, and
|
||
`cloc` executables were not available. The following scores are the graph tool's
|
||
reported cognitive scores, used for relative triage rather than as limits or
|
||
standardized acceptance criteria. Function spans include comments and blank
|
||
lines within the declaration.
|
||
|
||
| 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 |
|
||
|
||
The private engine contains 88 production Go files and approximately 20,144
|
||
physical lines, compared with 16 files and 1,861 lines in the root facade.
|
||
`imports.go` is the largest production file at 1,195 lines. Size identifies where
|
||
to inspect; it does not establish that the engine needs to be split into packages.
|
||
|
||
Findings 1–3 confirm opportunities already selected in the pending
|
||
[complexity roadmap](complexity.md). Findings 4–6 add narrower opportunities.
|
||
They should be coordinated with that roadmap rather than implemented as an
|
||
independent overlapping refactor. No ordinary correctness defect was established
|
||
by this static review.
|
||
|
||
## 1. Consolidate Import Entry Points And Separate Import Responsibilities
|
||
|
||
Status: open. Priority: higher maintenance benefit. Scope: `internal/engine`.
|
||
|
||
**Evidence and complexity.** [imports.go](../../internal/engine/imports.go)
|
||
contains parallel forwarding ladders such as
|
||
`loadImportedDocumentsTrackedWithVersion`,
|
||
`loadImportedDocumentsTrackedWithProcessing`, and
|
||
`loadImportedDocumentsTrackedWithProcessingDeferred`, plus corresponding
|
||
`loadImportedWithAccess...` variants. Both final signatures carry 13 declared
|
||
parameters, counting names in grouped declarations.
|
||
Related values must remain aligned across these calls: placement, version state,
|
||
processing results, sequence policy, accounting, repetition tracking, namespace
|
||
identity, and deferred assembly.
|
||
|
||
The same file also owns source admission, filesystem access lifetime, recursive
|
||
acquisition, pending-item assembly, and evidence projection. Source admission in
|
||
`importTraversal.visitPath` is 174 lines. The 188-line input assembler in
|
||
[load_input.go](../../internal/engine/load_input.go) adds discovery, source-role,
|
||
directive, version, placement, and resource-context decisions around that flow.
|
||
Import defaults are carried through `sourceVersionState`, although import
|
||
defaulting and version checking are independent concerns. Readers have to follow
|
||
that incidental state relationship to understand ordinary import behavior.
|
||
|
||
**Potential refactoring.** Follow the roadmap's cohesive request/context design,
|
||
with named inputs and explicit ownership of load-wide state. Remove forwarding
|
||
variants that only add another optional argument; retain helpers that express
|
||
distinct operations. Give acquisition, already-acquired scope composition, and
|
||
evidence projection focused homes. Keep load-wide import defaults with an
|
||
appropriate acquisition/load context rather than requiring version state to be
|
||
their transport.
|
||
|
||
Within that work, extract coherent declaration-field parsing and directory-entry
|
||
admission operations from `parseImportDeclarationSpec` and
|
||
`selectDirectoryImportCandidates`. Keep their selector-policy checks and
|
||
deterministic traversal visible. Moving code into smaller functions without
|
||
clarifying state handoffs would not resolve the main maintenance problem.
|
||
|
||
Preserve acquisition order, strict scope scheduling, item-local composition,
|
||
source/version evidence, existing limits, and explicit resource closure. The
|
||
existing import/discovery and ordinary/layered integration tests are the relevant
|
||
behavioral protection.
|
||
|
||
## 2. Expose The Phases Of The Shared Inheritance Executor
|
||
|
||
Status: open. Priority: higher maintenance benefit. Scope: `internal/engine`.
|
||
|
||
**Evidence and complexity.** `applyInheritanceScopeTemplates` in
|
||
[inheritance_schedule.go](../../internal/engine/inheritance_schedule.go)
|
||
coordinates template preparation, directive controls, retained-node accounting,
|
||
parent identity exclusion, inherited collection-policy preparation, recursive
|
||
mapping/sequence combination, origin transfer, replacement history, replay
|
||
operations, final policy projection, and scope rebuilding in one 219-line body.
|
||
Its merge callbacks mutate several surrounding results, so the evidence produced
|
||
by one combination is difficult to assess independently of the whole executor.
|
||
|
||
**Potential refactoring.** Keep the useful mapping/identified-sequence adapters
|
||
and one shared executor. Extract parent/child preparation, combination, evidence
|
||
construction, and accounting into meaningful operations with small, explicit
|
||
result records where appropriate. Make it clear which values are borrowed
|
||
templates and which are owned resolved results. Keep one sequence-combination
|
||
result as the source of value, policy, origin, and historical-position evidence.
|
||
|
||
This is the inheritance refactor already described in the complexity roadmap.
|
||
Preserve dependency-ready ordering, enclosing-before-nested evaluation, child
|
||
identity, policy ownership, history budgets, and sensitivity. Reuse the mapping
|
||
and identified-record inheritance, history, and ownership tests.
|
||
|
||
## 3. Decompose Reflective Projection And Review Clone Handlers Separately
|
||
|
||
Status: open. Priority: higher maintenance benefit for projection; secondary for
|
||
cloning. Scope: `internal/engine`.
|
||
|
||
**Evidence and complexity.** `valueOperation.project` in
|
||
[projection.go](../../internal/engine/projection.go) has the highest reported
|
||
cognitive score. Its struct branch alone handles member traversal, inline
|
||
flattening, key collisions, flattened-container accounting, and secret-field
|
||
classification. The enclosing dispatcher also handles pointer/cycle lifetime,
|
||
dynamic descriptors, maps, sequences, and scalar codecs.
|
||
`valueOperation.clone` in [clone.go](../../internal/engine/clone.go) has a similar
|
||
large dispatcher, including distinct secret-copy modes and text-codec round trips.
|
||
|
||
**Potential refactoring.** Implement the roadmap's focused struct/map/sequence
|
||
projection handlers while retaining `valueOperation` as the traversal-state
|
||
owner. Keep the dispatch and scalar representation decisions easy to locate.
|
||
Apply the same readability review to the substantial clone branches as a separate
|
||
small follow-up if it remains beneficial; keep cloning and projection as distinct
|
||
operations.
|
||
|
||
The high-scoring `valueBuilder.build` and `decodeValue` are predominantly explicit
|
||
type dispatch; decoding already delegates collection handling. Their scores alone
|
||
do not justify a generic reflection visitor. Share only operations whose semantics
|
||
actually match. Preserve balanced cycle tracking, depth/node accounting, inline
|
||
order, nil/empty distinctions, codecs, and secret behavior. Existing projection,
|
||
clone, schema, decoding, callback-ownership, and independent-load tests cover the
|
||
important risks.
|
||
|
||
## 4. Separate Schema Field Discovery From Inline Field Assembly
|
||
|
||
Status: open. Priority: medium maintenance benefit. Scope: `internal/engine`.
|
||
|
||
**Evidence and complexity.** `schemaBuilder.describeFields` in
|
||
[schema.go](../../internal/engine/schema.go) nests field enumeration and tag
|
||
handling around pointer-chain inspection, recursive-inline detection, inline
|
||
struct flattening, index-path construction, inline-map admission, duplicate
|
||
checks, secret propagation, and construction of both `members` and flattened
|
||
`fields`. Those two descriptor views serve different traversal needs, and their
|
||
consistency currently depends on understanding the full nested routine.
|
||
|
||
**Potential refactoring.** Retain one schema builder/cache. Extract named inline
|
||
struct and inline-map assembly operations and make ordinary-field registration
|
||
clear. Small helpers can centralize the paired updates to `members`, `fields`,
|
||
`fieldByName`, and `inlineMap`, including inherited secret classification, where
|
||
the same registration semantics apply. Keep pointer and recursive-type decisions
|
||
explicit rather than moving them into a configurable registration framework.
|
||
|
||
Preserve accepted field/tag forms, cache/building-state behavior, declaration
|
||
order, ambiguity diagnostics and paths, and schema/projection/decode agreement.
|
||
Existing inline, recursive-schema, text-codec, secret, and ambiguity tests are the
|
||
appropriate protection.
|
||
|
||
## 5. Give Resolved Filesystem Context A Clear Shared Representation
|
||
|
||
Status: open. Priority: medium maintenance benefit. Scope: acquisition and passive
|
||
context handling within `internal/engine`.
|
||
|
||
**Evidence and complexity.** [filesystem.go](../../internal/engine/filesystem.go)
|
||
derives host/native roots, selected-file bases, and containment during import and
|
||
context validation. `contextsForAcquiredSources` in
|
||
[source_context.go](../../internal/engine/source_context.go) independently derives
|
||
much of the same information, then computes each source's root-relative base.
|
||
It branches among native sources, explicit native contexts, selected host files,
|
||
absent host input, and in-memory sources before branching again for relative-path
|
||
calculation. The lifecycle calls it from ordinary acquisition and both selected
|
||
overlay paths, so a change in context derivation has several integration points.
|
||
|
||
**Potential refactoring.** Consider a small engine-owned resolved-context record
|
||
that names the namespace, root, selected-source path, and base directory. Share
|
||
the overlapping derivation/relative-base operations across acquisition and
|
||
passive-context construction, while keeping host and `fs.FS` path rules explicit.
|
||
Pass already-resolved facts where they are available instead of reconstructing
|
||
them from source-kind and optional-context combinations.
|
||
|
||
Validation, acquisition access, and returned passive views have different jobs;
|
||
a refactor should preserve their existing timing and ownership. In particular,
|
||
reuse of a context description need not retain an acquisition handle or make
|
||
previously deferred checks eager. Preserve selected-file identity, source-ID
|
||
association, containment diagnostics, absent-input behavior, and independent
|
||
overlay contexts. Existing native/host filesystem, discovery integration,
|
||
resource-context, and facade tests provide the behavioral baseline.
|
||
|
||
## 6. Remove Unused Reverse Inspection Conversions Across The Facade Boundary
|
||
|
||
Status: open. Priority: smaller, well-bounded cleanup. Scope: root `configkit` and
|
||
`internal/engine` together.
|
||
|
||
**Evidence and complexity.** In [conversion.go](../../conversion.go),
|
||
`toEngineSourceInfo` is called only by three tests in
|
||
[records_test.go](../../records_test.go). Its helpers
|
||
`toEngineSourceVersionCheck` and `toEngineImportSelections` have no callers outside
|
||
that reverse-conversion chain. `toEngineOrigin` has no callers. The corresponding
|
||
engine setters `SourceInfoWithImportSelections` and `SourceInfoWithPlacement` in
|
||
[records.go](../../internal/engine/records.go) exist only for that chain, as do
|
||
`importSelectorFromString` and `importSelectionOutcomeFromString`.
|
||
|
||
Consumers receive these inspection records; the production facade does not send
|
||
them back into the engine. Maintaining an unused reverse path adds a second
|
||
representation/ownership mapping whenever inspection evidence grows, and the
|
||
round-trip tests make that machinery appear necessary despite its lack of a
|
||
runtime caller.
|
||
|
||
**Potential refactoring.** Remove the unused inverse conversions and their
|
||
exclusive engine-side adapters together. Rewrite the affected tests around
|
||
engine-to-public conversion and detached public query records, preserving useful
|
||
placement, version-evidence, and import-selection ownership checks. Continue to
|
||
exercise real source creation/loading through the existing facade integration
|
||
tests. This can reduce both production interface surface and test scaffolding
|
||
without adding a transport framework.
|
||
|
||
Retain the forward inspection conversions and root-owned public types. Other
|
||
reverse conversions have real users: for example, `toEngineDiagnostics` supports
|
||
the public diagnostic renderer. Apply caller-based removal rather than deleting
|
||
conversions merely because they look symmetrical.
|
||
|
||
## Architectural Assessment And Follow-up
|
||
|
||
The package direction remains coherent: root-owned public wrappers delegate to
|
||
the engine; the engine uses the ordered document model and the private YAML
|
||
adapter. Most complexity is concentrated in multi-responsibility engine routines,
|
||
rather than distributed through unnecessary packages. The smaller document and
|
||
YAML packages have clear responsibilities; their tree visitors and the facade's
|
||
explicit conversions are not inherently maintenance defects.
|
||
|
||
The strongest next investment is the pending complexity roadmap's import,
|
||
inheritance, and projection work. Finding 6 is an independently reviewable cleanup;
|
||
findings 4 and 5 can be assessed as focused follow-ups. Package extraction or
|
||
public API redesign is not needed to pursue these findings. Keep the current
|
||
contracts as the behavioral baseline and use the
|
||
[development guide](../development.md) to select proportionate validation during
|
||
implementation. This audit introduces no new complexity thresholds, configuration
|
||
restrictions, ownership guarantees, or release requirements.
|