Files
archie/tools/contractaudit/audit.go
T
sam 1cddd97918 chore(fmt): adopt gofumpt wrapping in contractaudit
task fmt reformatted this file's fmt.Fprintf call; committing it rather than
letting it ride in the release commit, so the release diff stays the changelogs
alone. AGENTS.md: formatter changes are adopted verbatim.
2026-09-17 07:10:03 +00:00

297 lines
9.3 KiB
Go

package main
import (
"encoding/json"
"fmt"
"io"
"os"
"path/filepath"
"sort"
"strings"
)
// Class is a finding's conformance classification. Only Undeclared and Stale
// are findings; the other two are healthy states that are still reported so a
// reader can see the surface was actually walked rather than skipped.
type Class string
const (
// Consumed: a non-test client call site exercises the subject.
Consumed Class = "CONSUMED"
// DeclaredUnconsumed: named in the declaration allowlist with a reason and
// a tracker id. This is a status, not a defect -- tracked work whose only
// property is that its completion state was not visible anywhere.
DeclaredUnconsumed Class = "DECLARED-UNCONSUMED"
// Undeclared: nobody reaches the subject and nobody declared it. The finding.
Undeclared Class = "UNDECLARED-UNCONSUMED"
// Stale: a declaration naming a subject that is now consumed, or that no
// longer exists on the surface. A stale allowlist is how a gate quietly
// stops checking anything, so it fails like an undeclared entry.
Stale Class = "STALE-DECLARATION"
)
// Finding is one surface subject's conformance state. The shape is consumed by
// the text and JSON renderers and by the tests, so it is stable.
type Finding struct {
Surface string `json:"surface"`
Subject string `json:"subject"`
Class Class `json:"class"`
Evidence string `json:"evidence,omitempty"`
Tracker string `json:"tracker,omitempty"`
}
// Declaration is one allowlisted unconsumed subject.
type Declaration struct {
// Reason states the consequence, not "TODO". This file is the only place
// the debt is legible.
Reason string `json:"reason"`
// Tracker is the bead id or issue URL that owns the work.
Tracker string `json:"tracker,omitempty"`
}
// Declarations is the allowlist, keyed by surface name then subject. It must
// match reality exactly: a missing entry is an undeclared finding and an entry
// that is no longer true is a stale one.
type Declarations struct {
// Surfaces maps a surface name (e.g. "proto/state/v1") to its declared
// unconsumed subjects.
Surfaces map[string]map[string]Declaration `json:"surfaces"`
// BlindSpots names the checks that cannot be exact, with the reason. These
// are printed as-is and are never counted as findings -- the reachaudit
// rule that a static-analysis blind spot is labelled, not presented as dead.
BlindSpots []BlindSpot `json:"blindSpots,omitempty"`
}
// BlindSpot is a check limitation reported rather than silently applied.
type BlindSpot struct {
Surface string `json:"surface"`
Reason string `json:"reason"`
}
// Subject is one addressable element of a surface: an RPC, an HTTP route, a
// generated artifact.
type Subject struct {
// Name is the stable identity, e.g. "StateStoreService/TokensByDay" or
// "GET /api/summary".
Name string
// Evidence is where the subject is declared, as file:line where known.
Evidence string
// Consumed reports whether a client reaches it.
Consumed bool
// Consumer is the consuming call site, for the report.
Consumer string
}
// Surface is one declared contract surface and the subjects it exposes.
type Surface interface {
// Name is the surface's stable identifier, matching the declaration file.
Name() string
// Subjects enumerates the surface's declared subjects and their
// consumption state.
Subjects() ([]Subject, error)
}
// Audit walks every surface and classifies each subject against the
// declaration allowlist.
type Audit struct {
root string
declPath string
declarations Declarations
surfaces []Surface
}
// New builds an audit over the repository at root, reading the declaration
// allowlist from declPath (relative to root).
func New(root, declPath string) (*Audit, error) {
absRoot, err := filepath.Abs(root)
if err != nil {
return nil, fmt.Errorf("resolve repository root: %w", err)
}
absDecl := declPath
if !filepath.IsAbs(absDecl) {
absDecl = filepath.Join(absRoot, declPath)
}
declarations, err := loadDeclarations(absDecl)
if err != nil {
return nil, err
}
return &Audit{
root: absRoot,
declPath: absDecl,
declarations: declarations,
surfaces: []Surface{
newStateStoreSurface(absRoot),
newGatewayChatSurface(absRoot),
newWebUISurface(absRoot),
},
}, nil
}
// parseDeclarations decodes the allowlist from r. Decoding is separate from
// reading the file so its rules can be exercised without authoring a file.
func parseDeclarations(r io.Reader) (Declarations, error) {
var declarations Declarations
if err := json.NewDecoder(r).Decode(&declarations); err != nil {
return Declarations{}, fmt.Errorf("parse declarations: %w", err)
}
if declarations.Surfaces == nil {
declarations.Surfaces = map[string]map[string]Declaration{}
}
return declarations, nil
}
// loadDeclarations reads the allowlist. A missing file is not an error: an
// empty allowlist is the correct starting state and makes every unconsumed
// subject an undeclared finding, which is the honest first report.
func loadDeclarations(path string) (Declarations, error) {
f, err := os.Open(path)
if os.IsNotExist(err) {
return Declarations{Surfaces: map[string]map[string]Declaration{}}, nil
}
if err != nil {
return Declarations{}, fmt.Errorf("read declarations: %w", err)
}
defer f.Close()
return parseDeclarations(f)
}
// Run walks every surface and returns findings sorted by surface then subject.
func (a *Audit) Run() ([]Finding, error) {
var findings []Finding
for _, surface := range a.surfaces {
subjects, err := surface.Subjects()
if err != nil {
return nil, fmt.Errorf("surface %s: %w", surface.Name(), err)
}
findings = append(findings, classify(surface.Name(), subjects, a.declarations)...)
}
sort.Slice(findings, func(i, j int) bool {
if findings[i].Surface != findings[j].Surface {
return findings[i].Surface < findings[j].Surface
}
return findings[i].Subject < findings[j].Subject
})
return findings, nil
}
// classify applies the three-state rule, then the staleness rule in the
// opposite direction: every declaration must name a subject that still exists
// and is still unconsumed.
func classify(surface string, subjects []Subject, declarations Declarations) []Finding {
declared := declarations.Surfaces[surface]
findings := make([]Finding, 0, len(subjects)+len(declared))
seen := make(map[string]bool, len(subjects))
for _, subject := range subjects {
seen[subject.Name] = true
declaration, isDeclared := declared[subject.Name]
switch {
case subject.Consumed && isDeclared:
// The declaration outlived its subject's unconsumed state.
findings = append(findings, Finding{
Surface: surface,
Subject: subject.Name,
Class: Stale,
Evidence: fmt.Sprintf("declared unconsumed but consumed by %s", subject.Consumer),
Tracker: declaration.Tracker,
})
case subject.Consumed:
findings = append(findings, Finding{
Surface: surface,
Subject: subject.Name,
Class: Consumed,
Evidence: subject.Consumer,
})
case isDeclared:
findings = append(findings, Finding{
Surface: surface,
Subject: subject.Name,
Class: DeclaredUnconsumed,
Evidence: declaration.Reason,
Tracker: declaration.Tracker,
})
default:
findings = append(findings, Finding{
Surface: surface,
Subject: subject.Name,
Class: Undeclared,
Evidence: subject.Evidence,
})
}
}
// A declaration for a subject the surface no longer exposes is stale too:
// the allowlist is now permitting something that does not exist, which is
// indistinguishable from permitting something nobody checked.
for name, declaration := range declared {
if seen[name] {
continue
}
findings = append(findings, Finding{
Surface: surface,
Subject: name,
Class: Stale,
Evidence: "declared, but the surface no longer exposes this subject",
Tracker: declaration.Tracker,
})
}
return findings
}
// UndeclaredCount is the number of findings that should fail a strict run.
func UndeclaredCount(findings []Finding) int {
n := 0
for _, finding := range findings {
if finding.Class == Undeclared || finding.Class == Stale {
n++
}
}
return n
}
func writeJSON(out io.Writer, findings []Finding) error {
encoder := json.NewEncoder(out)
encoder.SetIndent("", " ")
return encoder.Encode(findings)
}
func writeText(out io.Writer, findings []Finding) {
bySurface := map[string][]Finding{}
var order []string
for _, finding := range findings {
if _, ok := bySurface[finding.Surface]; !ok {
order = append(order, finding.Surface)
}
bySurface[finding.Surface] = append(bySurface[finding.Surface], finding)
}
sort.Strings(order)
for _, surface := range order {
group := bySurface[surface]
counts := map[Class]int{}
for _, finding := range group {
counts[finding.Class]++
}
fmt.Fprintf(
out, "\n%s (%s %d, %s %d, %s %d, %s %d)\n",
surface,
Consumed, counts[Consumed],
DeclaredUnconsumed, counts[DeclaredUnconsumed],
Undeclared, counts[Undeclared],
Stale, counts[Stale],
)
for _, finding := range group {
if finding.Class == Consumed {
continue
}
line := fmt.Sprintf(" %-22s %s", finding.Class, finding.Subject)
if finding.Tracker != "" {
line += " [" + finding.Tracker + "]"
}
fmt.Fprintln(out, line)
if finding.Evidence != "" {
fmt.Fprintf(out, " %s\n", strings.TrimSpace(finding.Evidence))
}
}
}
}