Devour/internal/quality/docs_evidence.go

package quality

import "strings"

type docsEvidence struct {
	URLs       []string
	Rationale  string
	Confidence string
}

var defaultEvidenceByType = map[string]docsEvidence{
	"complexity_ast": {
		URLs:       []string{"https://go.dev/doc/effective_go", "https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "High complexity correlates with maintainability and defect risk; official style guidance recommends smaller focused functions.",
		Confidence: "0.82",
	},
	"god_function": {
		URLs:       []string{"https://go.dev/doc/effective_go", "https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "Large multi-responsibility functions usually violate readability and testability guidance.",
		Confidence: "0.84",
	},
	"unused_import": {
		URLs:       []string{"https://pkg.go.dev/cmd/go", "https://pkg.go.dev/go/importer"},
		Rationale:  "Unused imports break build hygiene and indicate stale code paths.",
		Confidence: "0.95",
	},
	"dead_code": {
		URLs:       []string{"https://pkg.go.dev/cmd/go", "https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "Unreachable or unused symbols increase maintenance overhead with no runtime value.",
		Confidence: "0.90",
	},
	"dead_code_enhanced": {
		URLs:       []string{"https://pkg.go.dev/cmd/go", "https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "Unreachable or unused symbols increase maintenance overhead with no runtime value.",
		Confidence: "0.90",
	},
	"duplication": {
		URLs:       []string{"https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "Duplication increases change cost and risk of inconsistent bug fixes.",
		Confidence: "0.80",
	},
	"single_use": {
		URLs:       []string{"https://go.dev/doc/effective_go", "https://go.dev/wiki/CodeReviewComments"},
		Rationale:  "Single-use abstractions can reduce clarity unless they encode reusable domain behavior.",
		Confidence: "0.74",
	},
	"test_coverage": {
		URLs:       []string{"https://go.dev/doc/tutorial/add-a-test", "https://pkg.go.dev/testing"},
		Rationale:  "Coverage gaps on changed code increase regression probability.",
		Confidence: "0.78",
	},
}

// AttachDocsEvidence annotates findings with docs evidence metadata.
func AttachDocsEvidence(language string, findings []Finding) []Finding {
	language = strings.ToLower(strings.TrimSpace(language))
	for i := range findings {
		ev, ok := defaultEvidenceByType[findings[i].Type]
		if !ok {
			continue
		}
		if findings[i].Metadata == nil {
			findings[i].Metadata = map[string]string{}
		}
		if len(ev.URLs) > 0 {
			findings[i].Metadata["docs_evidence_urls"] = strings.Join(ev.URLs, " | ")
		}
		if ev.Rationale != "" {
			findings[i].Metadata["docs_evidence_rationale"] = ev.Rationale
		}
		if ev.Confidence != "" {
			findings[i].Metadata["docs_evidence_confidence"] = ev.Confidence
		}
		if language != "" {
			findings[i].Metadata["docs_evidence_language"] = language
		}
	}
	return findings
}