✨ NEW: enforce mounted-directive path confinement (path_check)

[ubmarco]

Summary

Adds path confinement for mounted bundles: a directive inside a mounted bundle that references a file outside the bundle root now fails the build by default, keeping bundles self-contained and portable.

Directives resolve file paths relative to the document's own location, which for a mounted doc is the bundle on disk — so relative references resolve inside the bundle. Two shapes escape: a leading-slash path (/foo, "absolute from the source root" = the host srcdir) and a .. climb above the bundle root. Either drags an outside file into the host build (and, for asset directives, copies it into the host's _images/_downloads output, risking collisions with host files). The check is directive-agnostic — it inspects env.dependencies for each mounted doc — so it covers literalinclude, include, csv-table/raw (:file:), image, figure, graphviz, uml, mermaid, and any other directive that records a file dependency.

Config

New per-mount path_check in ubproject.toml: "error" (default — fail the build), "warn" (log a warning; escalates under -W), or "off" (disable for that mount).

Behavior change: a bundle that today references a file via a leading slash or .. will now fail by default; set path_check = "warn"/"off" to opt out.

Tests

• tests/test_path_directives.py (new): happy-path resolution for all nine file-referencing directives (host-side decoy proves bundle-relative-not-host resolution; renderer-independent — mermaid raw, plantuml/graphviz asserted via the recorded dependency), the two leak boundaries, and enforcement (error/warn/off, directive-agnostic, file-list mode, per-mount).
• tests/test_config.py: path_check validation + parse round-trip.
• tests/test_example.py: the Bazel example's api-foo bundle now exercises all nine directives end-to-end under -nW.

Docs / changelog

• docs/source/configuration.rst: new path_check option row + a "Path confinement" section.
• docs/source/changelog.rst: Unreleased entry.

Code quality

uv run prek run --all-files passes; uv run --group ty ty check clean; non-bazel suite green (132); Bazel e2e green (with dot/java/plantuml available).

Note: overlaps with #6 in tests/example/ (api-foo BUILD.bazel, docs/conf.py, README.md, test_example.py); whichever merges second will need a small conflict resolution.