[quality] test: unit coverage for .github/scripts/docs-checks.py

[kubestellar-hive]

Claimed ground: projectbluefin/server, new files tests/unit/conftest.py and tests/unit/test_docs_checks.py, plus a test-unit recipe in Justfile. Functions under test: load_fm, validate_frontmatter, check_budget, check_stale_flags, check_internal_links, validate_skill in .github/scripts/docs-checks.py. Tracker cluster: quality/test-coverage for the server repo (no existing tracking issue — this repo had zero tests).

Why

server had no test directory and no unit tests of any kind. .github/scripts/docs-checks.py (186 lines) is a required PR gate: it enforces skill front-matter schema, doc line budgets, stale TODO/draft markers and internal link validity. A regression there either blocks every docs PR or silently stops enforcing the contract.

What

• tests/unit/conftest.py — re-imports the script by path per test and repoints ROOT/DOCS_DIR/SKILLS_DIR at tmp_path, so the module-level errors/warnings globals stay isolated.
• tests/unit/test_docs_checks.py — 50 cases:
  • load_fm: absent, valid, unterminated front-matter
  • validate_frontmatter: invalid YAML, non-mapping, unknown top key, missing/non-kebab/over-64-char/stem-mismatched name, missing/non-string/over-1024-char description, non-mapping metadata, unknown metadata key, bad metadata.type, non-stable status
  • check_budget: under, warn band, over, exact-max boundary
  • check_stale_flags: TODO/FIXME/XXX/HACK, draft marker, the three exempt filenames, and that exempt files still reject TODO
  • check_internal_links: http/https/mailto/anchor skips, valid relative link, broken .md link, root-absolute link, directory link with and without index.md/INDEX.md, existing and missing non-markdown targets
  • validate_skill: missing front-matter, well-formed skill, >500-line error, 300–500-line warning, stale marker
  • one invariant test that runs the real checker against the checked-in docs (currently passes)
• Justfile: just test-unit runs python3 -m pytest tests/unit -q.

Verification

$ pytest tests/unit -q
50 passed

Tests only — no production code, no workflow, no docs changed.

Note: a .github/workflows/unit-tests.yml to run this suite on PRs is not included; the bot token lacks the workflows permission. Filed separately as an issue.

---

Filed by quality agent (hold-gated mode) — do not merge, do not remove the hold label.

— hive: agent=quality backend=copilot model=claude-opus-5