A ### section ends at the next heading of level <= 3 outside a fence; a last ### gives its parent's trailing --- back. Bare headings stay ##.
244 lines
10 KiB
Bash
244 lines
10 KiB
Bash
#!/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 [--depth 2|3] <file> chars, line, heading per ## section
|
|
# (--depth 3 adds the ### subsections; a section
|
|
# ends at the next heading of level ≤ its own)
|
|
# extract <file> <heading> <out> <globs-json> move one section to a
|
|
# rule (bare heading = ##; "### title" = a subsection;
|
|
# a ### moved last keeps its parent's trailing ---)
|
|
# 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,
|
|
# no brace expansion: one glob per extension; a symlinked dir matches
|
|
# when the glob names it, globstar never descends into a symlink met
|
|
# under `**`;
|
|
# dotglob makes `*` match dotfiles, which the engine's matcher skips: a
|
|
# glob that only hits hidden paths passes here but never loads),
|
|
# dependency dirs excluded (unless the glob names one: `vendor/**` is a
|
|
# valid rule): 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
|
|
case "$1" in # a glob that names a dependency dir is not filtered
|
|
node_modules/*|.venv/*|venv/*|vendor/*|target/*|dist/*|build/*|.git/*)
|
|
( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null; return ;;
|
|
esac
|
|
( 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: must be one line:" \
|
|
"paths: [\"a\", \"b\"]"; 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() { # [--depth 2|3] <file> → chars, line, heading
|
|
local depth=2
|
|
if [ "${1:-}" = "--depth" ]; then depth="${2:-}"; shift 2; fi
|
|
case "$depth" in 2|3) ;; *)
|
|
echo "project-rules: --depth takes 2 or 3" >&2; return 2 ;; esac
|
|
[ $# -eq 1 ] \
|
|
|| { echo "project-rules: sections [--depth 2|3] <file>" >&2; return 2; }
|
|
[ -f "$1" ] || { echo "project-rules: $1 not found" >&2; return 2; }
|
|
awk -v depth="$depth" '
|
|
function flush2() {
|
|
if (h2 != "") printf "%d\t%d\t%s\n", c2, l2, h2; h2 = "" }
|
|
function flush3() {
|
|
if (h3 != "") printf "%d\t%d\t%s\n", c3, l3, h3; h3 = "" }
|
|
/^```/ { fence = !fence }
|
|
/^# / && !fence { flush3(); flush2() }
|
|
/^## / && !fence { flush3(); flush2(); h2 = $0; l2 = NR; c2 = 0 }
|
|
/^### / && !fence && depth == 3 { flush3(); h3 = $0; l3 = NR; c3 = 0 }
|
|
h2 != "" { c2 += length($0) + 1 }
|
|
h3 != "" { c3 += length($0) + 1 }
|
|
END { flush3(); flush2() }' "$1" | sort -t "$(printf '\t')" -k2,2n
|
|
}
|
|
|
|
_rules_heading_line() { # <heading arg> → "## t" | "### t" on stdout, rc 2
|
|
case "$1" in
|
|
'## '*|'### '*) printf '%s\n' "$1" ;;
|
|
'# '*|'####'*)
|
|
echo "project-rules: heading level must be ## or ###: $1" >&2
|
|
return 2 ;;
|
|
*) printf '## %s\n' "$1" ;;
|
|
esac
|
|
}
|
|
|
|
_rules_heading_count() { # <file> <heading line> → fence-aware count
|
|
awk -v h="$2" '/^```/ { fence = !fence }
|
|
!fence && $0 == h { n++ }
|
|
END { print n + 0 }' "$1"
|
|
}
|
|
|
|
_rules_section_body() { # <file> <heading line> → body, ---/blank trimmed
|
|
awk -v h="$2" '
|
|
BEGIN { lvl = index(h, " ") - 1 }
|
|
/^```/ { fence = !fence }
|
|
!fence && $0 == h { on = 1; next }
|
|
!fence && on && match($0, /^#+ /) && RLENGTH - 1 <= lvl { 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 line> → the file minus it
|
|
# a ### ended by a lower-level heading gives its trailing ---/blank run
|
|
# back to the source (the parent's closing separator); a ## keeps today's
|
|
# behaviour, its run travels with it
|
|
awk -v h="$2" '
|
|
BEGIN { lvl = index(h, " ") - 1 }
|
|
/^```/ { fence = !fence }
|
|
!fence && $0 == h { skip = 1; n = 0; next }
|
|
!fence && skip && match($0, /^#+ /) && RLENGTH - 1 <= lvl {
|
|
if (lvl == 3 && RLENGTH - 1 < lvl) for (i = 1; i <= n; i++) print buf[i]
|
|
skip = 0 }
|
|
skip { if ($0 == "" || $0 == "---") buf[++n] = $0; else n = 0; next }
|
|
{ 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" out="$3" globs="$4" hline tmp
|
|
hline=$(_rules_heading_line "$2") || return 2
|
|
[ "$(_rules_heading_count "$src" "$hline")" = 1 ] || {
|
|
echo "project-rules: heading must occur exactly once: $hline" >&2
|
|
return 2; }
|
|
[ -e "$out" ] && { echo "project-rules: $out exists" >&2; return 2; }
|
|
_rules_globs_all_match "$globs" || return 2
|
|
mkdir -p "$(dirname "$out")"
|
|
tmp=$(mktemp) || { echo "project-rules: no temp file" >&2; return 2; }
|
|
{ printf -- '---\npaths: %s\n---\n\n# %s\n' "$globs" "${hline#* }"
|
|
_rules_section_body "$src" "$hline"; } > "$out"
|
|
if ! { _rules_without_section "$src" "$hline" > "$tmp" \
|
|
&& cat "$tmp" > "$src"; }; then
|
|
rm -f "$tmp" "$out"
|
|
echo "project-rules: $src not rewritten, $out removed" >&2
|
|
return 2
|
|
fi
|
|
rm -f "$tmp"
|
|
echo "project-rules: moved '$hline' 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}" ;;
|
|
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 [--depth 2|3] <file> | extract <file>" \
|
|
"<heading> <out> <globs-json> | emit <skeleton> <out>" >&2
|
|
return 2 ;;
|
|
esac
|
|
}
|
|
|
|
if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _project_rules_main "$@"; fi
|