mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-26 16:28:15 +00:00
Zhengchao An
d1db9a10cd
Agent-instruction and architecture docs had drifted from the code: - CLAUDE.md: slim to commands + pointers; fix wrong claim that `make pre-commit` is the full pre-PR gate (that is `make pre-pr`); drop stale pre-#3929 file paths and merged bug narratives - AGENTS.md: drop dead `rust-refactor-helper` skill rule and the hand-maintained (already stale) scoped-AGENTS index; link architecture docs from Sources of Truth - .github/AGENTS.md: replace the outdated copied CI command matrix with a pointer to ci.yml - crates/AGENTS.md: merge duplicated Testing sections - ARCHITECTURE.md: resolve the utils->config contradiction (edges are removed), mark volatile counts as snapshots, fix a bad path - docs/architecture: add README router; move one-shot plans/trackers (rebalance-decommission phases, migration-progress ledger, PR template) to docs/superpowers/plans with archive headers; fix stale source paths in kept inventories (core/sets.rs, core/pools.rs, store/mod.rs, startup_* split from #3671) - docs/operations/tier-ilm-debugging.md: extracted tier debugging playbook with corrected paths - scripts/check_doc_paths.sh: new guard failing pre-commit/pre-pr when instruction/architecture docs reference nonexistent file paths - .claude/skills: add tier-debug and arch-checks repo skills; .gitignore now keeps .claude/skills and docs/operations committable Verification: ./scripts/check_doc_paths.sh, ./scripts/check_architecture_migration_rules.sh (both pass) Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
70 lines
2.5 KiB
Bash
Executable File
70 lines
2.5 KiB
Bash
Executable File
#!/usr/bin/env bash
|
|
#
|
|
# Fail when an agent-instruction or architecture document references a
|
|
# repository file path that no longer exists. Keeps CLAUDE.md / AGENTS.md /
|
|
# ARCHITECTURE.md / docs/architecture honest after refactors move code.
|
|
#
|
|
# Checked files: all tracked AGENTS.md, CLAUDE.md, ARCHITECTURE.md, and
|
|
# docs/architecture/*.md (archived plans under docs/superpowers/plans are
|
|
# intentionally NOT checked — they are historical).
|
|
#
|
|
# A reference is any token starting with crates/, rustfs/, scripts/, docs/,
|
|
# .github/ or .config/ that ends in a known file extension. Tokens containing
|
|
# globs or placeholders, extensionless tokens (HTTP routes, directory
|
|
# references, org/repo shorthands), and lines containing URLs are skipped.
|
|
|
|
set -euo pipefail
|
|
|
|
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
|
cd "$ROOT_DIR"
|
|
|
|
FAILURES=0
|
|
|
|
doc_files() {
|
|
git ls-files 'AGENTS.md' '*/AGENTS.md' 'CLAUDE.md' 'ARCHITECTURE.md' 'docs/architecture/*.md'
|
|
}
|
|
|
|
check_file() {
|
|
local doc="$1"
|
|
# Path-like tokens; strip surrounding backticks/brackets/punctuation later.
|
|
# Lines with URLs are skipped wholesale: path fragments inside links are
|
|
# external, not repo paths.
|
|
# grep exits 1 on no matches; that must not kill the script under pipefail.
|
|
{ grep -vE 'https?://' "$doc" || true; } \
|
|
| { grep -oE '(crates|rustfs|scripts|docs|\.github|\.config)/[A-Za-z0-9_./-]+' || true; } \
|
|
| sed -e 's/[.,;:)]*$//' -e 's:/$::' \
|
|
| sort -u \
|
|
| while IFS= read -r ref; do
|
|
case "$ref" in
|
|
(*'*'*|*'<'*|*'>'*|*'{'*|*'}'*|*'…'*) continue ;;
|
|
esac
|
|
# Only verify references with a known file extension. Extensionless
|
|
# tokens are too often HTTP routes (rustfs/admin/v3/...), org/repo
|
|
# shorthands (rustfs/backlog), or glob prefixes — not repo paths.
|
|
case "$ref" in
|
|
(*.rs|*.md|*.sh|*.toml|*.yml|*.yaml|*.mak|*.proto) ;;
|
|
(*) continue ;;
|
|
esac
|
|
if [[ ! -e "$ref" ]]; then
|
|
printf 'stale path reference: %s -> %s\n' "$doc" "$ref" >&2
|
|
echo "FAIL" >> "$FAIL_MARKER"
|
|
fi
|
|
done
|
|
}
|
|
|
|
FAIL_MARKER="$(mktemp)"
|
|
trap 'rm -f "$FAIL_MARKER"' EXIT
|
|
|
|
while IFS= read -r doc; do
|
|
[[ -f "$doc" ]] && check_file "$doc"
|
|
done < <(doc_files)
|
|
|
|
if [[ -s "$FAIL_MARKER" ]]; then
|
|
count="$(wc -l < "$FAIL_MARKER" | tr -d ' ')"
|
|
printf '\n%s stale doc path reference(s) found.\n' "$count" >&2
|
|
printf 'Fix the doc to match the current tree, or update the moved code path.\n' >&2
|
|
exit 1
|
|
fi
|
|
|
|
printf 'doc path check passed\n'
|