🧪 needflow: a shared conformance corpus for the portable vocabulary

[chrisjsewell]

Slice 2 of the #1770 split (see the plan there); slice 1 merged as #1780.

What this is, and why it exists. The needflow portable option vocabulary is implemented
twice: here, and in ubCode's mermaid emitter. Two implementations of one user-facing
contract drift, and until now nothing structural would have made that drift visible — you
would find out from a user whose diagram looked different in the two tools.

This PR adds the sphinx-needs half of the only structural mitigation we have: a
conformance corpus. It is a set of fixture cases written in a language-neutral
vocabulary — each states some needs, some portable configuration, some directive options,
and the diagram source every engine must emit for them — duplicated verbatim into both
repositories under a checksummed manifest. Each repo's harness independently verifies
sha256(case file) == manifest entry for its own copy, so a local edit that skips the
manifest is a red test in that repo, and drift between copies shows up at re-sync as
differing checksums or corpus_version. Honest about the limit: there is no cross-repo CI
guard — the manifest makes drift visible, not impossible. ubCode is the repo of record;
edits land there first and this copy is a verbatim re-sync.

What is in the PR.

• tests/conformance/needflow/README.md — the corpus format spec, shipped inside the
  corpus so it travels with both copies, byte-identical in both.
• cases/*.yaml — five cases (below); manifest.json — corpus_version: 1 plus the
  sha256 of the README and every case, over line-ending-normalised bytes.
• test_conformance.py — the harness: builds a minimal Sphinx project per case per engine,
  pulls the emitted diagram source out of the doctree, normalises node hyperlink URLs to
  <NODE_URL:need_id> tokens, compares byte-exactly. It also enforces the format's own
  rules (unknown keys, tier-1 degradation entries, malformed legend expectations, checksum
  mismatch) — a runner that quietly accepts a malformed case is green while testing
  nothing, so each refusal has a test.
• .gitattributes pins the corpus to LF so the working-tree bytes stay canonical and a
  re-sync cannot carry a platform's line endings across; .pre-commit-config.yaml holds
  yamlfmt off the corpus (shared bytes — verified it would rewrite all five files and
  invalidate every checksum).
• tests/conftest.py — the plantuml command every test project renders with becomes one
  session fixture that test_app now uses too. CI has java and the vendored jar but no
  plantuml on PATH, so a project on the default command passes locally and fails there.

There is no production change. git diff master -- sphinx_needs/ is empty, and so is
docs/. Every case pins behaviour that already exists on master, so this PR cannot change
what any user's diagram looks like. It can only start failing when a later change moves
those bytes — which is the point.

The five cases.

case	what it pins
baseline-defaults	two needs, one link, no options: the no-warning fence, and the baseline every other case deviates from
node-id-injectivity	ids R-1 and R=1 stay two nodes with distinct edges — they used to fold to the same plantuml entity and silently lose a need (#1768)
percent-neutralisation	%%, quotes, angle brackets and braces in a title stay literal to the reader and are never truncated (depends on the graphviz label escaper from #1780)
edge-empty-label	a link type with an empty outgoing title, labelled: both engines here emit the label even when empty. Mermaid cannot (its pipe form is a parse error when empty), and the case says so — that divergence being explicit rather than discovered later is what the corpus is for
legend-engine-default	a bare :show_legend:: today's in-diagram legend, byte-exact, on both engines — including that plantuml lists every configured type while graphviz lists only the drawn ones

Reading and changing the corpus. Expectations are regenerated, never hand-written:
UBC_UPDATE_CORPUS=1 pytest tests/conformance/needflow rewrites the emitted sources into
the case files and restamps the manifest — then read the diff, because an expectation
accepted without reading is a snapshot, and a snapshot cannot tell you that what it
recorded is wrong. Regeneration is idempotent and a single pass converges. Any change to a
case or the README bumps corpus_version, lands in ubCode first, and comes here as the
paired re-sync.

One thing to know about the harness. The corpus format is deliberately wider than
what this repo can express today — it is the shared format, and Sphinx-Needs' surface is
a growing subset. The harness keeps the two apart: the SPEC_* tables are the format's
closed vocabulary; the mapping tables beside them are what this repo can currently build a
project from, carrying only rows a shipped case uses. A case naming something the format
defines but this repo has no surface for is refused with a message saying so — never
built as if the key were absent, which would leave the case asserting a diagram that was
never asked for the thing it is about. When a slice implements an option it adds its
mapping row together with the case that needs it. Two mapping tables ship empty on purpose
(project-level config keys, and the degradation registry) because nothing on master
populates them; with the degradation table empty, every warning a corpus build emits
counts as unexpected, which is what makes the fence a fence.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.64%. Comparing base (4e10030) to head (6d82bd9).
⚠️ Report is 329 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1781      +/-   ##
==========================================
+ Coverage   86.87%   90.64%   +3.76%     
==========================================
  Files          56       76      +20     
  Lines        6532    11340    +4808     
==========================================
+ Hits         5675    10279    +4604     
- Misses        857     1061     +204     

Flag	Coverage Δ
pytests	90.64% <ø> (+3.76%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.