Files
audita/docs/roadmap/audit/12-deadcode.md

264 lines
17 KiB
Markdown

# 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)