Close test-coverage gaps (storage, inspector integration, check composition)

[abegong]

Summary

A point-in-time audit of the test suite (done while defining the testing
approach in #38) found coverage solid at most boundaries but thin in a few
specific places. This issue records the audit and tracks closing those gaps. The
testing strategy this supports lives in
How we test.

Test counts below are approximate and current as of the audit (2026-06-24); treat
the table as a map, not a live metric.

Seam coverage (snapshot)

A katalyst check <selector> run flows through these boundaries:
config.Load -> project.Resolve -> storage.Items -> frontmatter.Parse ->
engine.checksFor -> checks.Check.Run -> output, with inspect.Inspect and
query.Predicate.Matches as siblings.

Seam	Boundary (identifier)	Test style	~Tests	Where
Frontmatter	frontmatter.Parse / Format -> *Document	unit, inline literals	28	internal/frontmatter/*_test.go
Config	config.Load(start) -> *Config	component, scaffolded .katalyst/	40	internal/config/config_test.go
Storage	storage.CollectionDefinition (Items / Unmatched / Reference)	unit, temp dirs	7	internal/storage/storage_test.go
Project	project.Project.Resolve(selectors) -> *Resolution	component, scaffolded repo	10	internal/project/project_test.go
Engine	engine.checksFor(collection, meta) -> []checks.Check	component	engine_test	cmd/engine_test.go
Check	checks.Check.Run(Context) []Violation (+ CollectionCheck)	unit per family, via checktest	54	internal/checks/*/
Registry / library	checks.Register / Build, CheckLibrary / SchemaLibrary	parity guards	registry_test	internal/checks/registry_test.go
Validator	jsonschema CompileSchema + Schema.Check	unit, rich fixture	9	internal/checks/jsonschema/jsonschema_test.go
Inspector	Source / CollectionInspector.Inspect(View, Params) Evidence	unit on evidence; registry parity	~20	internal/inspect/*_test.go
Query	query.ParseFilter(s) + Predicate.Matches(meta)	unit, table-driven	25	internal/query/*_test.go
CLI	cmd.NewRootCmd() end-to-end	integration: snapshot text + property behavior	121	cmd/*_test.go
Generated docs	cmd/gendocs + internal/examples + docs-gen-check	golden + drift gate	examples golden	internal/examples/run_test.go
Dogfood	katalyst check over .katalyst/ in CI	acceptance	CI step	.github/workflows/ci.yml

Gaps to close

Roughly in priority order:

1. Storage error paths. internal/storage is happy-path only: pattern
   matching, sorted listing, reference resolution. No coverage of permission
   errors, missing directories, or symlink loops.
2. Inspector Inspect() integration. Evidence computation is unit-tested
   (fields, body, source), but the Inspect() interface itself has a
   single integration test (CollectionView). Source-layer inspectors are not
   exercised end-to-end through the interface.
3. Check composition. Each check is unit-tested in isolation, but no test
   chains a base collection plus a matched variant plus multiple checks on one
   item, the path engine.checksFor actually produces.
4. Project resolution with variants. Resolve is tested for selector
   parsing and basic resolution, not for variant-predicate routing or the
   collection-scoped re-scan semantics.
5. Config-example compilation. Each check type ships a ConfigExample
   string in its descriptor; nothing asserts those examples actually parse and
   build.

CI gates beyond go test

go test -race -count=1 ./...; make build; make docs-gen-check (reference
and example drift); make docs-build then ./bin/katalyst check (broken-ref
catch + dogfood); go mod tidy drift.

Related

• Review all tests and define an opinionated testing approach #38 (review all tests / define the testing approach) — this audit was produced
  for it; the strategy graduated into how-we-test.md, and these gaps are the
  follow-on code work.
• Full worked-example coverage across check types and inspectors, gated by a completeness test #85 (full worked-example coverage) — a coverage gap of a different kind (docs
  examples per check type/inspector), tracked separately.