refactor: replace positional-string args to Compute*Key with named-field structs

[Tgenz1213]

Summary

• cache.ComputeAnalysisKey and cache.ComputeSuggestionKey took 5 and 8 positional string parameters respectively, which the compiler can't catch if same-typed args (e.g. adrContent/fileContent, reasoning/quotedCode) get transposed at a call site.
• Introduces cache.AnalysisKeyInput and cache.SuggestionKeyInput named-field structs; both Compute*Key functions now take one of these instead of a flat positional list.
• internal/analysis/engine.go's two call sites and all internal/cache/cache_test.go / internal/analysis/analysis_test.go call sites updated to the new shape.

This is a pure signature refactor — hashParts receives the exact same values in the exact same order as before, so hash output (and cache-key stability/collision-resistance guarantees from #179/#182) is unchanged. No new ADR: this doesn't introduce a new architectural decision, just hardens an existing call-site convention.

Deviations from the plan

None — implemented exactly as proposed in the issue.

Test plan

• go build ./... passes
• go test ./... passes (all packages, including the exact-value hash-stability/collision tests in internal/cache/cache_test.go and internal/analysis/analysis_test.go, which would catch any field-order regression)
• golangci-lint run --timeout=5m reports 0 issues on the changed code (unrelated stdlib typecheck error present in this environment predates the change)
• Manual diff review confirms field order into hashParts is unchanged in both functions

Closes #183

🤖 Generated with Claude Code

[Copilot]

🔵 Needs a closer look

Add digest compatibility coverage and update the existing ADR documentation.

Pull request overview

Refactors cache-key APIs from positional strings to named input structs while preserving hash behavior.

Changes:

• Added AnalysisKeyInput and SuggestionKeyInput.
• Updated production and test call sites.
• Preserved field ordering and cache-key stability.

Review notes:

• Moderate: add fixed digest or compatibility tests for both key functions.
• Nit: update the existing ADR to document SuggestionKeyInput and Filename.

File summaries

File	Description
internal/cache/cache.go	Defines structured cache-key inputs and updated functions.
internal/cache/cache_test.go	Updates cache-key and round-trip tests.
internal/analysis/engine.go	Uses structured inputs at production call sites.
internal/analysis/analysis_test.go	Updates suggestion-key test fixtures.

Review details

Suppressed comments (2)

internal/cache/cache.go:92

• Changing this exported API leaves docs/arch/0017-suggestion-cache-key-namespace.md:17 documenting the old positional ComputeSuggestionKey call (and omitting Filename). Please update that existing ADR to use SuggestionKeyInput, otherwise its documented API no longer matches code that contributors can compile.

func ComputeSuggestionKey(in SuggestionKeyInput) string {

internal/cache/cache_test.go:56

• These tests only compare two calls using the same implementation, so they would still pass if this refactor accidentally reordered fields before calling hashParts while invalidating every existing cache key. Since preserving the digest is part of this refactor's contract, add a fixed expected digest (or a compatibility test against the pre-refactor field order) for each Compute*Key function.

	a := ComputeAnalysisKey(AnalysisKeyInput{ModelName: "gpt-4", ADRContent: "adr", FileContent: "code", SystemPrompt: "sys", UserPromptTemplate: "tmpl"})
	b := ComputeAnalysisKey(AnalysisKeyInput{ModelName: "gpt-4", ADRContent: "adr", FileContent: "code", SystemPrompt: "sys", UserPromptTemplate: "tmpl"})

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Tgenz1213]

Addressed both points from the Copilot review in ce8202a:

• Digest compatibility: added TestComputeAnalysisKey_MatchesPreRefactorDigest and TestComputeSuggestionKey_MatchesPreRefactorDigest, pinning each function's output to a fixed hex digest. Verified those digests against the pre-refactor: replace positional-string args to Compute*Key with named-field structs #183 positional implementation with identical inputs (checked out main's hashParts, called it with the same literal values in the old positional order) — confirmed they match exactly, so this closes the gap where the existing self-consistency tests would've passed even if the refactor had silently reordered fields.
• Stale ADR: updated docs/arch/0017-suggestion-cache-key-namespace.md's Decision section from the old positional ComputeSuggestionKey(modelName, adrContent, ...) signature to the new SuggestionKeyInput struct, and added the previously-undocumented Filename field with a pointer to why it's part of the key (fix: suggestion cache entries don't invalidate when the suggestion prompt changes #167).