Skip to content

docs: test and verification workflows are undocumented #65

Description

@OmarAlJarrah

Problem

The repo has unusually strong verification infrastructure that a contributor can't discover:

  1. The harness is invisible. cmd/morphic-harness (sweeps specs through no-panic / invariant / round-trip / determinism oracles), internal/harness, and ir/irverify are documented only in their doc.go files. README's Usage/Building/layout sections never mention them; nothing says when to run the harness (e.g. before submitting a compiler change) or what the oracles check.
  2. The golden/corpus workflow lives in one code comment. The -update flag works well (verified — regenerates byte-identically, clean tree), but README only says "the corpus test's -update flag" without naming the test or package; the exact command is a comment at compilers/openapi/conformance_test.go:24. The add-a-conformance-case recipe (paired X.yaml/X.golden.json + a table entry in TestConformance — a new .yaml without a table entry is silently un-asserted by that test) and the purpose of testdata/dangling/ are documented nowhere.
  3. Three fuzz targets, zero mentions. FuzzCompile, FuzzLowerSchema, FuzzCycleDetector exist and run fine, but "fuzz" appears nowhere in README/CLAUDE.md/docs, so contributors touching the compiler won't know to run them.

Proposed direction

A short "Testing & verification" section in README (or a testdata/README.md): one harness command with a sentence on the oracles, the concrete golden-regen command, the add-a-conformance-case recipe, and an example -fuzz invocation.

Acceptance

  • A contributor adding a compiler feature can find, from README alone: how to add a conformance case, regenerate goldens, run the harness, and run the fuzzers.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions