feat(rules): lib/project-rules.sh check/matches/sections/extract + suite
This commit is contained in:
1 parent
36dfee0b26
commit
abfa4167ea
2 files changed
+346
No files matched your search
@@ -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
|
||||
@@ -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 ]
|
||||
Reference in new issue
Block a user