feat(rules): lib/project-rules.sh check/matches/sections/extract + suite

This commit is contained in:
bchanot committed 2026-10-26 17:41:07 +01:00
1 parent 36dfee0b26
commit abfa4167ea
2 files changed
+346

No files matched your search

+192
View File
@@ -0,0 +1,192 @@
#!/usr/bin/env bash
# lib/project-rules.sh — project-scope path rules (.claude/rules/<name>.md),
# BDR-125 phase 0. One deterministic oracle for the make-test suite, the
# /onboard split mode, the onboarder and the scaffolder. Every subcommand
# takes an optional leading `-C <dir>` (a dispatched agent's cwd is the
# session's, never the project's):
# check [rules-dir] every path rule parses and every glob matches ≥1
# path; rc 2 with the culprit named
# matches <glob> rc 0 + the first hits, rc 1 none
# sections <file> chars, line, heading per top-level ## section
# extract <file> <heading> <out> <globs-json> move one section to a rule
# emit <skeleton> <out> the rule with the matching globs only (rc 1
# when none matches, nothing written)
# Globs match the WORKING TREE (compgen -G with globstar and dotglob,
# through symlinks, no brace expansion: one glob per extension),
# dependency dirs excluded: the engine matches the path the model reads,
# tracked or not; a typo matches nothing either way. A frontmatter line
# `# static-check: skip` exempts a rule whose files only exist mid-run. A
# rule without frontmatter or without `paths:` is an always-on rule:
# reported, never failed. No `head` after a producer: an early reader
# gives the writer SIGPIPE (rc 141 under pipefail).
_RULES_DEPS='(^|/)(node_modules|\.venv|venv|vendor|target|dist|build|\.git)/'
_rules_frontmatter() { # <file> → frontmatter body on stdout, rc 1 if none
awk 'NR == 1 && $0 != "---" { exit 1 }
NR > 1 && $0 == "---" { found = 1; exit }
NR > 1 { print }
END { exit found ? 0 : 1 }' "$1"
}
# <frontmatter text> → one glob per line. rc 1: no paths: line (always-on);
# rc 2: a paths: value that is not a non-empty JSON array of strings.
_rules_globs() {
local line arr
line=$(printf '%s\n' "$1" | grep -E '^paths:') || return 1
arr=${line#paths:}
printf '%s' "$arr" \
| jq -e 'type == "array" and length > 0 and all(type == "string")' \
>/dev/null 2>&1 || return 2
printf '%s' "$arr" | jq -r '.[]'
}
_rules_hits() { # <glob> → matching paths outside dependency dirs, rc 1 none
( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null \
| grep -Ev "$_RULES_DEPS"
}
_rules_matching() { # <globs, one per line> → JSON array of the matching ones
local g out=""
while IFS= read -r g; do
[ -n "$g" ] && _rules_hits "$g" >/dev/null && out="$out, \"$g\""
done <<< "$1"
[ -n "$out" ] || return 1
printf '[%s]\n' "${out#, }"
}
_rules_check_file() { # <rule.md> → rc 0 ok or always-on, rc 1 with culprits
local fm globs skip=0 g bad=0
fm=$(_rules_frontmatter "$1") \
|| { echo "$1: always-on (no frontmatter)"; return 0; }
globs=$(_rules_globs "$fm")
case $? in
1) echo "$1: always-on (no paths:)"; return 0 ;;
2) echo "$1: paths: is not a JSON array of strings"; return 1 ;;
esac
printf '%s\n' "$fm" | grep -qx '# static-check: skip' && skip=1
while IFS= read -r g; do
if [ "$skip" = 1 ]; then echo "$1: SKIP $g"; continue; fi
_rules_hits "$g" >/dev/null \
|| { echo "$1: glob matches nothing: $g"; bad=1; }
done <<< "$globs"
[ "$bad" = 0 ]
}
project_rules_check() { # [rules-dir] → rc 0 all ok, rc 2 with culprits named
local dir="${1:-.claude/rules}" f n=0 bad=0
[ -d "$dir" ] \
|| { echo "project-rules: 0 rule(s) ok ($dir absent)"; return 0; }
for f in "$dir"/*.md; do
[ -e "$f" ] || continue
n=$((n + 1))
_rules_check_file "$f" || bad=1
done
[ "$bad" = 0 ] || return 2
echo "project-rules: $n rule(s) ok"
}
project_rules_matches() { # <glob> → rc 0 + the first 3 hits, rc 1 none
# awk reads the pipe to its end: a `head` reader would SIGPIPE the
# producer on any glob with more than a pipe buffer of hits (rc 141).
_rules_hits "$1" | awk 'NR <= 3 { print } END { exit NR == 0 }' \
|| { echo "no match: $1" >&2; return 1; }
}
project_rules_sections() { # <file> → chars, line, heading per ## section
[ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; }
awk '
/^```/ { fence = !fence }
/^## / && !fence { if (h != "") printf "%d\t%d\t%s\n", c, l, h
h = $0; l = NR; c = 0 }
h != "" { c += length($0) + 1 }
END { if (h != "") printf "%d\t%d\t%s\n", c, l, h }' "$1"
}
_rules_heading_count() { # <file> <heading> → fence-aware count of "## h"
awk -v h="## $2" '/^```/ { fence = !fence }
!fence && $0 == h { n++ }
END { print n + 0 }' "$1"
}
_rules_section_body() { # <file> <heading> → body, trailing ---/blank trimmed
awk -v h="## $2" '
/^```/ { fence = !fence }
!fence && $0 == h { on = 1; next }
!fence && on && /^## / { exit }
on { buf[++n] = $0 }
END { while (n > 0 && (buf[n] == "" || buf[n] == "---")) n--
for (i = 1; i <= n; i++) print buf[i] }' "$1"
}
_rules_without_section() { # <file> <heading> → the file minus that section
awk -v h="## $2" '
/^```/ { fence = !fence }
!fence && $0 == h { skip = 1; next }
!fence && skip && /^## / { skip = 0 }
!skip { print }' "$1"
}
_rules_globs_all_match() { # <globs-json> → rc 0 valid and every glob matches
local globs g
globs=$(_rules_globs "paths: $1") || {
echo "project-rules: globs must be a JSON array of strings: $1" >&2
return 1; }
while IFS= read -r g; do
_rules_hits "$g" >/dev/null \
|| { echo "project-rules: glob matches nothing: $g" >&2; return 1; }
done <<< "$globs"
}
project_rules_extract() { # <file> <heading> <out.md> <globs-json>
local src="$1" heading="$2" out="$3" globs="$4" tmp
[ "$(_rules_heading_count "$src" "$heading")" = 1 ] || {
echo "project-rules: heading must occur exactly once: ## $heading" >&2
return 2; }
[ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; }
_rules_globs_all_match "$globs" || return 2
mkdir -p "$(dirname "$out")"
{ printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "$heading"
_rules_section_body "$src" "$heading"; } > "$out"
tmp=$(mktemp)
_rules_without_section "$src" "$heading" > "$tmp" && cat "$tmp" > "$src"
rm -f "$tmp"
echo "project-rules: moved '## $heading' to $out"
}
project_rules_emit() { # <skeleton.md> <out.md> → the rule, matching globs only
local fm globs kept
fm=$(_rules_frontmatter "$1") \
|| { echo "project-rules: $1: no frontmatter" >&2; return 2; }
globs=$(_rules_globs "$fm") \
|| { echo "project-rules: $1: no valid paths: array" >&2; return 2; }
kept=$(_rules_matching "$globs") \
|| { echo "project-rules: $1: no glob matches, not emitted" >&2; return 1; }
[ -e "$2" ] && { echo "project-rules: $2 exists" >&2; return 2; }
mkdir -p "$(dirname "$2")"
{ printf -- '---\npaths: %s\n---\n' "$kept"
awk 'body { print } NR > 1 && $0 == "---" { body = 1 }' "$1"; } > "$2"
echo "project-rules: emitted $2 paths: $kept"
}
_project_rules_main() {
set -uo pipefail
if [ "${1:-}" = "-C" ]; then
cd "${2:?dir}" 2>/dev/null \
|| { echo "project-rules: no dir $2" >&2; return 2; }
shift 2
fi
case "${1:-}" in
check) project_rules_check "${2:-.claude/rules}" ;;
matches) project_rules_matches "${2:?glob}" ;;
sections) project_rules_sections "${2:?file}" ;;
extract) project_rules_extract "${2:?file}" "${3:?heading}" "${4:?out}" \
"${5:?globs-json}" ;;
emit) project_rules_emit "${2:?skeleton}" "${3:?out}" ;;
*) echo "usage: project-rules.sh [-C dir] check [rules-dir] | matches" \
"<glob> | sections <file> | extract <file> <heading> <out>" \
"<globs-json> | emit <skeleton> <out>" >&2; return 2 ;;
esac
}
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _project_rules_main "$@"; fi
+154
View File
@@ -0,0 +1,154 @@
#!/usr/bin/env bash
# lib/tests/project-rules.test.sh — lib/project-rules.sh (check / matches /
# sections / extract / emit) and hooks/instructions-loaded.sh. Flip-tests
# on fixtures first (LRN-096), then the real check on this repo's rules.
set -u
ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
pass=0; fail=0
check() { if [ "$2" = "$3" ]; then pass=$((pass+1)); else fail=$((fail+1));
printf 'FAIL %s: got[%s] want[%s]\n' "$1" "$2" "$3"; fi; }
PR="$ROOT/lib/project-rules.sh"
FIX=$(mktemp -d); trap 'rm -rf "$FIX"' EXIT
cd "$FIX" || exit 1
mkdir -p .claude/rules src node_modules/x
echo x > src/app.ts
echo n > node_modules/x/a.test.js
# T1 a good rule passes
printf -- '---\npaths: ["src/**"]\n---\n\n# Src\nbody\n' > .claude/rules/good.md
bash "$PR" check >/dev/null; check T1-good-rule-passes "$?" 0
# T2 an unmatched glob fails, culprit named (flip test)
printf -- '---\npaths: ["src/**", "nowhere/**"]\n---\n\n# Bad\n' > .claude/rules/bad.md
out=$(bash "$PR" check); rc=$?
check T2-unmatched-glob-fails "$rc" 2
check T2b-culprit-named \
"$(printf '%s\n' "$out" | grep -c 'bad.md: glob matches nothing: nowhere/\*\*')" 1
printf -- '---\npaths: ["src/app.tz"]\n---\n\n# Typo\n' > .claude/rules/bad.md
bash "$PR" check >/dev/null; check T2c-literal-typo-fails "$?" 2
printf -- '---\npaths: ["**/*.test.*"]\n---\n\n# Deps\n' > .claude/rules/bad.md
out=$(bash "$PR" check); rc=$?
check T2d-dep-dir-only-is-no-match "$rc" 2
check T2e-dep-dir-culprit \
"$(printf '%s\n' "$out" | grep -c 'bad.md: glob matches nothing: \*\*/\*.test.\*')" 1
rm .claude/rules/bad.md
# T3 no frontmatter / no paths: = always-on info; a malformed paths: fails
printf '# No front\nbody\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3-no-frontmatter-is-always-on "$rc" 0
check T3b-reported "$(printf '%s\n' "$out" | grep -c 'nofm.md: always-on (no frontmatter)')" 1
check T3c-counted "$(printf '%s\n' "$out" | grep -c '2 rule(s) ok')" 1
printf -- '---\ntitle: x\n---\n\n# No paths\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3d-no-paths-is-always-on "$rc" 0
check T3e-reported "$(printf '%s\n' "$out" | grep -c 'nofm.md: always-on (no paths:)')" 1
printf -- '---\npaths: src/**\n---\n\n# Malformed\n' > .claude/rules/nofm.md
out=$(bash "$PR" check); rc=$?
check T3f-malformed-paths-fails "$rc" 2
check T3g-named \
"$(printf '%s\n' "$out" | grep -c 'nofm.md: paths: is not a JSON array of strings')" 1
rm .claude/rules/nofm.md
# T4 the skip marker passes an unmatched glob, and only in its own file
printf -- '---\npaths: ["nowhere/**"]\n# static-check: skip\n---\n\n# T\n' \
> .claude/rules/skip.md
out=$(bash "$PR" check); rc=$?
check T4-skip-marker-passes "$rc" 0
check T4b-skip-printed "$(printf '%s\n' "$out" | grep -c 'skip.md: SKIP nowhere/\*\*')" 1
printf -- '---\npaths: ["nowhere2/**"]\n---\n\n# U\n' > .claude/rules/other.md
bash "$PR" check >/dev/null; check T4c-skip-is-per-file "$?" 2
rm .claude/rules/skip.md .claude/rules/other.md
# T5 an absent dir is not an error; -C runs from elsewhere
rm -rf .claude/rules
out=$(bash "$PR" check); check T5-absent-dir-ok "$?" 0
check T5b-zero-rules "$(printf '%s' "$out" | grep -c '0 rule(s) ok')" 1
mkdir -p .claude/rules
printf -- '---\npaths: ["src/**"]\n---\n\n# Src\n' > .claude/rules/good.md
out=$(cd / && bash "$PR" -C "$FIX" check); rc=$?
check T5c-dash-C-rc "$rc" 0
check T5d-dash-C-counted "$(printf '%s' "$out" | grep -c '1 rule(s) ok')" 1
bash "$PR" -C /nonexistent-dir check 2>/dev/null; check T5e-dash-C-bad-dir "$?" 2
# T5f matches: hits on stdout, rc 1 and stderr line when none
out=$(bash "$PR" matches 'src/**'); rc=$?
check T5f-matches-rc "$rc" 0
check T5g-matches-hit "$(printf '%s\n' "$out" | grep -c '^src/app.ts$')" 1
err=$(bash "$PR" matches 'nope/**' 2>&1 >/dev/null); rc=$?
check T5h-no-match-rc "$rc" 1
check T5i-no-match-stderr "$err" 'no match: nope/**'
bash "$PR" matches '**/*.test.*' >/dev/null 2>&1; check T5j-dep-only-no-match "$?" 1
# T5k a glob with more than a pipe buffer of hits is still a match (no
# SIGPIPE from an early reader); T5m braces are not expanded by compgen
mkdir -p many
seq -f 'many/file-%04.0f-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' 1 3000 \
| xargs touch
bash "$PR" matches 'many/**' >/dev/null; check T5k-many-hits-rc "$?" 0
check T5l-three-lines "$(bash "$PR" matches 'many/**' | wc -l | tr -d ' ')" 3
bash "$PR" matches 'src/**/*.{ts,tz}' >/dev/null 2>&1
check T5m-brace-glob-no-match "$?" 1
# T6 sections lists headings with sizes, fence-aware
cat > CLAUDE.md <<'EOF'
# Proj
## Alpha
aaa
---
## Beta
```
## not a heading
```
bbb
## Gamma
g1
## Gamma
g2
EOF
out=$(bash "$PR" sections CLAUDE.md)
check T6-four-sections "$(printf '%s\n' "$out" | wc -l | tr -d ' ')" 4
check T6b-beta-line "$(printf '%s\n' "$out" | awk -F'\t' '$3=="## Beta"{print $2}')" 8
check T6c-alpha-chars "$(printf '%s\n' "$out" | awk -F'\t' '$3=="## Alpha"{print $1}')" 19
check T6d-fenced-not-listed "$(printf '%s\n' "$out" | grep -c 'not a heading')" 0
# T7 extract moves the section, writes the frontmatter, demotes the title
bash "$PR" extract CLAUDE.md 'Alpha' .claude/rules/alpha.md '["src/**"]' >/dev/null
check T7-extract-rc "$?" 0
check T7b-rule-frontmatter "$(sed -n '2p' .claude/rules/alpha.md)" 'paths: ["src/**"]'
check T7c-rule-title "$(sed -n '5p' .claude/rules/alpha.md)" '# Alpha'
check T7d-rule-body "$(sed -n '6p' .claude/rules/alpha.md)" 'aaa'
check T7e-trailing-sep-trimmed "$(tail -1 .claude/rules/alpha.md)" 'aaa'
check T7f-section-gone "$(grep -c '^## Alpha' CLAUDE.md)" 0
check T7g-beta-kept "$(grep -c '^## Beta' CLAUDE.md)" 1
check T7h-fenced-line-kept "$(grep -c '^## not a heading' CLAUDE.md)" 1
bash "$PR" check >/dev/null; check T7i-check-passes "$?" 0
# T8 extract refuses: missing heading, existing target, duplicate, fenced-only
bash "$PR" extract CLAUDE.md 'Alpha' .claude/rules/alpha2.md '["src/**"]' 2>/dev/null
check T8-missing-heading-rc "$?" 2
check T8b-nothing-written "$([ -e .claude/rules/alpha2.md ] && echo yes || echo no)" no
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/alpha.md '["src/**"]' 2>/dev/null
check T8c-existing-target-rc "$?" 2
check T8d-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
bash "$PR" extract CLAUDE.md 'Gamma' .claude/rules/gamma.md '["src/**"]' 2>/dev/null
check T8e-duplicate-heading-rc "$?" 2
check T8e2-both-gammas-kept "$(grep -c '^## Gamma' CLAUDE.md)" 2
bash "$PR" extract CLAUDE.md 'not a heading' .claude/rules/nah.md '["src/**"]' 2>/dev/null
check T8f-fenced-only-rc "$?" 2
check T8g-nothing-written "$(cd .claude/rules && printf '%s ' *)" 'alpha.md good.md '
# T9 extract refuses malformed globs and a glob that matches nothing
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md 'src/**' 2>/dev/null
check T9-bad-globs-rc "$?" 2
bash "$PR" extract CLAUDE.md 'Beta' .claude/rules/beta.md '["nowhere/**"]' 2>/dev/null
check T9b-unmatched-glob-rc "$?" 2
check T9c-nothing-written "$([ -e .claude/rules/beta.md ] && echo yes || echo no)" no
check T9d-beta-still-there "$(grep -c '^## Beta' CLAUDE.md)" 1
echo "PASS=$pass FAIL=$fail"
[ "$fail" -eq 0 ]