@lvlup-sw/exarchos 2.0.1

package/scripts/check-polish-scope.sh

@@ -0,0 +1,245 @@
+#!/usr/bin/env bash
+# Check Polish Scope
+# Checks if polish scope has expanded beyond limits.
+# Replaces "Scope Expansion Triggers" prose with deterministic validation.
+#
+# Usage: check-polish-scope.sh --repo-root <path> [--base-branch main]
+#
+# Exit codes:
+#   0 = scope OK (stay polish)
+#   1 = scope expanded (switch to overhaul)
+#   2 = usage error (missing required args)
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+REPO_ROOT=""
+BASE_BRANCH="main"
+
+usage() {
+    cat << 'USAGE'
+Usage: check-polish-scope.sh --repo-root <path> [--base-branch main]
+
+Required:
+  --repo-root <path>      Path to the git repository root
+
+Optional:
+  --base-branch <branch>  Base branch to diff against (default: main)
+  --help                  Show this help message
+
+Exit codes:
+  0  Scope OK — within polish limits
+  1  Scope expanded — switch to overhaul
+  2  Usage error (missing required args)
+
+Expansion triggers checked:
+  - File count > 5 (modified files via git diff)
+  - Module boundaries crossed (>2 top-level dirs modified)
+  - New test files needed (impl files without test counterparts)
+  - Architectural docs needed (detected heuristically)
+
+  Note: Assumes co-located tests (foo.test.ts alongside foo.ts)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --repo-root requires a path argument" >&2
+                exit 2
+            fi
+            REPO_ROOT="$2"
+            shift 2
+            ;;
+        --base-branch)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --base-branch requires a branch name" >&2
+                exit 2
+            fi
+            BASE_BRANCH="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$REPO_ROOT" ]]; then
+    echo "Error: --repo-root is required" >&2
+    usage >&2
+    exit 2
+fi
+
+# ============================================================
+# DEPENDENCY CHECK
+# ============================================================
+
+if ! command -v git &>/dev/null; then
+    echo "Error: git is required but not installed" >&2
+    exit 2
+fi
+
+# ============================================================
+# CHECK FUNCTIONS
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+RESULTS=()
+TRIGGERS_FIRED=()
+
+check_pass() {
+    local name="$1"
+    RESULTS+=("- **PASS**: $name")
+    CHECK_PASS=$((CHECK_PASS + 1))
+}
+
+check_fail() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **FAIL**: $name — $detail")
+    else
+        RESULTS+=("- **FAIL**: $name")
+    fi
+    CHECK_FAIL=$((CHECK_FAIL + 1))
+}
+
+# ============================================================
+# GET MODIFIED FILES
+# ============================================================
+
+cd "$REPO_ROOT"
+
+# Get list of files modified compared to base branch
+MODIFIED_FILES=()
+while IFS= read -r line; do
+    [[ -n "$line" ]] && MODIFIED_FILES+=("$line")
+done < <(git diff --name-only "$BASE_BRANCH"...HEAD 2>/dev/null || git diff --name-only "$BASE_BRANCH" HEAD 2>/dev/null || true)
+
+FILE_COUNT=${#MODIFIED_FILES[@]}
+
+# ============================================================
+# TRIGGER 1: File count > 5
+# ============================================================
+
+if [[ $FILE_COUNT -le 5 ]]; then
+    check_pass "File count within limit ($FILE_COUNT <= 5)"
+else
+    check_fail "File count exceeds limit" "$FILE_COUNT files modified (max 5)"
+    TRIGGERS_FIRED+=("File count ($FILE_COUNT) exceeds limit of 5")
+fi
+
+# ============================================================
+# TRIGGER 2: Module boundaries crossed (>2 top-level dirs)
+# ============================================================
+
+# Bash 3 compatible — no associative arrays
+MODULE_LIST=""
+for f in "${MODIFIED_FILES[@]}"; do
+    top_dir="$(echo "$f" | cut -d'/' -f1)"
+    if ! echo "$MODULE_LIST" | grep -qF "|$top_dir|"; then
+        MODULE_LIST="${MODULE_LIST}|$top_dir|"
+    fi
+done
+MODULE_COUNT=0
+MODULE_NAMES=""
+if [[ -n "$MODULE_LIST" ]]; then
+    MODULE_NAMES="$(echo "$MODULE_LIST" | tr '|' '\n' | sort -u | grep -v '^$' | tr '\n' ' ')"
+    MODULE_COUNT="$(echo "$MODULE_LIST" | tr '|' '\n' | sort -u | grep -vc '^$' || true)"
+fi
+
+if [[ $MODULE_COUNT -le 2 ]]; then
+    check_pass "Module boundaries OK ($MODULE_COUNT top-level dirs)"
+else
+    check_fail "Module boundaries crossed" "$MODULE_COUNT top-level dirs: $MODULE_NAMES"
+    TRIGGERS_FIRED+=("Module boundaries crossed ($MODULE_COUNT dirs: $MODULE_NAMES)")
+fi
+
+# ============================================================
+# TRIGGER 3: New test files needed
+# ============================================================
+
+MISSING_TESTS=()
+for f in "${MODIFIED_FILES[@]}"; do
+    # Only check .ts implementation files
+    if [[ "$f" == *.ts && "$f" != *.test.ts && "$f" != *.d.ts ]]; then
+        test_file="${f%.ts}.test.ts"
+        if [[ ! -f "$test_file" ]]; then
+            MISSING_TESTS+=("$f")
+        fi
+    fi
+done
+
+if [[ ${#MISSING_TESTS[@]} -eq 0 ]]; then
+    check_pass "Test coverage OK (all impl files have test counterparts)"
+else
+    check_fail "New test files needed" "${#MISSING_TESTS[@]} impl files without tests: ${MISSING_TESTS[*]}"
+    TRIGGERS_FIRED+=("New test files needed for ${#MISSING_TESTS[@]} files")
+fi
+
+# ============================================================
+# TRIGGER 4: Architectural docs needed (heuristic)
+# ============================================================
+
+NEEDS_ARCH_DOCS=false
+for f in "${MODIFIED_FILES[@]}"; do
+    # Heuristic: if modifying files in multiple top-level dirs with structural changes
+    if [[ "$f" == *"index.ts" || "$f" == *"types.ts" || "$f" == *"interface"* ]]; then
+        if [[ $MODULE_COUNT -gt 1 ]]; then
+            NEEDS_ARCH_DOCS=true
+            break
+        fi
+    fi
+done
+
+if [[ "$NEEDS_ARCH_DOCS" == false ]]; then
+    check_pass "No architectural docs needed"
+else
+    check_fail "Architectural documentation likely needed" "Structural files modified across modules"
+    TRIGGERS_FIRED+=("Architectural documentation needed")
+fi
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Polish Scope Check Report"
+echo ""
+echo "**Repository:** \`$REPO_ROOT\`"
+echo "**Base branch:** $BASE_BRANCH"
+echo "**Files modified:** $FILE_COUNT"
+echo "**Modules touched:** $MODULE_COUNT (${MODULE_NAMES:-none})"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    echo "$result"
+done
+
+echo ""
+echo "---"
+echo ""
+
+if [[ ${#TRIGGERS_FIRED[@]} -eq 0 ]]; then
+    echo "**Result: SCOPE OK** — All within polish limits"
+    exit 0
+else
+    echo "**Result: SCOPE EXPANDED** — Switch to overhaul track"
+    echo ""
+    echo "Triggers fired:"
+    for trigger in "${TRIGGERS_FIRED[@]}"; do
+        echo "  - $trigger"
+    done
+    exit 1
+fi

package/scripts/check-property-tests.sh

@@ -0,0 +1,167 @@
+#!/usr/bin/env bash
+# check-property-tests.sh
+# Verifies that tasks requiring property-based tests have PBT patterns in the implementation.
+# Exit 0 = pass, 1 = fail (missing PBT), 2 = usage error
+
+set -euo pipefail
+
+# ─── Usage ──────────────────────────────────────────────────────────────────
+
+usage() {
+    cat <<EOF
+Usage: check-property-tests.sh --plan-file <path> --worktree-dir <path>
+
+Verifies that plan tasks with propertyTests: true have property-based test
+patterns in the worktree.
+
+Arguments:
+  --plan-file      Path to plan JSON file containing tasks with testingStrategy
+  --worktree-dir   Path to the worktree directory to scan for PBT patterns
+
+Exit Codes:
+  0  All PBT-required tasks have property test patterns
+  1  One or more PBT-required tasks lack property test patterns
+  2  Usage error (missing arguments)
+EOF
+}
+
+# ─── Arg Parsing ────────────────────────────────────────────────────────────
+
+PLAN_FILE=""
+WORKTREE_DIR=""
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --plan-file)
+            PLAN_FILE="${2:-}"
+            shift 2 || { echo "Error: --plan-file requires a value" >&2; exit 2; }
+            ;;
+        --worktree-dir)
+            WORKTREE_DIR="${2:-}"
+            shift 2 || { echo "Error: --worktree-dir requires a value" >&2; exit 2; }
+            ;;
+        --help|-h)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument: $1" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$PLAN_FILE" || -z "$WORKTREE_DIR" ]]; then
+    echo "Error: Both --plan-file and --worktree-dir are required." >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -f "$PLAN_FILE" ]]; then
+    echo "Error: Plan file not found: $PLAN_FILE" >&2
+    exit 2
+fi
+
+if [[ ! -d "$WORKTREE_DIR" ]]; then
+    echo "Error: Worktree directory not found: $WORKTREE_DIR" >&2
+    exit 2
+fi
+
+# ─── Plan JSON Extraction ──────────────────────────────────────────────────
+
+# Extract task IDs where testingStrategy.propertyTests is true
+PBT_TASK_IDS=()
+while IFS= read -r task_id; do
+    [[ -n "$task_id" ]] && PBT_TASK_IDS+=("$task_id")
+done < <(
+    # Use python3 for reliable JSON parsing (available on macOS and most Linux)
+    python3 -c "
+import json, sys
+with open(sys.argv[1]) as f:
+    plan = json.load(f)
+for task in plan.get('tasks', []):
+    strategy = task.get('testingStrategy', {})
+    if strategy.get('propertyTests', False):
+        print(task.get('id', ''))
+" "$PLAN_FILE" 2>/dev/null
+)
+
+if [[ ${#PBT_TASK_IDS[@]} -eq 0 ]]; then
+    echo "## PBT Check: PASS"
+    echo "No tasks require property-based tests."
+    exit 0
+fi
+
+echo "## PBT Check"
+echo "Tasks requiring property-based tests: ${PBT_TASK_IDS[*]}"
+echo ""
+
+# ─── PBT Pattern Detection ─────────────────────────────────────────────────
+
+# TypeScript patterns: fast-check library usage
+TS_PBT_PATTERN="fc\.property|fc\.assert|it\.prop|test\.prop|from 'fast-check'|from \"fast-check\"|@fast-check"
+
+# .NET patterns: FsCheck library usage
+DOTNET_PBT_PATTERN="Prop\.ForAll|using FsCheck|\[Property\]"
+
+# Combined pattern
+COMBINED_PATTERN="$TS_PBT_PATTERN|$DOTNET_PBT_PATTERN"
+
+# Find all test files with PBT patterns
+PBT_FILES=()
+while IFS= read -r file; do
+    [[ -n "$file" ]] && PBT_FILES+=("$file")
+done < <(
+    grep -rlE "$COMBINED_PATTERN" "$WORKTREE_DIR" \
+        --include="*.test.ts" \
+        --include="*.test.tsx" \
+        --include="*.spec.ts" \
+        --include="*.Tests.cs" \
+        --include="*Tests.cs" \
+        --include="*.test.js" \
+        2>/dev/null || true
+)
+
+# ─── Cross-Reference ───────────────────────────────────────────────────────
+
+HAS_PBT=false
+if [[ ${#PBT_FILES[@]} -gt 0 ]]; then
+    HAS_PBT=true
+    echo "Found PBT patterns in:"
+    for f in "${PBT_FILES[@]}"; do
+        echo "  - $f"
+    done
+    echo ""
+fi
+
+# For each PBT-required task, check if any PBT file exists in the worktree
+UNCOVERED_TASKS=()
+if [[ "$HAS_PBT" == "true" ]]; then
+    # If any PBT patterns exist in the worktree, consider all tasks covered
+    # (task-to-file mapping is coarse-grained; presence of PBT patterns is the gate)
+    echo "All PBT-required tasks have coverage."
+else
+    # No PBT patterns found at all
+    for task_id in "${PBT_TASK_IDS[@]}"; do
+        UNCOVERED_TASKS+=("$task_id")
+    done
+fi
+
+# ─── Result ─────────────────────────────────────────────────────────────────
+
+if [[ ${#UNCOVERED_TASKS[@]} -gt 0 ]]; then
+    echo "## PBT Check: FAIL"
+    echo ""
+    echo "The following tasks require property-based tests but none were found:"
+    for task_id in "${UNCOVERED_TASKS[@]}"; do
+        echo "  - $task_id"
+    done
+    echo ""
+    echo "Expected patterns (TypeScript): fc.property, fc.assert, it.prop, test.prop, from 'fast-check'"
+    echo "Expected patterns (.NET): Prop.ForAll, using FsCheck, [Property]"
+    exit 1
+else
+    echo "## PBT Check: PASS"
+    exit 0
+fi

package/scripts/check-tdd-compliance.sh

@@ -0,0 +1,265 @@
+#!/usr/bin/env bash
+# Check TDD Compliance
+# Verify test-first git history order for commits on a branch.
+#
+# Usage: check-tdd-compliance.sh --repo-root <path> --branch <name> [--base-branch main]
+#
+# Exit codes:
+#   0 = compliant (test files committed before or alongside implementation)
+#   1 = violations found (implementation committed without test)
+#   2 = usage error (missing required args)
+
+set -euo pipefail
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+REPO_ROOT=""
+BRANCH=""
+BASE_BRANCH="main"
+
+usage() {
+    cat << 'USAGE'
+Usage: check-tdd-compliance.sh --repo-root <path> --branch <name> [--base-branch main]
+
+Required:
+  --repo-root <path>     Repository root directory
+  --branch <name>        Branch to check
+
+Optional:
+  --base-branch <name>   Base branch to compare against (default: main)
+  --help                 Show this help message
+
+Exit codes:
+  0  Compliant (test files committed before or alongside implementation)
+  1  Violations found (implementation without test in same/prior commit)
+  2  Usage error (missing required args)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo-root)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --repo-root requires a path argument" >&2
+                exit 2
+            fi
+            REPO_ROOT="$2"
+            shift 2
+            ;;
+        --branch)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --branch requires a name argument" >&2
+                exit 2
+            fi
+            BRANCH="$2"
+            shift 2
+            ;;
+        --base-branch)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --base-branch requires a name argument" >&2
+                exit 2
+            fi
+            BASE_BRANCH="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$REPO_ROOT" || -z "$BRANCH" ]]; then
+    echo "Error: --repo-root and --branch are required" >&2
+    usage >&2
+    exit 2
+fi
+
+if [[ ! -d "$REPO_ROOT/.git" ]]; then
+    echo "Error: Not a git repository: $REPO_ROOT" >&2
+    exit 2
+fi
+
+# ============================================================
+# HELPER: Classify a file as test or implementation
+# ============================================================
+
+is_test_file() {
+    local file="$1"
+    case "$file" in
+        *.test.ts|*.test.sh|*.spec.ts|*.test.js|*.spec.js|*.test.tsx|*.spec.tsx)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+is_impl_file() {
+    local file="$1"
+    # Implementation files: source code that isn't a test, config, or docs
+    case "$file" in
+        *.ts|*.js|*.tsx|*.jsx|*.sh)
+            # Exclude test files
+            if is_test_file "$file"; then
+                return 1
+            fi
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+# ============================================================
+# ANALYZE COMMITS
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+VIOLATIONS=()
+RESULTS=()
+
+# Track test files seen across all commits (cumulative)
+# Use a delimiter-separated string for bash 3.x compatibility (no associative arrays)
+TESTS_SEEN=""
+
+# Get commits from base..branch in chronological order (oldest first)
+cd "$REPO_ROOT"
+COMMITS=()
+while IFS= read -r commit_hash; do
+    [[ -n "$commit_hash" ]] && COMMITS+=("$commit_hash")
+done < <(git log --reverse --format="%H" "${BASE_BRANCH}..${BRANCH}" 2>/dev/null)
+
+if [[ ${#COMMITS[@]} -eq 0 ]]; then
+    echo "## TDD Compliance Report"
+    echo ""
+    echo "**Branch:** $BRANCH"
+    echo "**Base:** $BASE_BRANCH"
+    echo ""
+    echo "No commits found between $BASE_BRANCH and $BRANCH"
+    echo ""
+    echo "---"
+    echo ""
+    echo "**Result: PASS** (no commits to check)"
+    exit 0
+fi
+
+for commit_hash in "${COMMITS[@]}"; do
+    commit_msg="$(git log -1 --format="%s" "$commit_hash")"
+    commit_short="$(git log -1 --format="%h" "$commit_hash")"
+
+    # Get files changed in this commit
+    FILES_IN_COMMIT=()
+    while IFS= read -r file; do
+        [[ -n "$file" ]] && FILES_IN_COMMIT+=("$file")
+    done < <(git diff-tree --no-commit-id --name-only --diff-filter=ACMRT -r "$commit_hash" 2>/dev/null)
+
+    # Classify files in this commit
+    HAS_TEST=false
+    HAS_IMPL=false
+    IMPL_FILES=()
+    TEST_FILES=()
+
+    for file in "${FILES_IN_COMMIT[@]}"; do
+        if is_test_file "$file"; then
+            HAS_TEST=true
+            TEST_FILES+=("$file")
+            TESTS_SEEN="${TESTS_SEEN}|${file}|"
+        elif is_impl_file "$file"; then
+            HAS_IMPL=true
+            IMPL_FILES+=("$file")
+        fi
+    done
+
+    # A commit with implementation files is compliant if:
+    # 1. It also contains test files (mixed commit), OR
+    # 2. Corresponding test files were seen in prior commits
+    if [[ "$HAS_IMPL" == true ]]; then
+        if [[ "$HAS_TEST" == true ]]; then
+            # Mixed commit: test and impl together — OK
+            RESULTS+=("- **PASS**: \`$commit_short\` — $commit_msg (test+impl)")
+            CHECK_PASS=$((CHECK_PASS + 1))
+        else
+            # Check if test files were seen before this commit
+            FOUND_PRIOR_TEST=false
+            for impl_file in "${IMPL_FILES[@]}"; do
+                # Derive expected test file name(s)
+                base="${impl_file%.*}"
+                ext="${impl_file##*.}"
+                test_candidate_test="${base}.test.${ext}"
+                test_candidate_spec="${base}.spec.${ext}"
+
+                if echo "$TESTS_SEEN" | grep -qF "|${test_candidate_test}|" || \
+                   echo "$TESTS_SEEN" | grep -qF "|${test_candidate_spec}|"; then
+                    FOUND_PRIOR_TEST=true
+                    break
+                fi
+            done
+
+            if [[ "$FOUND_PRIOR_TEST" == true ]]; then
+                RESULTS+=("- **PASS**: \`$commit_short\` — $commit_msg (test in prior commit)")
+                CHECK_PASS=$((CHECK_PASS + 1))
+            else
+                RESULTS+=("- **FAIL**: \`$commit_short\` — $commit_msg (implementation without test)")
+                VIOLATIONS+=("$commit_short: $commit_msg")
+                CHECK_FAIL=$((CHECK_FAIL + 1))
+            fi
+        fi
+    elif [[ "$HAS_TEST" == true ]]; then
+        # Test-only commit — always compliant
+        RESULTS+=("- **PASS**: \`$commit_short\` — $commit_msg (test-only)")
+        CHECK_PASS=$((CHECK_PASS + 1))
+    else
+        # Non-code commit (docs, config, etc.) — skip
+        RESULTS+=("- **SKIP**: \`$commit_short\` — $commit_msg (non-code)")
+    fi
+done
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## TDD Compliance Report"
+echo ""
+echo "**Branch:** $BRANCH"
+echo "**Base:** $BASE_BRANCH"
+echo "**Commits analyzed:** ${#COMMITS[@]}"
+echo ""
+
+echo "### Per-commit Analysis"
+echo ""
+for result in "${RESULTS[@]}"; do
+    echo "$result"
+done
+echo ""
+
+if [[ ${#VIOLATIONS[@]} -gt 0 ]]; then
+    echo "### Violations"
+    echo ""
+    for v in "${VIOLATIONS[@]}"; do
+        echo "- $v"
+    done
+    echo ""
+fi
+
+TOTAL=$((CHECK_PASS + CHECK_FAIL))
+echo "---"
+echo ""
+
+if [[ $CHECK_FAIL -eq 0 ]]; then
+    echo "**Result: PASS** ($CHECK_PASS/$TOTAL commits compliant)"
+    exit 0
+else
+    echo "**Result: FAIL** ($CHECK_FAIL/$TOTAL commits have violations)"
+    exit 1
+fi