Record dead code and obsolete functionality audit findings
This commit is contained in:
263
docs/roadmap/audit/12-deadcode.md
Normal file
263
docs/roadmap/audit/12-deadcode.md
Normal file
@@ -0,0 +1,263 @@
|
|||||||
|
# Dead code and obsolete functionality audit
|
||||||
|
|
||||||
|
Reviewed at `9110aed`. Audita is a single-process Go CLI. CommandKit dispatches
|
||||||
|
the command and inspection surfaces. The application loads version 3 settings,
|
||||||
|
parses and normalizes the transcript, and passes it to a runner that chunks it
|
||||||
|
and coordinates proposals, validation, repair, and application. The PromptKit
|
||||||
|
adapter performs model calls. The CLI publishes the selected transcript format
|
||||||
|
and reports, with separate opt-in debug evidence.
|
||||||
|
[Package map](../../internal/overview.md) · [Pipeline](../../internal/pipeline.md)
|
||||||
|
|
||||||
|
## Scope and verification
|
||||||
|
|
||||||
|
The review used Go's `deadcode` analyzer from `x/tools` v0.52.0 on `./...`,
|
||||||
|
with and without test entry points, and Staticcheck 2026.2.2 for unused
|
||||||
|
declarations and ineffectual operations. Production reachability returned the
|
||||||
|
same 19 candidates for both shipped Linux targets, amd64 and arm64. The native
|
||||||
|
test-inclusive scan returned 16 candidates, including test-only declarations.
|
||||||
|
Typed reference counts helped locate write-only fields. The review traced
|
||||||
|
whole-value serialization, command registration, embedded assets, interface
|
||||||
|
assertions, and build selection before selecting findings. The FIFO test's
|
||||||
|
Linux and Darwin build constraint is intentional. `go vet -unreachable ./...`
|
||||||
|
produced no diagnostics, and `go test -count=1 ./...` passed on Go 1.27.3.
|
||||||
|
[Release targets](../../../releasekit.json#L7) · [Platform test](../../../internal/core/diagnostics/output_stream_test.go#L1)
|
||||||
|
|
||||||
|
## 1. Retire the test-only direct continuation path
|
||||||
|
|
||||||
|
`structuredoutput.Request.ContinueFrom` is read in `RoleClient.prepareCall`,
|
||||||
|
where it has its own opaque exchange check and passes the exchange to an
|
||||||
|
ordinary `Engine.Run`. The only request literals that set it are in
|
||||||
|
`conversation_test.go`. The supported correction-repair path passes the
|
||||||
|
captured proposal exchange to `Coordinator.Coordinate`. Its callback builds
|
||||||
|
requests without `ContinueFrom`, and the PromptKit coordinator supplies
|
||||||
|
history and owns the turn budget. A function-level scan sees the shared
|
||||||
|
request preparer as live, even though its continuation branch has no
|
||||||
|
production caller. [Request fields](../../../internal/framework/structuredoutput/call.go#L26) ·
|
||||||
|
[Direct continuation](../../../internal/framework/llm/adapter.go#L127) ·
|
||||||
|
[Direct callers in tests](../../../internal/framework/llm/conversation_test.go#L73) ·
|
||||||
|
[Runner repair](../../../internal/framework/runner/repair.go#L143) ·
|
||||||
|
[Coordinator adapter](../../../internal/framework/llm/coordinate.go#L13)
|
||||||
|
|
||||||
|
Move meaningful coverage of sibling isolation, carried context, and structural
|
||||||
|
repair onto coordinated calls, then remove the request field and direct
|
||||||
|
continuation branch. Keep exchange capture for proposals and keep the live
|
||||||
|
coordinator's cancellation, final-turn, and accounting checks.
|
||||||
|
[Second continuation fixture](../../../internal/framework/llm/conversation_test.go#L113) ·
|
||||||
|
[Coordinator tests](../../../internal/framework/llm/coordinate_test.go#L15) ·
|
||||||
|
[Subprocess repair test](../../../cmd/audita/correction_repair_integration_test.go#L173)
|
||||||
|
|
||||||
|
## 2. Remove proposal enrichment that the live handoff discards
|
||||||
|
|
||||||
|
`GenerateCandidates` appends both a plain proposal and an enriched proposal for
|
||||||
|
each decoded correction. The only production wrapper, `ExecuteModuleProposal`,
|
||||||
|
passes `StartIndex: 0` and forwards the plain proposals, segment references,
|
||||||
|
exchange, and operations. The runner creates its own enriched proposals and
|
||||||
|
assigns indices in ordered section collection. Only tests consume generation's
|
||||||
|
`Result.Enriched` or supply a nonzero `StartIndex`. Those tests can still pass
|
||||||
|
when the runner assigns incorrect run-level indices.
|
||||||
|
[Duplicate construction](../../../internal/framework/proposal_generation/generate.go#L189) ·
|
||||||
|
[Production wrapper](../../../internal/framework/proposal_generation/module_proposal.go#L55) ·
|
||||||
|
[Runner assignment](../../../internal/framework/runner/runner.go#L522) ·
|
||||||
|
[Generator index assertions](../../../internal/framework/proposal_generation/generate_test.go#L238)
|
||||||
|
|
||||||
|
Return one proposal representation from generation and use the runner tests
|
||||||
|
for global ordering. The adapter integration fixture can prepare validation
|
||||||
|
input explicitly or exercise the runner handoff. Review the debug metadata
|
||||||
|
before dropping `StartIndex`, since its `start_index` field is emitted with a
|
||||||
|
constant zero through the current module path. Keep the actual local segment
|
||||||
|
references and operation facts.
|
||||||
|
[Adapter fixture](../../../internal/framework/proposal_generation/adapter_integration_test.go#L76) ·
|
||||||
|
[Runtime ordering test](../../../internal/framework/runner/runner_test.go#L423) ·
|
||||||
|
[Debug metadata field](../../../internal/framework/proposal_generation/generate.go#L148)
|
||||||
|
|
||||||
|
## 3. Remove duplicate runner bookkeeping for unused module totals
|
||||||
|
|
||||||
|
`runModulePipeline` increments a module proposal count and flattens work-unit
|
||||||
|
operations into a second slice. `Run` copies that count into each `ModuleResult`.
|
||||||
|
It uses the flattened operations on failures and, on success, flattens the
|
||||||
|
enriched work-unit operations again after apply-time attribution. No current
|
||||||
|
consumer reads `ModuleResult.ProposalCount`. Only tests read
|
||||||
|
`ModuleResult.Operations`. Ordinary reports consume `RunOutput.WorkUnits`,
|
||||||
|
and the correction ledger uses the module's decisions and applied and skipped
|
||||||
|
changes. The CLI serializes those projections, so the JSON tags on the unused
|
||||||
|
module fields never turn them into output fields.
|
||||||
|
[Count accumulation](../../../internal/framework/runner/runner.go#L536) ·
|
||||||
|
[First operation copy](../../../internal/framework/runner/runner.go#L620) ·
|
||||||
|
[Second operation copy](../../../internal/framework/runner/runner.go#L264) ·
|
||||||
|
[Report work-unit input](../../../internal/framework/processreport/report.go#L51) ·
|
||||||
|
[CLI artifact projections](../../../internal/cli/process_pipeline.go#L56)
|
||||||
|
|
||||||
|
Remove the unused count and the module-level copies once the partial-failure
|
||||||
|
and accounting tests assert the corresponding work units. Retain the
|
||||||
|
per-module status and edit evidence consumed by reporting and the ledger.
|
||||||
|
[Ledger input](../../../internal/framework/processreport/correction_ledger.go#L70) ·
|
||||||
|
[Partial-progress tests](../../../internal/framework/runner/runner_test.go#L685)
|
||||||
|
|
||||||
|
## 4. Drop the unconsumed validation request envelope
|
||||||
|
|
||||||
|
`BuildLLMValidationRequest` constructs a `LLMValidationRequest` holding the
|
||||||
|
validator name, type, module key, module instance, replacement policy, and a
|
||||||
|
slice of items. The caller takes only `.Items`. Batch encoding serializes
|
||||||
|
local-reference items, and diagnostics source their labels directly from the
|
||||||
|
validator and runtime request. The envelope is never passed to JSON encoding.
|
||||||
|
Each item also stores `SegmentID`, which is assigned after the segment lookup,
|
||||||
|
never read, and explicitly excluded from JSON. The result's duplicate
|
||||||
|
`ValidatorName` likewise has no production reader. The runner reads the
|
||||||
|
validator's `Name()` when recording decisions.
|
||||||
|
[Envelope construction](../../../internal/framework/validators/llm_validators.go#L242) ·
|
||||||
|
[Runtime consumer](../../../internal/framework/validators/llm_validators.go#L61) ·
|
||||||
|
[Fields and wire exclusions](../../../internal/framework/validators/llm_models.go#L20) ·
|
||||||
|
[Payload construction](../../../internal/framework/validators/llm_prompt_variables.go) ·
|
||||||
|
[Decision recorder](../../../internal/framework/runner/runner.go#L775)
|
||||||
|
|
||||||
|
Have the builder return items and immediate decisions. Remove the write-only
|
||||||
|
fields after checking fixtures. Keep proposal indices for reconciliation and
|
||||||
|
the active diagnostic labels. The unused duplicate `framework/validators.Validator`
|
||||||
|
interface can also go. The module and runner use `contracts.Validator`.
|
||||||
|
[Unused interface](../../../internal/framework/validators/models.go#L95) ·
|
||||||
|
[Active interface](../../../internal/framework/contracts/contracts.go#L29) ·
|
||||||
|
[Payload parity test](../../../internal/framework/validators/llm_budget_test.go#L17)
|
||||||
|
|
||||||
|
## 5. Remove structured-call fields superseded by execution observations
|
||||||
|
|
||||||
|
The adapter still sets `Response.Provider` to a fixed string and copies prompt,
|
||||||
|
completion, and total token counts out of the run result. No production consumer
|
||||||
|
reads those response fields or serializes the whole response. The debug
|
||||||
|
execution projection gets usage from terminal events and the execution group.
|
||||||
|
`CallRecord.Prepared` and `CallRecord.FinalContent` are also populated even
|
||||||
|
though the observation collector copies only the call metadata. Interaction
|
||||||
|
artifacts get those payloads from `Response`, and a test currently asserts the
|
||||||
|
duplicated final content on the callback record.
|
||||||
|
[Response model](../../../internal/framework/structuredoutput/call.go#L52) ·
|
||||||
|
[Adapter assignments](../../../internal/framework/llm/adapter.go#L153) ·
|
||||||
|
[Collector projection](../../../internal/framework/llm/observations.go#L126) ·
|
||||||
|
[Debug execution rendering](../../../internal/framework/processreport/llm.go#L61) ·
|
||||||
|
[Test-only response and callback assertions](../../../internal/framework/llm/adapter_test.go#L167)
|
||||||
|
|
||||||
|
Remove the unconsumed response summaries and callback payload copies. Move
|
||||||
|
tests to the native usage observation and actual interaction payload paths.
|
||||||
|
Preserve `Response.Execution` for ordinary report counts and retain prepared
|
||||||
|
and final response evidence in the opt-in interaction artifacts.
|
||||||
|
[Observation mapping](../../../internal/framework/llm/observations.go#L139) ·
|
||||||
|
[Interaction payload](../../../internal/framework/proposal_generation/generate.go#L159)
|
||||||
|
|
||||||
|
`Failure.Kind` is a related, explicitly transitional field. The adapter sets
|
||||||
|
it in tandem with `ReasonInvalidOutputExhausted` and production uses the reason
|
||||||
|
and class. The remaining reads are from `IsMalformedError` in tests. The debug
|
||||||
|
call record independently derives its `failure` value from the reason. Move
|
||||||
|
the tests to the typed reason and remove the compatibility field and helper.
|
||||||
|
Keep the diagnostic `FailureKind` values, the safe failure message, and the
|
||||||
|
wrapped cause. [Transitional field and helper](../../../internal/framework/structuredoutput/failure.go#L17) ·
|
||||||
|
[Paired assignments](../../../internal/framework/llm/adapter.go#L279) ·
|
||||||
|
[Debug failure mapping](../../../internal/framework/llm/adapter.go#L86) ·
|
||||||
|
[Cause and classification tests](../../../internal/framework/structuredoutput/failure_test.go#L10)
|
||||||
|
|
||||||
|
## 6. Resolve shared prompt variables once per model call
|
||||||
|
|
||||||
|
`prepareCall` invokes `WithSharedVariables`, which loads all four embedded
|
||||||
|
instruction values and fills missing keys. The following loop reloads those
|
||||||
|
same assets and overwrites every one of those keys. For processing calls,
|
||||||
|
the first pass over shared instruction values is redundant. The helper is
|
||||||
|
still useful in CLI request inspection, where caller values take precedence.
|
||||||
|
[Processing merge](../../../internal/framework/llm/adapter.go#L123) ·
|
||||||
|
[Shared values and merge semantics](../../../internal/prompts/registry.go#L82) ·
|
||||||
|
[Inspection caller](../../../internal/cli/app_wiring.go#L100)
|
||||||
|
|
||||||
|
Use a single merge in the processing path that preserves the embedded-values
|
||||||
|
precedence and the missing `ProtectedTermsJSON` default. Keep the inspection
|
||||||
|
merge semantics and retain the existing prompt rendering coverage.
|
||||||
|
[Operator prompt test](../../../internal/framework/llm/adapter_test.go#L291)
|
||||||
|
|
||||||
|
## 7. Remove orphaned normalization and file helpers
|
||||||
|
|
||||||
|
The analyzer and repository references agree that `normalization.shouldMerge`,
|
||||||
|
`core/io.ValidateWellFormedJSON`, and `core/io.WriteFile` are unreachable in
|
||||||
|
production and tests. The normalizer calls `shouldMergeWithReason` so it can
|
||||||
|
count skipped merge reasons. The CLI reads the transcript and calls the schema
|
||||||
|
parser, which already validates JSON. Current output delivery goes through
|
||||||
|
`OutputSession` and has a different lifecycle from `os.WriteFile`.
|
||||||
|
[Unused merge predicate](../../../internal/core/normalization/normalize.go#L115) ·
|
||||||
|
[Live merge caller](../../../internal/core/normalization/normalize.go#L73) ·
|
||||||
|
[File helpers](../../../internal/core/io/files.go#L17) ·
|
||||||
|
[Live input boundary](../../../internal/cli/process_inputs.go#L46) ·
|
||||||
|
[Live delivery boundary](../../../internal/core/diagnostics/output_session.go#L273)
|
||||||
|
|
||||||
|
Delete the three declarations and retain the live merge checks, labeled input
|
||||||
|
read, and publication paths. Existing normalization and output tests cover
|
||||||
|
the behavior these helpers formerly duplicated or bypassed.
|
||||||
|
[Normalization limit test](../../../internal/core/normalization/normalize_test.go#L155) ·
|
||||||
|
[Publication tests](../../../internal/core/diagnostics/output_session_test.go#L207)
|
||||||
|
|
||||||
|
## 8. Remove the transcript parser variants that only tests call
|
||||||
|
|
||||||
|
The CLI calls `ParseSourceTranscriptJSON`, keeps the source for debug, then
|
||||||
|
converts it to the processing model before normalization. Neither
|
||||||
|
`ParseTranscriptJSON` nor `ParseTranscriptJSONLenient` is reached from the CLI.
|
||||||
|
The strict wrapper and its sequential-ID helper are used by schema tests. The
|
||||||
|
strict wrapper dereferences source IDs even though source input allows them to
|
||||||
|
be omitted. The lenient wrapper duplicates the live conversion and has a
|
||||||
|
test-only caller. Neither wrapper is an external Go API because the package is
|
||||||
|
internal. [Live load](../../../internal/cli/process_inputs.go#L46) ·
|
||||||
|
[Live conversion](../../../internal/cli/run.go#L12) ·
|
||||||
|
[Strict and lenient variants](../../../internal/core/schema/transcript.go#L65) ·
|
||||||
|
[Parser and round-trip tests](../../../internal/core/schema/transcript_test.go#L166)
|
||||||
|
|
||||||
|
Move the live conversion to the schema package if a shared seam is useful.
|
||||||
|
Use the supported source decoder and explicit field expectations to test
|
||||||
|
serialized transcripts, and exercise missing-ID conversion through the live
|
||||||
|
entry point. That leaves the optional source IDs, normalization's sequential
|
||||||
|
output, and both output formats intact. [Transcript input contract](../../integrations/transcript-glossary-files.md#transcript-json-contract) ·
|
||||||
|
[Boundary finding](11-boundaries.md#9-put-transcript-conversion-and-output-shape-at-their-owning-boundaries)
|
||||||
|
|
||||||
|
## 9. Clean up abandoned test support
|
||||||
|
|
||||||
|
`internal/testsupport` has no imports from Go code anywhere in the repository,
|
||||||
|
including tests. All four filesystem and redaction helpers are flagged by both
|
||||||
|
reachability runs. Staticcheck also reports the old subprocess configuration
|
||||||
|
view helper, the runner entry wait helper, and two runner structured-client
|
||||||
|
fixtures with no callers. Current configuration and redaction tests run with
|
||||||
|
their own fixtures. The unused test doubles differ from the explicit interface
|
||||||
|
conformance fixtures in `contracts_test.go`, whose methods exist to satisfy
|
||||||
|
compile-time type assertions.
|
||||||
|
[Orphan helper package](../../../internal/testsupport/files.go) ·
|
||||||
|
[Unused config view helper](../../../cmd/audita/main_integration_test.go#L319) ·
|
||||||
|
[Unused wait helper](../../../internal/framework/runner/runner_test.go#L503) ·
|
||||||
|
[Unused test clients](../../../internal/framework/runner/runner_test.go#L615) ·
|
||||||
|
[Compile-time fixture](../../../internal/framework/contracts/contracts_test.go#L64)
|
||||||
|
|
||||||
|
Delete the orphan package and unused fixtures. Keep the active assertions in
|
||||||
|
the configuration inspection, artifact, and runner suites.
|
||||||
|
|
||||||
|
## 10. Resolve the inherited progress flag for `process`
|
||||||
|
|
||||||
|
The built executable advertises `audita process --progress` as showing
|
||||||
|
progress messages. The process command registers no progress producer. The
|
||||||
|
pipeline attaches model observations only for debug capture, and the CLI's
|
||||||
|
processing summary and path messages are emitted at completion. In a local
|
||||||
|
normalization-only invocation, `--progress` and the default invocation returned
|
||||||
|
identical transcript bytes and empty stderr. The source trace is the evidence
|
||||||
|
for the model path too, since its observation hook is connected to the debug
|
||||||
|
artifact and no process progress callback is supplied.
|
||||||
|
[Command registration](../../../internal/cli/app_wiring.go#L84) ·
|
||||||
|
[Processing observation wiring](../../../internal/cli/process_pipeline.go#L20) ·
|
||||||
|
[Completion reporting](../../../internal/cli/process_output.go#L61)
|
||||||
|
|
||||||
|
Treat this as an exposed option with no Audita process behavior. Either attach
|
||||||
|
it to a real process event source or clarify its availability in process help
|
||||||
|
while retaining acceptance for existing scripts. The delegated inspection and
|
||||||
|
smoke commands have their own reporting behavior.
|
||||||
|
|
||||||
|
## Retained behavior
|
||||||
|
|
||||||
|
The version gate rejects older explicit configuration versions. The flags
|
||||||
|
marked for removal in the migration guide are absent from command help and
|
||||||
|
registration. `chunking.min_section_tokens` is documented, accepted and
|
||||||
|
validated, and the chunker explicitly
|
||||||
|
retains it for compatibility even though partitioning does not use it as a
|
||||||
|
target. Keep that setting. Also keep the generic validator estimator path,
|
||||||
|
which supplies the independent serialized reference in the existing budget
|
||||||
|
comparison, and the debug-only metadata reached through serialization.
|
||||||
|
[Migration guide](../../migrations/v3.md) ·
|
||||||
|
[Version gate](../../../internal/core/config/config.go#L131) ·
|
||||||
|
[Chunk compatibility field](../../../internal/core/chunking/sections.go#L27) ·
|
||||||
|
[Budget reference test](../../../internal/framework/validators/llm_budget_test.go#L14)
|
||||||
Reference in New Issue
Block a user