dtourolle
6b1aac477d
docs/ had 26 developer documents flat beside the manual, and the two audiences are very differently sized: most readers want the manual and the gesture reference, a few want the register, the designs and the measurements. The manual and gestures.md stay at the top; everything for someone changing the code moves to docs/dev/, and the two documents that name their own successors — the v0.1 milestone and the UI-refinement plan — go to docs/dev/archive/ rather than being deleted, since both are still cited. docs/README.md is the index, users first. Every reference follows: code comments, Cargo manifests, the workflows, the pre-commit hook, the bench and traceability tools (which locate the repo root by docs/dev/requirements.md now), packaging, the Docker READMEs, CLAUDE.md, CONTRIBUTING.md and the README. The matrix links one level deeper and is regenerated. Links out of the moved documents into the tree gain a level; a link checker over every Markdown file finds none broken.
68 lines
2.7 KiB
Bash
Executable File
68 lines
2.7 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
# Keep the generated artefacts in step with the tags in the tree.
|
|
#
|
|
# Two of them now, from the same scanner: the requirements matrix and the
|
|
# gesture vocabulary. Both are generated *from* the tree and cite line numbers
|
|
# in it, so both go stale on any commit that moves a line — a `cargo fmt` sweep
|
|
# above all, but equally a commit that merely adds a paragraph above a tag.
|
|
#
|
|
# The gate regenerates the matrix in CI and fails if the result differs from
|
|
# what is committed. That is the right check — a matrix that disagrees with the
|
|
# tree is worse than none, because it is read as current — but it fails *after*
|
|
# a push, on a commit that is otherwise fine, and it has now done so on six
|
|
# commits in a row because adding a `TRACES:` tag and regenerating the matrix
|
|
# are two actions and only the first is on anyone's mind.
|
|
#
|
|
# So it happens here instead, where the tags are being changed.
|
|
#
|
|
# Only when something that can carry a tag is staged: a commit touching
|
|
# workflows, packaging or the matrix itself pays nothing.
|
|
set -euo pipefail
|
|
|
|
staged="$(git diff --cached --name-only --diff-filter=ACMR)"
|
|
if ! grep -qE '\.(rs|slint|yaml|md)$' <<< "${staged}"; then
|
|
exit 0
|
|
fi
|
|
# The artefacts are generated from the tree, so regenerating them because one
|
|
# was itself edited would be circular.
|
|
case "$(tr -d '[:space:]' <<< "${staged}")" in
|
|
docs/dev/traceability.md | docs/gestures.md | ui/dr-ui/src/gesture_book.rs)
|
|
exit 0
|
|
;;
|
|
esac
|
|
|
|
repo="$(git rev-parse --show-toplevel)"
|
|
cd "${repo}"
|
|
|
|
# Quiet unless it has something to say. A hook that prints on every commit is
|
|
# a hook people start passing --no-verify to.
|
|
if ! cargo run -q -p traceability -- report >/dev/null 2>&1; then
|
|
echo "pre-commit: could not run the traceability report; leaving the matrix alone" >&2
|
|
exit 0
|
|
fi
|
|
|
|
if ! git diff --quiet -- docs/dev/traceability.md; then
|
|
git add docs/dev/traceability.md
|
|
echo "pre-commit: regenerated docs/dev/traceability.md and staged it"
|
|
fi
|
|
|
|
# The gesture vocabulary, same discipline.
|
|
#
|
|
# **Failure here is reported and not swallowed**, unlike the matrix above. A
|
|
# matrix that will not build leaves the previous one in place, which is merely
|
|
# stale; a malformed `GESTURE:` block means a gesture the user is about to be
|
|
# told about in the wrong words, or not at all. The gate would catch it in CI
|
|
# either way — this is only about catching it a push earlier.
|
|
if ! out="$(cargo run -q -p traceability -- gestures 2>&1)"; then
|
|
echo "pre-commit: the gesture scan failed — the tags below need fixing" >&2
|
|
echo "${out}" >&2
|
|
exit 1
|
|
fi
|
|
|
|
for f in docs/gestures.md ui/dr-ui/src/gesture_book.rs; do
|
|
if ! git diff --quiet -- "${f}"; then
|
|
git add "${f}"
|
|
echo "pre-commit: regenerated ${f} and staged it"
|
|
fi
|
|
done
|