feat(compile_formal_docs): mirror docs/ subtree so formal docs can embed assets

[abitofhelp]

Summary

Prerequisite for adafmt#56. The SDS needs to embed architecture diagrams via image("../diagrams/foo.svg"), but compile_formal_docs.py copied .typ sources flat into the temp build directory — so any ../<dir>/ asset reference pointed outside the Typst project root and typst rejected it:

error: failed to load file (access denied)
  = hint: cannot read file outside of project root

Fix

Mirror the project's whole docs/ subtree into the temp build, overlay the shared templates next to the mirrored .typ sources, and compile each document with --root at the docs mirror:

• temp/docs/formal/ — the .typ sources + core.typ / utility.typ
• temp/docs/diagrams/ (and any other docs/ subdir) — mirrored assets
• typst compile --root temp/docs temp/docs/formal/<doc>.typ <project>/docs/formal/<doc>.pdf

Cross-directory asset references (../diagrams/...) now resolve inside the Typst root, while #import "core.typ" (a same-directory import) still works because the templates are overlaid next to the mirrored sources.

General docs-asset solution — any asset under docs/ is reachable, not just docs/diagrams/. No project-specific special case. Generated *.pdf files are excluded from the mirror (build outputs, not compile inputs).

Tests

tests/test_compile_formal_docs.py — new, 6 tests:

• find_project_root from the formal dir / returns None when absent.
• dry_run does not compile.
• plain formal doc compiles — regression guard; this path worked before the fix too.
• embedded-diagram doc compiles — the adafmt#56 regression. Fails against the pre-fix script with the exact "cannot read file outside of project root" error; passes after the fix.
• stale *.pdf under docs/ does not break the temp-mirror copy.

typst-dependent tests skipif cleanly when typst is not on PATH. Full suite: 139 passing (133 baseline + 6 new).

End-to-end verification

Ran the fixed script against adafmt's real docs/56-diagrams-sync-pdf branch (SDS with three #figure(image(...)) embeds):

OK: software_design_specification.typ -> software_design_specification.pdf
OK: software_requirements_specification.typ -> software_requirements_specification.pdf
OK: software_test_guide.typ -> software_test_guide.pdf
Done. 3 succeeded, 0 failed.

Consumer impact

compile_formal_docs.py is invoked by consumers' make docs-formal. The change is backward-compatible: a project whose formal docs reference no cross-directory assets compiles exactly as before (covered by the plain formal doc compiles regression test). The only behavioral change is that cross-directory docs/-relative asset references — which previously failed — now succeed.

Refs

• adafmt#56 — regenerate diagrams + sync formal docs (the consumer that needs this)