From abfa4167ea23a80f136f363d22543ec5f6c657ba Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 26 Oct 2026 17:41:07 +0100 Subject: [PATCH] feat(rules): lib/project-rules.sh check/matches/sections/extract + suite --- lib/project-rules.sh | 192 ++++++++++++++++++++++++++++++++ lib/tests/project-rules.test.sh | 154 +++++++++++++++++++++++++ 2 files changed, 346 insertions(+) create mode 100644 lib/project-rules.sh create mode 100644 lib/tests/project-rules.test.sh diff --git a/lib/project-rules.sh b/lib/project-rules.sh new file mode 100644 index 0000000..a592583 --- /dev/null +++ b/lib/project-rules.sh @@ -0,0 +1,192 @@ +#!/usr/bin/env bash +# lib/project-rules.sh — project-scope path rules (.claude/rules/.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 ` (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 rc 0 + the first hits, rc 1 none +# sections chars, line, heading per top-level ## section +# extract move one section to a rule +# emit 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() { # → 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" +} + +# → 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() { # → matching paths outside dependency dirs, rc 1 none + ( shopt -s globstar dotglob; compgen -G "$1" ) 2>/dev/null \ + | grep -Ev "$_RULES_DEPS" +} + +_rules_matching() { # → 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() { # → 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() { # → 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() { # → 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() { # → fence-aware count of "## h" + awk -v h="## $2" '/^```/ { fence = !fence } + !fence && $0 == h { n++ } + END { print n + 0 }' "$1" +} + +_rules_section_body() { # → 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() { # → 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() { # → 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() { # + 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() { # → 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" \ + " | sections | extract " \ + " | emit " >&2; return 2 ;; + esac +} + +if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then _project_rules_main "$@"; fi diff --git a/lib/tests/project-rules.test.sh b/lib/tests/project-rules.test.sh new file mode 100644 index 0000000..a94d5dd --- /dev/null +++ b/lib/tests/project-rules.test.sh @@ -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 ]