Files
archie/tools/go.mod
T
sam e537447333 feat(tools): add contractaudit for standing contract-conformance reporting
Reachability (tools/reachaudit, epic archie-core-06ag) answers "is this code
in a shipped binary?". It cannot answer the complementary question: "does
every declared contract surface have a consumer, or a declaration that it
has none?". ratelimit was in the binary closure and called by nothing, which
reachability could not see.

tools/contractaudit classifies each subject of each declared surface as
CONSUMED, DECLARED-UNCONSUMED, UNDECLARED-UNCONSUMED, or STALE-DECLARATION,
and only the last two are findings. The declaration allowlist must match
reality exactly: a missing entry fails and so does an entry that outlived
its subject, because a stale allowlist is how a gate quietly stops checking
anything.

Surfaces: the two gRPC services, whose consumption is derived by scanning
adapter bodies for calls through the generated client, and the dashboard
HTTP API, matched between the registerXRoutes call sites and the path
literals the bundled client calls.

Findings on the current tree, all deliberate and now declared:
ListCaptures and ListUndispatchedCaptures are superseded by their streaming
variants -- staterpc's client calls StreamCaptures -- so no production
client reaches the unary RPCs.

Three bugs this tool found in itself, each recorded because each is the
class of error that makes a conformance check worse than none:

- Joining RPCs to adapter methods by name silently reported live RPCs as
  unconsumed, because adapters do not map one-to-one: StoreClient.Get calls
  GetSession, List calls ListSessions.
- Reflecting over the client value rather than the pointer reported zero
  methods, hence the whole surface unconsumed.
- Treating the asset mount and the health probes as dashboard API routes
  reported four healthy routes as undeclared; they have different consumers
  and are out of scope for this surface.

The consumer extractor fails loudly on a call shape it cannot parse rather
than under-reporting, and every check is negative-tested: a route, an RPC,
and a removed consumer are each injected, confirmed to fail for the right
reason, and reverted. The declaration staleness rule is tested too.

Advisory when run directly; task check runs it -strict. See
docs/prds/contract-conformance-audit.md.
2026-09-15 09:41:20 +10:00

37 lines
1.3 KiB
AMPL

module github.com/samcharles93/archie-core/tools
go 1.27.0
require (
github.com/invopop/jsonschema v0.14.0
github.com/samcharles93/archie-core v0.0.0-00010101000000-000000000000
)
require (
github.com/bahlo/generic-list-go v0.2.0 // indirect
github.com/buger/jsonparser v1.1.2 // indirect
github.com/dustin/go-humanize v1.0.1 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/mattn/go-isatty v0.0.24 // indirect
github.com/ncruces/go-strftime v1.0.0 // indirect
github.com/pb33f/ordered-map/v2 v2.3.1 // indirect
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
github.com/samcharles93/ai-sdk v0.1.32 // indirect
github.com/traefik/yaegi v0.16.1 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect
golang.org/x/net v0.58.0 // indirect
golang.org/x/sys v0.47.0 // indirect
golang.org/x/text v0.41.0 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20260904194346-d0f1323225a4 // indirect
google.golang.org/grpc v1.83.2 // indirect
google.golang.org/protobuf v1.36.12 // indirect
gopkg.in/yaml.v3 v3.0.1 // indirect
modernc.org/libc v1.75.7 // indirect
modernc.org/mathutil v1.7.1 // indirect
modernc.org/memory v1.12.1 // indirect
modernc.org/sqlite v1.58.0 // indirect
)
replace github.com/samcharles93/archie-core => ../