Rendered from docs/verifications/0002-a-fixture-tree-of-document-paths-symlinks-and-identifiers-proves-the-document-path-finding.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

A fixture tree of document paths, symlinks and identifiers proves the document path finding

Approach

The fixture tree at engine/crates/check/fixtures/document-path-target/ holds one note for each case of HW-AC-0003. engine/crates/check/fixtures/document-path-target.taxonomy.yml declares the kinds and relations the notes use. NOTE-FIX-b in notes/b.md is the target document that every path case names.

The cases, and the file that carries each one:

  • The decisive case. notes/a.md writes the path of NOTE-FIX-b under traces_to.
  • Spelling. notes/a2.md writes the path with ./ and a .. segment. notes/k.md writes it in two spellings in one entry.
  • Symlinks. src/alias.md is a symlink onto notes/b.md, and linked/ is a symlink onto notes/. notes/l.md and notes/l2.md write a path through each one.
  • Path and identifier together. notes/m.md writes the path and then NOTE-FIX-b.
  • The identifier form. notes/c.md writes NOTE-FIX-b.
  • Paths that name no document. notes/d.md traces to src/lib.rs, and notes/n.md traces to src/lib-link.rs, a symlink onto it. notes/e.md writes a wildcard, notes/g.md names a file with no identifier, and notes/j.md names a file with no kind. notes/h.md writes the path under cites, whose resolver is a fixture snapshot outside the tree. notes/f.md writes the path under governs.

engine/crates/check/tests/document_path_target.rs builds the census, the graph and one check run over the tree, with a pinned clock. Each of its seven tests reads the findings of relation.target.unresolved on one or more notes, and the graph's target for each entry.

cargo test -p headwater-check --test document_path_target --manifest-path engine/Cargo.toml --locked

The two source files under src/ hold no code that the engine runs. They exist so that a path to a source file, and a symlink onto one, resolve to a real entry on the tree.

What this does not cover

The tree proves the rule over one taxonomy, and that taxonomy declares two relations that admit a document and an anchor. It does not prove every relation of every package.

The test does not run headwater check from the command line. It calls the check library, so the CLI's output format for the finding is outside this test.

This document governs the test file and the fixture tree. A change to either one is a change to the test design, and a reader then checks this document against the change. The comment that cites HW-VER-0002 in the test file binds the cited_in edge.