225 lines
11 KiB
Markdown
225 lines
11 KiB
Markdown
# Potential Maintainability Audit
|
|
|
|
## Status
|
|
|
|
Initial impressions only. This document does not define action items, commit to
|
|
an audit, or recommend specific refactoring. Its purpose is to preserve signals
|
|
that may warrant investigation in a subsequent, deeper pass.
|
|
|
|
## Context
|
|
|
|
Narratio contains approximately 36,000 lines of production Go and 45,000 lines
|
|
of test Go across 26 packages. That footprint appears broadly consistent with a
|
|
durable workflow orchestrator that owns configuration, pipeline sequencing,
|
|
artifact and manifest state, recovery, storage, subprocess integration, and
|
|
filesystem safety. It is larger than would be expected of a simple command
|
|
wrapper, but the current size alone is not evidence of a maintainability
|
|
problem.
|
|
|
|
Narratio handles non-sensitive pipeline data and is expected to run in a
|
|
trusted environment. A future review therefore need not assume an adversary who
|
|
can manipulate workspace paths, symlinks, or directory entries concurrently
|
|
with the process. Protection against accidental path escape and destructive
|
|
operator mistakes remains useful, as do atomic replacement, crash durability,
|
|
and recoverable state transitions. The distinction between adversarial
|
|
filesystem hardening and crash-safe data integrity should guide any proposed
|
|
simplification.
|
|
|
|
## Preliminary Signals
|
|
|
|
The following observations may justify a focused maintainability audit:
|
|
|
|
- Production code is concentrated in `internal/stage`, `internal/app`, and
|
|
`internal/config`. These packages contain approximately 8,300, 7,900, and
|
|
5,500 lines respectively.
|
|
- Several production files exceed 1,000 lines, including stage publishing and
|
|
analysis, configuration validation, and application runner code. File size
|
|
does not establish poor cohesion, but it can conceal multiple responsibilities
|
|
or make change impact harder to assess.
|
|
- The application, stage, and artifact areas have substantial interaction.
|
|
Their effective boundaries and the blast radius of changes may merit closer
|
|
examination.
|
|
- The most notable function-level complexity observed so far is concentrated in
|
|
confined filesystem and directory-promotion code. This is security-sensitive
|
|
logic built around a stronger threat model than Narratio now requires. A
|
|
review could determine which mechanisms exist only to resist adversarial
|
|
filesystem races and which are necessary for path safety, atomic updates, and
|
|
crash-safe integrity.
|
|
- Test code is larger than production code. This is a positive verification
|
|
signal, but a deeper pass could determine whether the suite also contains
|
|
repetition, brittle implementation coupling, or fixture and helper sprawl.
|
|
|
|
## Counter-Signals
|
|
|
|
The initial review also found evidence against a conclusion of broad or urgent
|
|
maintainability trouble:
|
|
|
|
- Repository-wide tests and `go vet` pass.
|
|
- Package dependencies are acyclic.
|
|
- Average function complexity is modest, with higher complexity appearing
|
|
localized rather than systemic.
|
|
- The direct dependency set is small.
|
|
- Documentation is structured around explicit ownership and reading paths.
|
|
- The repository has substantial automated test coverage by volume.
|
|
|
|
## Questions for a Deeper Pass
|
|
|
|
A later audit could investigate, without presuming that changes are required:
|
|
|
|
- whether responsibilities within `internal/app`, `internal/stage`, and
|
|
`internal/config` remain cohesive;
|
|
- whether the largest files contain natural internal modules that are currently
|
|
obscured;
|
|
- whether stage and external-adapter implementations contain meaningful
|
|
duplication;
|
|
- whether tests are organized around durable behavior or coupled to incidental
|
|
implementation structure; and
|
|
- whether manifest, restore, publishing, and confined-filesystem invariants are
|
|
easy to locate, understand, and verify across package boundaries.
|
|
|
|
The deeper pass should also evaluate these specific modernization candidates:
|
|
|
|
- upgrading the maintained toolchain baseline from Go 1.25 to Go 1.27, subject
|
|
to ordinary compatibility and release validation;
|
|
- replacing custom root-confinement, no-follow traversal, safe cleanup, and
|
|
confined-read machinery with the standard library's `os.Root` operations
|
|
where their semantics match Narratio's reduced threat model;
|
|
- retaining Narratio-owned code where it still provides application-specific
|
|
crash durability, atomic replacement, no-replace directory promotion, mode
|
|
policy, bounded reads, or destructive-operation guardrails; and
|
|
- evaluating the `os.Process.WithHandle` API added in Go 1.26 as a way to avoid
|
|
reopening a Windows child process by PID before assigning it to an owned job
|
|
object, while recognizing that it may not replace suspended startup, job
|
|
object management, or initial-thread resumption;
|
|
- using the standard library's `slices` and `maps` packages to replace generic
|
|
cloning, membership, key extraction, sorting, and deduplication helpers where
|
|
those helpers do not encode domain-specific ordering or copy semantics;
|
|
- using `golang.org/x/sync/errgroup`, including its bounded-concurrency support,
|
|
to simplify transcription worker coordination, cancellation, and first-error
|
|
propagation while retaining Narratio-owned result aggregation and error
|
|
context;
|
|
- adopting `github.com/google/go-cmp/cmp` selectively in tests where structural
|
|
diffs would replace `reflect.DeepEqual` or hand-written comparisons with more
|
|
useful failure output;
|
|
- evaluating `github.com/gofrs/flock` after the `os.Root` design is understood,
|
|
to determine whether it can replace Unix and Windows lock primitives and
|
|
context-aware polling without losing lock metadata or desired file ownership
|
|
semantics; and
|
|
- considering a CLI framework such as Cobra only if command and flag evolution
|
|
proves costly enough to justify migration risk, dependency growth, and
|
|
possible changes to existing parsing, help, and error-output behavior.
|
|
|
|
The review may also document why a replacement is not appropriate. Current
|
|
low-confidence candidates include general configuration frameworks or schema
|
|
validators, generic atomic-file packages, provider-neutral object-storage
|
|
abstractions, retry or backoff packages, UUID or ULID packages, and generic
|
|
subprocess frameworks. Narratio's composition provenance, semantic validation,
|
|
durability guarantees, conditional object writes, identifier needs, and
|
|
tool-specific adapter contracts may leave little generic machinery for these
|
|
libraries to replace.
|
|
|
|
## Preliminary Complexity Findings
|
|
|
|
Complexity metrics are heuristics rather than findings of defects. Guard
|
|
clauses, validation branches, and explicit state transitions can score highly
|
|
while remaining appropriate. The following production-only measurements are
|
|
initial signals for focused code reading.
|
|
|
|
### Execution And Planning
|
|
|
|
`internal/app.executePlan` is the clearest outlier observed so far:
|
|
|
|
- approximately 456 lines;
|
|
- cyclomatic complexity of 79;
|
|
- cognitive complexity of 149; and
|
|
- more than 60 direct collaborators in the code graph.
|
|
|
|
The function currently spans invocation preparation, collaborator construction,
|
|
locking, session and run manifest initialization, resume decisions, stage
|
|
transitions, invalidation, terminal-failure persistence, and post-publish
|
|
cleanup. A deeper pass should look for existing lifecycle boundaries that could
|
|
be made explicit without redesigning the state machine during extraction.
|
|
|
|
`internal/app.Plan` is approximately 110 lines with cyclomatic complexity 27
|
|
and cognitive complexity 51. More importantly, it independently models parts
|
|
of the run/skip, resume-validation, stale-marking, and invalidation behavior
|
|
also present in execution. The audit should examine whether a shared, pure stage
|
|
transition model could reduce drift between planning and execution.
|
|
|
|
### Analyze Orchestration
|
|
|
|
The analyze implementation has two notable orchestration functions:
|
|
|
|
- `analyzeStage.Run` is approximately 252 lines with cyclomatic complexity 33
|
|
and cognitive complexity 47; and
|
|
- `executeAnalyzeArtifact` is approximately 259 lines with cyclomatic
|
|
complexity 28 and cognitive complexity 39.
|
|
|
|
`internal/stage/analyze.go` combines setup, catalog construction,
|
|
reconciliation, planning, per-artifact execution, state projection, dependency
|
|
invalidation, reuse aggregation, evidence registration, and result assembly.
|
|
Possible seams to investigate include execution-state initialization,
|
|
current/reused record projection, a per-artifact transaction, evidence
|
|
registration, and final result accumulation.
|
|
|
|
### Configuration Validation And Composition
|
|
|
|
`internal/config/validate.go` contains approximately 1,100 lines and has the
|
|
highest aggregate file complexity observed: cyclomatic complexity 264 and
|
|
cognitive complexity 394 across its functions. Notable functions include:
|
|
|
|
- `validateScriptorium`: approximately 117 lines, cyclomatic complexity 32,
|
|
cognitive complexity 74;
|
|
- `validateNotarius`: approximately 129 lines, cyclomatic complexity 29,
|
|
cognitive complexity 42; and
|
|
- `validateAudita`: approximately 54 lines, cyclomatic complexity 21,
|
|
cognitive complexity 34.
|
|
|
|
These scores are partly driven by explicit validation guards. A deeper review
|
|
should determine whether artifact-level, dependency-graph, path/output,
|
|
input-source, and variable validation can be separated while preserving precise
|
|
field-specific errors.
|
|
|
|
Composition complexity is concentrated in `internal/config/composition.go` and
|
|
`internal/config/pipeline_composition.go`. In particular,
|
|
`splitPipelineCompositionEnvelope` is approximately 87 lines with cyclomatic
|
|
complexity 21 and cognitive complexity 63. It combines YAML shape checking,
|
|
source-aware diagnostics, profile parsing, default-profile validation, cloning,
|
|
and removal of composition metadata. Structural decoding and semantic
|
|
validation may be separable, but the audit should preserve source provenance
|
|
and field ownership.
|
|
|
|
### Previous-Session Cache
|
|
|
|
`internal/previouscache.Resolve` is approximately 180 lines with cyclomatic
|
|
complexity 29 and cognitive complexity 60, within a package of only about 483
|
|
production lines. It combines configuration checks, current-state loading,
|
|
required and optional behavior, immutable-commit resolution, legacy candidate
|
|
probing, local-path construction, record creation, and sorting. Modern
|
|
immutable-commit resolution and legacy probing are distinct algorithms and may
|
|
form a useful extraction boundary.
|
|
|
|
### Additional Areas To Inspect
|
|
|
|
Lower-priority complexity concentrations include:
|
|
|
|
- `internal/stage/publish.go`, approximately 1,175 lines with aggregate
|
|
cognitive complexity 239, where file collection, output resolution,
|
|
publication, and commit assembly may be separable;
|
|
- `internal/fileops/directory.go`, approximately 555 lines with aggregate
|
|
cognitive complexity 184, some of which may be removed by the `os.Root`
|
|
evaluation;
|
|
- `internal/app/restore_plan.go`, particularly the approximately 129-line
|
|
`classifyRestoreAction`; and
|
|
- `internal/manifest/analyze_state.go`, whose moderately complex validation may
|
|
be justified by its ownership of explicit state invariants.
|
|
|
|
On the initial evidence, execution and shared plan/execution transition logic
|
|
should receive the first detailed review. Configuration and analyze
|
|
orchestration form the next tier, while their higher complexity may more often
|
|
reflect detailed domain rules.
|
|
|
|
These questions should be revisited with change-history analysis, focused code
|
|
reading, and maintenance experience before forming recommendations or creating
|
|
work items.
|