Skip to content

Fail a check when docs or just recipes name paths and commands that don't exist #333

Description

@ooloth

Current state

Docs name files, commands, and identifiers that no longer exist, and nothing catches it until a reader wastes time on a dead reference. The justfile's status recipe invokes a hub-cli subcommand the binary does not define, and it still runs green because nothing checks it.

These are lookups rather than judgement calls, so they should fail a check instead of waiting for someone to read carefully. hub already runs scripts/check-banned-terms.sh and scripts/check-lint-inheritance.py from prek, so both the pattern and the wiring exist.

Ideal state

  • A check fails when a tracked markdown file names a repo-relative path that does not exist
  • It fails when a just recipe invokes a subcommand the binary does not define
  • It reports, without failing, every ADR whose status line claims the decision is implemented, so a human can confirm the code is actually there
  • It runs from prek alongside the existing checks, and from just check
  • scripts/README.md describes each check, and the description matches what the script does

Open decisions

  • Whether to also flag backticked identifiers in docs/ with no hit anywhere in the source. This would have caught several real cases, but many identifiers legitimately name external things. Measure the false-positive rate against the current docs before committing to it; if it is noisy, leave it to the handoff skill's judgement scans instead

Out of scope

  • Anything requiring judgement, which belongs in the handoff skill rather than a script
  • Scanning GitHub issue bodies. This runs offline in a pre-commit hook and must not depend on the network

Starting points

  • scripts/check-lint-inheritance.py — the existing Python check to model, including how it reports failures
  • prek.toml — where hooks are wired in
  • justfile — the status recipe naming a subcommand that does not exist

QA plan

  1. Run the script against hub as it stands — expect it to flag the just status recipe
  2. Add a line to a doc naming docs/does-not-exist.md, run the script — expect a failure naming the file and the line number
  3. Remove that line, run the script — expect a pass
  4. Commit a change touching a markdown file — expect the hook to run from prek without being invoked by hand
  5. Read scripts/README.md against the script's actual behaviour — expect every described check to exist and every implemented check to be described

Done when

A doc naming a path that does not exist, or a just recipe naming a subcommand that does not exist, fails a check that runs from prek.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions