Justfile

# SPDX-License-Identifier: MPL-2.0
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
#
# 007 Agent Meta-Language — RSR-Compliant Justfile
# https://just.systems/man/en/
#
# Rust workspace: crates/oo7-core (library), crates/oo7-cli (binary)
# Run `just` to see all available recipes
# Run `just cookbook` to generate docs/just-cookbook.adoc

set shell := ["bash", "-uc"]
set dotenv-load := true
set positional-arguments := true

# Import auto-generated contractile recipes (must-check, trust-verify, etc.)
# Re-generate with: contractile gen-just
import? "contractile.just"

# Project metadata
project := "007-lang"
OWNER := "hyperpolymath"
REPO := "007-lang"
version := "0.1.0"
tier := "2"  # Novel language, pre-production

# ═══════════════════════════════════════════════════════════════════════════════
# DEFAULT & HELP
# ═══════════════════════════════════════════════════════════════════════════════

# Show all available recipes with descriptions
default:
    @just --list --unsorted

# Show detailed help for a specific recipe, or list all if no recipe given
help recipe="":
    #!/usr/bin/env bash
    if [ -z "{{recipe}}" ]; then
        just --list --unsorted
        echo ""
        echo "Usage: just help <recipe>"
        echo "       just cookbook     # Generate full documentation"
        echo "       just info        # Show project metadata"
    else
        just --show "{{recipe}}" 2>/dev/null || echo "Recipe '{{recipe}}' not found"
    fi

# Show this project's metadata and build status
info:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Project: {{project}}"
    echo "Version: {{version}}"
    echo "RSR Tier: {{tier}} (novel language, pre-production)"
    echo "Workspace: crates/oo7-core, crates/oo7-cli"
    echo "Recipes: $(just --summary | wc -w)"
    echo "License: MPL-2.0"
    echo "Author: Jonathan D.A. Jewell"
    [ -f ".machine_readable/STATE.a2ml" ] && grep -oP 'phase\s*=\s*"\K[^"]+' .machine_readable/STATE.a2ml 2>/dev/null | head -1 | xargs -I{} echo "Phase: {}" || true

# ═══════════════════════════════════════════════════════════════════════════════
# BUILD
# ═══════════════════════════════════════════════════════════════════════════════

# Build the entire workspace (debug mode)
build *args:
    cargo build {{args}}

# Build in release mode with optimizations
release *args:
    cargo build --release {{args}}

# Build only the CLI binary (debug)
build-cli:
    cargo build --bin oo7

# Build only the CLI binary (release)
build-cli-release:
    cargo build --bin oo7 --release

# Build and watch for changes (requires cargo-watch)
build-watch:
    #!/usr/bin/env bash
    set -euo pipefail
    if command -v cargo-watch &>/dev/null; then
        cargo watch -x build
    else
        echo "cargo-watch not installed. Install with: cargo install cargo-watch"
        echo "Falling back to entr..."
        find crates -name '*.rs' -o -name '*.pest' | entr -c cargo build
    fi

# ═══════════════════════════════════════════════════════════════════════════════
# TEST
# ═══════════════════════════════════════════════════════════════════════════════

# Run all tests across the workspace
test *args:
    cargo test {{args}}

# Run tests with full output (no capture)
test-verbose:
    cargo test -- --nocapture

# Run only parser tests (grammar and AST)
test-parser:
    cargo test --package oo7-core parser -- --nocapture

# Run only evaluator tests
test-eval:
    cargo test --package oo7-core eval -- --nocapture

# Run only trace tests (decision trace output)
test-trace:
    cargo test --package oo7-core trace -- --nocapture

# Run a specific test by name pattern
test-filter pattern:
    cargo test "{{pattern}}" -- --nocapture

# Run the M3-v0 differential (v0 Rust oracle vs production). Floor: 17/17.
v0-differential:
    cargo test -p oo7-typechecker-oracle --test differential

# Run the M3-v1 differential (v1 Idris2 reference checker vs v0 + production).
# Skipped with a notice on stderr if `idris2` is not on PATH, because v1 is
# a nightly gate rather than an every-push gate per the dispatch architecture
# at audits/audit-m3-dispatch-architecture.md §4.
#
# Fast path: closed corpus pinned via `idris2 --check` Refl (~7s); open
# corpus checked via v0-vs-production agreement only.
v1-differential:
    cargo test -p oo7-typechecker-oracle --test v1_differential -- --nocapture

# Run the M3-v1 differential INCLUDING the idris2 --exec path for the open
# corpus (M3-DD-12's two-mechanism split closed via the `v1_differential_open_terms_via_exec`
# test). Adds ~15s to compile the Idris2 wrapper through Chez Scheme.
# Default `just v1-differential` skips this path; use `just v1-differential-full`
# for the complete verification (typically nightly rather than every push).
v1-differential-full:
    OO7_V1_EXEC=1 cargo test -p oo7-typechecker-oracle --test v1_differential -- --nocapture

# ═══════════════════════════════════════════════════════════════════════════════
# CODE QUALITY
# ═══════════════════════════════════════════════════════════════════════════════

# Run clippy lints with warnings as errors
lint:
    cargo clippy --workspace -- -D warnings

# Format all Rust source files
fmt:
    cargo fmt --all

# Check formatting without modifying files
fmt-check:
    cargo fmt --all -- --check

# Pre-commit quality gate: format check, lint, and test
check: fmt-check lint test
    @echo "All checks passed."

# Full local gate — the billing-independent "is it green?" in one command.
# Runs every locally-faithful CI check in sequence, CONTINUES past failures,
# and prints a per-stage PASS/FAIL/SKIP summary (non-zero exit if any FAIL).
# Stages that need a specific toolchain (idris2) or an external GitHub action
# (A2ML validator, etc.) self-SKIP with a notice rather than failing, so this
# runs anywhere. Rocq canonical-proof-suite (needs Rocq 9) and the external
# manifest/security scans (K9 / Groove / openssf / Hypatia / eclexiaiser)
# remain CI/nightly-only — there is no local validator for them in-repo.
# Distinct from `ci` (build/test/lint/verify) and `check` (fast fmt/lint/test).
# One command; the full local green-check with a per-stage PASS/FAIL summary.
gate:
    #!/usr/bin/env bash
    set -uo pipefail
    fail=0
    declare -a results
    run() {
        local name="$1"; shift
        echo; echo "──▶ ${name}"
        if "$@"; then results+=("  ✓ PASS  ${name}")
        else results+=("  ✗ FAIL  ${name}"); fail=1; fi
    }
    skip() { echo; echo "──▶ $1 — SKIP ($2)"; results+=("  ⊘ SKIP  $1 ($2)"); }

    run "rustfmt"        cargo fmt --all -- --check
    run "clippy"         cargo clippy --workspace -- -D warnings
    run "test"           cargo test --workspace
    run "grammar-check"  just grammar-check
    run "verify-harvard" just verify-harvard
    run "e2e"            bash tests/e2e.sh

    if command -v idris2 >/dev/null 2>&1; then
        run "idris2-proofs" bash -c 'for f in proofs/idris2/*.idr; do ( cd "$(dirname "$f")" && idris2 --check "$(basename "$f")" ) || { echo "  failed: $f"; exit 1; }; done'
    else
        skip "idris2-proofs" "idris2 not on PATH"
    fi

    if command -v validate-a2ml.sh >/dev/null 2>&1; then
        run "a2ml" bash -c 'INPUT_PATH=.machine_readable/6a2 INPUT_STRICT=false validate-a2ml.sh'
    else
        skip "a2ml" "validate-a2ml.sh not on PATH (CI uses hyperpolymath/a2ml-validate-action)"
    fi

    if command -v panic-attack >/dev/null 2>&1; then
        run "assail" panic-attack assail .
    else
        skip "assail" "panic-attack not installed"
    fi

    echo; echo "═══════════════ local CI summary ═══════════════"
    printf '%s\n' "${results[@]}"
    echo "─────────────────────────────────────────────────"
    echo "CI/nightly-only (not run here): rocq canonical-proof-suite (needs"
    echo "Rocq 9); external manifest/security scans (no local validator)."
    if [ "${fail}" -eq 0 ]; then echo "RESULT: GREEN ✓"; else echo "RESULT: RED ✗ (see FAIL above)"; exit 1; fi

# Run panic-attacker pre-commit scan (RSR mandatory before commit)
assail:
    #!/usr/bin/env bash
    set -euo pipefail
    if command -v panic-attack &>/dev/null; then
        panic-attack assail .
    else
        echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker"
        echo "Skipping assail (non-fatal in dev)."
    fi

# ═══════════════════════════════════════════════════════════════════════════════
# PARSER
# ═══════════════════════════════════════════════════════════════════════════════

# Parse a .007 source file and print the AST
parse file:
    cargo run --bin oo7 -- parse "{{file}}"

# Validate Pest grammar consistency (check for unreachable or undefined rules)
grammar-check:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Pest Grammar Consistency Check ==="
    GRAMMAR="crates/oo7-core/src/grammar.pest"

    if [ ! -f "$GRAMMAR" ]; then
        echo "FAIL: $GRAMMAR not found"
        exit 1
    fi

    # Extract rule names defined in the grammar (lines matching: rule_name = ...)
    DEFINED=$(grep -oP '^[a-z_][a-z_0-9]*(?=\s*=)' "$GRAMMAR" | sort -u)
    DEFINED_COUNT=$(echo "$DEFINED" | wc -l)

    # Extract rule names referenced in the grammar (inside { } or ~ separators)
    REFERENCED=$(grep -oP '(?<![a-z_])[a-z_][a-z_0-9]*' "$GRAMMAR" \
        | grep -v -E '^(WHITESPACE|COMMENT|SOI|EOI|ANY|ASCII|NEWLINE|PEEK|POP|PUSH|DROP)$' \
        | sort -u)

    # Find undefined references (referenced but not defined)
    UNDEFINED=$(comm -23 <(echo "$REFERENCED") <(echo "$DEFINED") || true)

    # Find unreferenced definitions (defined but never referenced elsewhere)
    # Note: top-level entry points (program, WHITESPACE, COMMENT) are expected
    UNREFERENCED=$(comm -23 <(echo "$DEFINED") <(echo "$REFERENCED") || true)

    echo "Defined rules: $DEFINED_COUNT"

    if [ -n "$UNDEFINED" ]; then
        echo ""
        echo "WARNING: Referenced but not defined (may be Pest built-ins):"
        echo "$UNDEFINED" | sed 's/^/  /'
    fi

    if [ -n "$UNREFERENCED" ]; then
        echo ""
        echo "NOTE: Defined but not referenced (entry points or dead rules):"
        echo "$UNREFERENCED" | sed 's/^/  /'
    fi

    echo ""
    echo "Grammar check complete."

# ═══════════════════════════════════════════════════════════════════════════════
# DEMO & RUN
# ═══════════════════════════════════════════════════════════════════════════════

# Run the built-in demo (produces decision trace)
demo:
    cargo run --bin oo7 -- demo

# Run a .007 program and display the decision trace
trace file:
    cargo run --bin oo7 -- trace "{{file}}"

# Run a .007 program
run file *args:
    cargo run --bin oo7 -- run "{{file}}" {{args}}

# Run all example programs in the examples/ directory
run-examples:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Running all .007 examples ==="
    for f in examples/*.007; do
        echo ""
        echo "--- $(basename "$f") ---"
        cargo run --bin oo7 -- run "$f" || echo "  (failed)"
    done

# ═══════════════════════════════════════════════════════════════════════════════
# DOCS
# ═══════════════════════════════════════════════════════════════════════════════

# Generate Rust API documentation (opens in browser if --open passed)
docs *args:
    cargo doc --workspace --no-deps {{args}}
    @echo "Documentation generated in target/doc/"

# Generate Justfile cookbook documentation in AsciiDoc format
cookbook:
    #!/usr/bin/env bash
    mkdir -p docs
    OUTPUT="docs/just-cookbook.adoc"
    echo "= {{project}} Justfile Cookbook" > "$OUTPUT"
    echo ":toc: left" >> "$OUTPUT"
    echo ":toclevels: 3" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
    echo "Generated: $(date -Iseconds)" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
    echo "== Recipes" >> "$OUTPUT"
    echo "" >> "$OUTPUT"
    just --list --unsorted | while read -r line; do
        if [[ "$line" =~ ^[[:space:]]+([a-z_-]+) ]]; then
            recipe="${BASH_REMATCH[1]}"
            echo "=== $recipe" >> "$OUTPUT"
            echo "" >> "$OUTPUT"
            echo "[source,bash]" >> "$OUTPUT"
            echo "----" >> "$OUTPUT"
            echo "just $recipe" >> "$OUTPUT"
            echo "----" >> "$OUTPUT"
            echo "" >> "$OUTPUT"
        fi
    done
    echo "Generated: $OUTPUT"

# ═══════════════════════════════════════════════════════════════════════════════
# CONTAINER (Podman + Chainguard)
# ═══════════════════════════════════════════════════════════════════════════════

# Build the container image using Podman and Chainguard base
container-build *args:
    #!/usr/bin/env bash
    set -euo pipefail
    if [ -f "Containerfile" ]; then
        podman build -t oo7-lang:latest -f Containerfile . {{args}}
        echo "Built: oo7-lang:latest"
    else
        echo "No Containerfile found in project root"
        exit 1
    fi

# Run the container image interactively
container-run *args:
    podman run --rm -it oo7-lang:latest {{args}}

# Verify the container image builds and runs a basic health check
container-verify:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Container Verification ==="

    echo "Building image..."
    podman build -t oo7-lang:verify -f Containerfile . --quiet

    echo "Running smoke test..."
    OUTPUT=$(podman run --rm oo7-lang:verify --help 2>&1 || true)
    if [ -n "$OUTPUT" ]; then
        echo "  Container responds to --help"
        echo "  First line: $(echo "$OUTPUT" | head -1)"
    else
        echo "  WARNING: Container produced no output on --help"
    fi

    echo "Checking image size..."
    SIZE=$(podman image inspect oo7-lang:verify --format '{{{{.Size}}}}' 2>/dev/null || echo "unknown")
    echo "  Image size: $SIZE bytes"

    echo ""
    echo "Container verification complete."

# ═══════════════════════════════════════════════════════════════════════════════
# VERIFICATION (OpenSSF + RSR Compliance)
# ═══════════════════════════════════════════════════════════════════════════════

# Verify OpenSSF Best Practices prerequisites — fails if required files are missing
verify:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "=== OpenSSF Best Practices Verification ==="
    ERRORS=0

    check_file() {
        if [ ! -f "$1" ]; then
            echo "  FAIL: $1 missing"
            ERRORS=$((ERRORS + 1))
        else
            echo "  OK:   $1"
        fi
    }

    check_either() {
        if [ ! -f "$1" ] && [ ! -f "$2" ]; then
            echo "  FAIL: $1 (or $2) missing"
            ERRORS=$((ERRORS + 1))
        else
            local found="$1"
            [ -f "$2" ] && found="$2"
            [ -f "$1" ] && found="$1"
            echo "  OK:   $found"
        fi
    }

    check_either "SECURITY.md" "SECURITY.adoc"
    check_file "LICENSE"
    check_either "CONTRIBUTING.md" "CONTRIBUTING.adoc"
    check_either "README.adoc" "README.md"
    check_file ".machine_readable/STATE.a2ml"
    check_file ".machine_readable/META.a2ml"
    check_file ".machine_readable/ECOSYSTEM.a2ml"
    check_either "CHANGELOG.md" "CHANGELOG.adoc"

    # Check at least 1 workflow exists
    WORKFLOW_COUNT=$(find .github/workflows -name '*.yml' -o -name '*.yaml' 2>/dev/null | wc -l)
    if [ "$WORKFLOW_COUNT" -eq 0 ]; then
        echo "  FAIL: No workflows in .github/workflows/"
        ERRORS=$((ERRORS + 1))
    else
        echo "  OK:   .github/workflows/ ($WORKFLOW_COUNT workflows)"
    fi

    echo ""
    if [ "$ERRORS" -gt 0 ]; then
        echo "FAIL: $ERRORS OpenSSF prerequisites missing — repo cannot ship."
        exit 1
    fi
    echo "PASS: All OpenSSF Best Practices prerequisites satisfied."

# Check for unreplaced template placeholders
verify-template:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Checking for unreplaced template placeholders..."
    FOUND=0

    # Check for double-brace PLACEHOLDER patterns (hex avoids just interpolation)
    LB=$(printf '\x7b\x7b')
    RB=$(printf '\x7d\x7d')

    HITS=$(grep -rn "${LB}[A-Z_]*${RB}" --include="*.adoc" --include="*.md" --include="*.a2ml" \
           --include="*.scm" --include="*.toml" --include="*.yml" --include="*.yaml" \
           . 2>/dev/null | grep -v 'node_modules\|\.git/' | grep -v 'PLACEHOLDERS.adoc' || true)
    if [ -n "$HITS" ]; then
        echo ""
        echo "WARNING: Unreplaced placeholders found:"
        echo "$HITS" | head -20
        FOUND=1
    fi

    if [ $FOUND -eq 0 ]; then
        echo "OK: No template placeholders found — project is properly customised."
    else
        echo ""
        echo "Edit the files above to replace the remaining template markers."
        exit 1
    fi

# Run aspect-focused integration tests
test-aspect:
    cargo test --package oo7-core aspect_ -- --nocapture

# Verify Harvard architecture invariant — data expressions must not contain control flow
verify-harvard:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Harvard Architecture Invariant Check ==="
    echo "Rule: data_expr must never contain control-flow constructs."
    echo "      Code and data buses are strictly separated."
    echo ""

    ERRORS=0

    # Check the Pest grammar for data_expr rules containing control flow references
    GRAMMAR="crates/oo7-core/src/grammar.pest"
    if [ ! -f "$GRAMMAR" ]; then
        echo "FAIL: $GRAMMAR not found"
        exit 1
    fi

    # Extract the data_expr rule block (from 'data_expr' to next top-level rule)
    # Look for control-flow keywords leaking into data expressions
    CONTROL_PATTERNS="if_expr\|match_expr\|loop_expr\|while_expr\|for_expr\|branch_expr\|dispatch\|send_msg\|receive_msg\|spawn\|choose\|offer"

    # Check grammar: data_expr should not reference control-flow rules
    DATA_SECTION=$(sed -n '/^data_expr\b/,/^[a-z_]*\s*=/p' "$GRAMMAR" 2>/dev/null | head -n -1 || true)
    if [ -n "$DATA_SECTION" ]; then
        VIOLATIONS=$(echo "$DATA_SECTION" | grep -oE "$CONTROL_PATTERNS" || true)
        if [ -n "$VIOLATIONS" ]; then
            echo "FAIL: data_expr contains control-flow references in grammar:"
            echo "$VIOLATIONS" | sed 's/^/  /'
            ERRORS=$((ERRORS + 1))
        else
            echo "  OK: data_expr in grammar contains no control-flow references"
        fi
    else
        echo "  SKIP: No data_expr rule found in grammar (may not be defined yet)"
    fi

    # Check Rust evaluator: data evaluation should not call control-flow eval paths
    EVAL_FILE="crates/oo7-core/src/eval.rs"
    if [ -f "$EVAL_FILE" ]; then
        # Look for eval_data functions that call eval_control or eval_dispatch
        DATA_FNS=$(grep -n 'fn eval_data\|fn evaluate_data' "$EVAL_FILE" || true)
        if [ -n "$DATA_FNS" ]; then
            echo "  Checking evaluator data paths for control-flow leaks..."
            # Rough check: in data eval functions, look for calls to control eval
            LEAKS=$(grep -A 30 'fn eval_data\|fn evaluate_data' "$EVAL_FILE" \
                | grep -E 'eval_control|eval_dispatch|eval_branch|eval_send|eval_receive' || true)
            if [ -n "$LEAKS" ]; then
                echo "  FAIL: Data evaluator calls control-flow evaluator:"
                echo "$LEAKS" | sed 's/^/    /'
                ERRORS=$((ERRORS + 1))
            else
                echo "  OK: Data evaluator does not call control-flow paths"
            fi
        else
            echo "  SKIP: No eval_data function found (Harvard separation may be at AST level)"
        fi
    fi

    # Check AST: DataExpr enum should not contain control-flow variants
    AST_FILE="crates/oo7-core/src/ast.rs"
    if [ -f "$AST_FILE" ]; then
        DATA_ENUM=$(sed -n '/enum DataExpr/,/^}/p' "$AST_FILE" 2>/dev/null || true)
        if [ -n "$DATA_ENUM" ]; then
            CONTROL_IN_DATA=$(echo "$DATA_ENUM" | grep -v '^\s*//' | grep -iE '\b(If|Match|Loop|While|For|Branch|Send|Receive|Spawn|Choose|Offer)\b' || true)
            if [ -n "$CONTROL_IN_DATA" ]; then
                echo "  FAIL: DataExpr enum contains control-flow variants:"
                echo "$CONTROL_IN_DATA" | sed 's/^/    /'
                ERRORS=$((ERRORS + 1))
            else
                echo "  OK: DataExpr enum is free of control-flow variants"
            fi
        else
            echo "  SKIP: No DataExpr enum found in ast.rs"
        fi
    fi

    echo ""
    if [ "$ERRORS" -gt 0 ]; then
        echo "FAIL: $ERRORS Harvard architecture violations detected."
        echo "The data bus must be strictly separated from the control bus."
        exit 1
    fi
    echo "PASS: Harvard architecture invariant holds."

# ═══════════════════════════════════════════════════════════════════════════════
# CONTRACTILES (must/trust/dust/lust/intend/k9)
# ═══════════════════════════════════════════════════════════════════════════════

# Check all must-contracts (hard requirements that block release)
must-check-local:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Must-Contract Check ==="
    MUST_DIR=".machine_readable/contractiles/must"
    if [ ! -d "$MUST_DIR" ]; then
        echo "No must-contracts found at $MUST_DIR"
        exit 0
    fi
    COUNT=0
    for f in "$MUST_DIR"/*; do
        [ -f "$f" ] || continue
        echo "  MUST: $(basename "$f")"
        COUNT=$((COUNT + 1))
    done
    echo ""
    echo "$COUNT must-contract(s) registered."

# Verify trust-contracts (delegated quality expectations)
trust-verify-local:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Trust-Contract Verify ==="
    TRUST_DIR=".machine_readable/contractiles/trust"
    if [ ! -d "$TRUST_DIR" ]; then
        echo "No trust-contracts found at $TRUST_DIR"
        exit 0
    fi
    COUNT=0
    for f in "$TRUST_DIR"/*; do
        [ -f "$f" ] || continue
        echo "  TRUST: $(basename "$f")"
        COUNT=$((COUNT + 1))
    done
    echo ""
    echo "$COUNT trust-contract(s) registered."

# Show dust-contract status (deprecated or decaying items)
dust-status-local:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Dust-Contract Status ==="
    DUST_DIR=".machine_readable/contractiles/dust"
    if [ ! -d "$DUST_DIR" ]; then
        echo "No dust-contracts found at $DUST_DIR"
        exit 0
    fi
    COUNT=0
    for f in "$DUST_DIR"/*; do
        [ -f "$f" ] || continue
        echo "  DUST: $(basename "$f")"
        COUNT=$((COUNT + 1))
    done
    echo ""
    echo "$COUNT dust-contract(s) registered."

# List all intend-contracts (planned but not yet implemented)
intend-list-local:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "=== Intend-Contract List ==="
    # Check both intend/ and lust/ directories (lust = aspirational contracts)
    for DIR_NAME in lust intend; do
        DIR=".machine_readable/contractiles/$DIR_NAME"
        if [ -d "$DIR" ]; then
            echo "--- $DIR_NAME ---"
            for f in "$DIR"/*; do
                [ -f "$f" ] || continue
                echo "  $(basename "$f")"
            done
        fi
    done

# Run all contractile checks together
contractile-check: must-check trust-verify dust-status intend-list bust-check adjust-check
    @echo ""
    @echo "Contractile review complete."

# Run bust hard-stop probes (blocks merge on critical/high severity hits).
# Per-probe timeout keeps slow provers (canonical-proof-suite,
# v0-differential) from stalling the pre-commit gate — those return
# 'deferred' rather than failing; run `just bust-check-full` for the
# untimed variant.
bust-check:
    #!/usr/bin/env bash
    set -uo pipefail
    bf=.machine_readable/contractiles/bust/Bustfile.a2ml
    if [ ! -f "$bf" ]; then echo "! Bustfile missing"; exit 0; fi
    echo "→ bust-check — running hard-stop probes from $bf (fast; 10s per probe)"
    fail=0; deferred=0
    while IFS= read -r line; do
      probe=$(echo "$line" | sed -E 's/^probe = "(.*)"$/\1/')
      [ -z "$probe" ] && continue
      timeout 10 bash -c "$probe" 2>/dev/null
      rc=$?
      if [ $rc -eq 0 ]; then
        echo "  ✗ BUST HIT: $probe"
        fail=1
      elif [ $rc -eq 124 ]; then
        deferred=$((deferred+1))
      fi
    done < <(grep -E '^probe = "' "$bf")
    echo "  deferred (slow probes): $deferred"
    if [ $fail -eq 0 ]; then echo "  ✓ no bust hits"; else echo "! bust-check failed"; exit 1; fi

# Full bust-check with no per-probe timeout — runs every slow prover.
bust-check-full:
    #!/usr/bin/env bash
    set -uo pipefail
    bf=.machine_readable/contractiles/bust/Bustfile.a2ml
    if [ ! -f "$bf" ]; then echo "! Bustfile missing"; exit 0; fi
    echo "→ bust-check-full — running all hard-stop probes"
    fail=0
    while IFS= read -r line; do
      probe=$(echo "$line" | sed -E 's/^probe = "(.*)"$/\1/')
      [ -z "$probe" ] && continue
      if bash -c "$probe" 2>/dev/null; then
        echo "  ✗ BUST HIT: $probe"
        fail=1
      fi
    done < <(grep -E '^probe = "' "$bf")
    if [ $fail -eq 0 ]; then echo "  ✓ no bust hits"; else echo "! bust-check-full failed"; exit 1; fi

# Run adjust drift-detection probes (advisory — reports without blocking).
adjust-check:
    #!/usr/bin/env bash
    set -uo pipefail
    af=.machine_readable/contractiles/adjust/Adjustfile.a2ml
    if [ ! -f "$af" ]; then echo "! Adjustfile missing"; exit 0; fi
    echo "→ adjust-check — running drift probes from $af"
    hits=0
    while IFS= read -r line; do
      probe=$(echo "$line" | sed -E 's/^detect = "(.*)"$/\1/')
      [ -z "$probe" ] && continue
      if bash -c "$probe" 2>/dev/null; then
        echo "  ⚠ ADJUST hit: $probe"
        hits=$((hits+1))
      fi
    done < <(grep -E '^detect = "' "$af")
    if [ $hits -eq 0 ]; then
      echo "  ✓ no drift detected"
    else
      echo "  $hits drift entry/entries surfaced (advisory)"
    fi

# ═══════════════════════════════════════════════════════════════════════════════
# SELF-ASSESSMENT
# ═══════════════════════════════════════════════════════════════════════════════

# Analyse this project and advise what is present, missing, or needs attention
self-assess:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "═══════════════════════════════════════════════════"
    echo "  007-lang RSR Self-Assessment (Tier {{tier}})"
    echo "═══════════════════════════════════════════════════"
    echo ""

    # ── ESSENTIAL (RSR-required) ──────────────────────────────
    echo "── ESSENTIAL (removing breaks Rhodium Standard) ──────────"
    echo ""

    for f in LICENSE SECURITY.md CODE_OF_CONDUCT.md CONTRIBUTING.md .editorconfig .gitignore; do
        if [ -f "$f" ]; then
            echo "  OK:   $f"
        else
            echo "  FAIL: $f — MISSING (RSR violation)"
        fi
    done

    for f in .machine_readable/STATE.a2ml .machine_readable/META.a2ml .machine_readable/ECOSYSTEM.a2ml; do
        if [ -f "$f" ]; then
            echo "  OK:   $f"
        else
            echo "  FAIL: $f — MISSING"
        fi
    done

    if [ -d ".github/workflows" ]; then
        WF_COUNT=$(find .github/workflows -name '*.yml' 2>/dev/null | wc -l)
        echo "  OK:   .github/workflows/ ($WF_COUNT workflows)"
    else
        echo "  FAIL: .github/workflows/ — MISSING"
    fi
    echo ""

    # ── PROJECT-SPECIFIC ──────────────────────────────────────
    echo "── PROJECT-SPECIFIC (007-lang) ───────────────────────────"
    echo ""

    [ -f "Cargo.toml" ] && echo "  OK:   Cargo.toml (Rust workspace)" || echo "  FAIL: Cargo.toml"
    [ -f "Containerfile" ] && echo "  OK:   Containerfile (Chainguard)" || echo "  SKIP: Containerfile"
    [ -f "crates/oo7-core/src/grammar.pest" ] && echo "  OK:   grammar.pest (Pest parser)" || echo "  FAIL: grammar.pest"
    [ -f "spec/grammar.ebnf" ] && echo "  OK:   spec/grammar.ebnf (formal grammar)" || echo "  FAIL: grammar.ebnf"
    [ -f "spec/LANGUAGE-SPEC.adoc" ] && echo "  OK:   LANGUAGE-SPEC.adoc" || echo "  SKIP: LANGUAGE-SPEC.adoc"
    [ -f "spec/TYPE-SYSTEM-SPEC.adoc" ] && echo "  OK:   TYPE-SYSTEM-SPEC.adoc" || echo "  SKIP: TYPE-SYSTEM-SPEC.adoc"
    [ -f "spec/OPERATIONAL-SEMANTICS.adoc" ] && echo "  OK:   OPERATIONAL-SEMANTICS.adoc" || echo "  SKIP: OPERATIONAL-SEMANTICS.adoc"
    [ -d "examples" ] && echo "  OK:   examples/ ($(ls examples/*.007 2>/dev/null | wc -l) programs)" || echo "  SKIP: examples/"

    # Check Harvard architecture separation in AST
    if [ -f "crates/oo7-core/src/ast.rs" ]; then
        if grep -q 'DataExpr\|ControlExpr\|CodeExpr' crates/oo7-core/src/ast.rs 2>/dev/null; then
            echo "  OK:   Harvard separation visible in AST"
        else
            echo "  NOTE: Harvard separation not yet reflected in AST enums"
        fi
    fi
    echo ""

    # ── CONTRACTILES ──────────────────────────────────────────
    echo "── CONTRACTILES ──────────────────────────────────────────"
    echo ""

    if [ -d ".machine_readable/contractiles" ]; then
        for c in must trust dust lust k9; do
            DIR=".machine_readable/contractiles/$c"
            if [ -d "$DIR" ]; then
                COUNT=$(find "$DIR" -type f 2>/dev/null | wc -l)
                echo "  OK:   $c/ ($COUNT contracts)"
            else
                echo "  SKIP: $c/ (not present)"
            fi
        done
    else
        echo "  FAIL: .machine_readable/contractiles/ — MISSING"
    fi

    echo ""
    echo "═══════════════════════════════════════════════════"
    echo "  Assessment complete. No files were modified."
    echo "═══════════════════════════════════════════════════"

# ═══════════════════════════════════════════════════════════════════════════════
# GROOVE (inter-service protocol)
# ═══════════════════════════════════════════════════════════════════════════════

# Configure Groove protocol manifest and build control plane
groove-setup:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Configuring 007 Agent Control Plane (Groove Protocol)..."
    cd oo7-control-plane && v .
    echo "Port 7007 assigned in oo7-control-plane/src/main.v"
    echo "Manifest available at oo7-control-plane/src/manifest.a2ml"

# Start the 007 Groove Daemon (Control Plane)
groove-daemon:
    #!/usr/bin/env bash
    set -euo pipefail
    echo "Starting 007 Agent Control Plane on http://localhost:7007..."
    ./oo7-control-plane/oo7_control_plane

# ═══════════════════════════════════════════════════════════════════════════════
# MAINTENANCE
# ═══════════════════════════════════════════════════════════════════════════════

# Remove all build artifacts [reversible: just build]
clean:
    cargo clean
    @echo "Build artifacts cleaned."

# Deep clean including any generated files [reversible: just build]
clean-all: clean
    rm -rf docs/just-cookbook.adoc docs/generated
    @echo "Deep clean complete."

# Audit dependencies for known vulnerabilities (requires cargo-audit)
audit:
    #!/usr/bin/env bash
    set -euo pipefail
    if command -v cargo-audit &>/dev/null; then
        cargo audit
    else
        echo "cargo-audit not installed. Install with: cargo install cargo-audit"
        exit 1
    fi

# Check dependency licenses and bans (requires cargo-deny)
deny:
    #!/usr/bin/env bash
    set -euo pipefail
    if command -v cargo-deny &>/dev/null; then
        cargo deny check
    else
        echo "cargo-deny not installed. Install with: cargo install cargo-deny"
        echo "Then create a deny.toml configuration file."
        exit 1
    fi

# List outdated dependencies (requires cargo-outdated)
outdated:
    #!/usr/bin/env bash
    set -euo pipefail
    if command -v cargo-outdated &>/dev/null; then
        cargo outdated --workspace
    else
        echo "cargo-outdated not installed. Install with: cargo install cargo-outdated"
        exit 1
    fi

# Run benchmarks (when available)
bench:
    cargo bench

# Run the Canonical Proof Suite runner (TRG roadmap §1).
# Reads audits/canonical-proof-suite/MANIFEST.a2ml, type-checks every
# entry under the qualifying prover declared for it, writes per-entry
# sidecars to proofs/canonical-proof-suite/<id>.sidecar.a2ml, and an
# aggregate report to audits/canonical-proof-suite/REPORT.a2ml.
canonical-proof-suite:
    bash scripts/canonical-proof-suite-runner.sh

# ═══════════════════════════════════════════════════════════════════════════════
# SPEC (grammar and specification sync)
# ═══════════════════════════════════════════════════════════════════════════════

# Compare EBNF and Pest grammar rule counts to identify specification drift
spec-check:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "=== Specification Sync Check ==="
    echo "Comparing: spec/grammar.ebnf vs crates/oo7-core/src/grammar.pest"
    echo ""

    EBNF="spec/grammar.ebnf"
    PEST="crates/oo7-core/src/grammar.pest"

    if [ ! -f "$EBNF" ]; then
        echo "FAIL: $EBNF not found"
        exit 1
    fi
    if [ ! -f "$PEST" ]; then
        echo "FAIL: $PEST not found"
        exit 1
    fi

    # Count top-level rules in EBNF (lines matching: rule_name = ... ;)
    # EBNF rules typically look like: rule_name = expr ;
    EBNF_RULES=$(grep -oP '^[a-z_][a-z_0-9]*(?=\s*=)' "$EBNF" | sort -u)
    EBNF_COUNT=$(echo "$EBNF_RULES" | grep -c '.' || echo 0)

    # Count top-level rules in Pest (lines matching: rule_name = { ... })
    PEST_RULES=$(grep -oP '^[a-z_][a-z_0-9]*(?=\s*=)' "$PEST" | sort -u)
    PEST_COUNT=$(echo "$PEST_RULES" | grep -c '.' || echo 0)

    echo "EBNF rules:  $EBNF_COUNT"
    echo "Pest rules:  $PEST_COUNT"

    # Calculate gap
    if [ "$EBNF_COUNT" -gt "$PEST_COUNT" ]; then
        GAP=$((EBNF_COUNT - PEST_COUNT))
        echo "Gap:         $GAP rules in EBNF not yet in Pest"
        echo ""
        echo "Rules in EBNF but missing from Pest:"
        comm -23 <(echo "$EBNF_RULES") <(echo "$PEST_RULES") | sed 's/^/  /'
    elif [ "$PEST_COUNT" -gt "$EBNF_COUNT" ]; then
        GAP=$((PEST_COUNT - EBNF_COUNT))
        echo "Gap:         $GAP rules in Pest not in EBNF"
        echo ""
        echo "Rules in Pest but missing from EBNF:"
        comm -23 <(echo "$PEST_RULES") <(echo "$EBNF_RULES") | sed 's/^/  /'
    else
        echo "Gap:         0 (perfectly in sync)"
    fi

    echo ""

    # Also check for rules that differ in name (possible renames)
    ONLY_EBNF=$(comm -23 <(echo "$EBNF_RULES") <(echo "$PEST_RULES") | wc -l)
    ONLY_PEST=$(comm -23 <(echo "$PEST_RULES") <(echo "$EBNF_RULES") | wc -l)
    COMMON=$(comm -12 <(echo "$EBNF_RULES") <(echo "$PEST_RULES") | wc -l)

    echo "Summary: $COMMON shared, $ONLY_EBNF EBNF-only, $ONLY_PEST Pest-only"

# ═══════════════════════════════════════════════════════════════════════════════
# COMBINED WORKFLOWS
# ═══════════════════════════════════════════════════════════════════════════════

# Full pre-release check: all quality gates + verification + spec sync
preflight: check verify verify-harvard spec-check
    @echo ""
    @echo "All preflight checks passed. Ready for release."

# Full CI simulation: build, test, lint, verify, audit
ci: build test lint verify
    @echo "CI simulation passed."

# ═══════════════════════════════════════════════════════════════════════════════
# ONBOARDING & DIAGNOSTICS
# ═══════════════════════════════════════════════════════════════════════════════

# Check all required toolchain dependencies and report health
doctor:
    #!/usr/bin/env bash
    echo "═══════════════════════════════════════════════════"
    echo "  007 Lang Doctor — Toolchain Health Check"
    echo "═══════════════════════════════════════════════════"
    echo ""
    PASS=0; FAIL=0; WARN=0
    check() {
        local name="$1" cmd="$2" min="$3"
        if command -v "$cmd" >/dev/null 2>&1; then
            VER=$("$cmd" --version 2>&1 | head -1)
            echo "  [OK]   $name — $VER"
            PASS=$((PASS + 1))
        else
            echo "  [FAIL] $name — not found (need $min+)"
            FAIL=$((FAIL + 1))
        fi
    }
    check "just"              just      "1.25" 
    check "git"               git       "2.40" 
    check "Rust (cargo)"      cargo     "1.80" 
    # Optional tools
    if command -v panic-attack >/dev/null 2>&1; then
        echo "  [OK]   panic-attack — available"
        PASS=$((PASS + 1))
    else
        echo "  [WARN] panic-attack — not found (pre-commit scanner)"
        WARN=$((WARN + 1))
    fi
    echo ""
    echo "  Result: $PASS passed, $FAIL failed, $WARN warnings"
    if [ "$FAIL" -gt 0 ]; then
        echo "  Run 'just heal' to attempt automatic repair."
        exit 1
    fi
    echo "  All required tools present."

# Attempt to automatically install missing tools
heal:
    #!/usr/bin/env bash
    echo "═══════════════════════════════════════════════════"
    echo "  007 Lang Heal — Automatic Tool Installation"
    echo "═══════════════════════════════════════════════════"
    echo ""
    if ! command -v cargo >/dev/null 2>&1; then
        echo "Installing Rust via rustup..."
        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
        source "$HOME/.cargo/env"
    fi
    if ! command -v just >/dev/null 2>&1; then
        echo "Installing just..."
        cargo install just 2>/dev/null || echo "Install just from https://just.systems"
    fi
    echo ""
    echo "Heal complete. Run 'just doctor' to verify."

# Guided tour of the project structure and key concepts
tour:
    #!/usr/bin/env bash
    echo "═══════════════════════════════════════════════════"
    echo "  007 Lang — Guided Tour"
    echo "═══════════════════════════════════════════════════"
    echo ""
    echo '// SPDX-License-Identifier: MPL-2.0'
    echo ""
    echo "Key directories:"
    echo "  docs/                     Documentation" 
    echo "  tests/                    Test suite" 
    echo "  .github/workflows/        CI/CD workflows" 
    echo "  .machine_readable/        Machine-readable metadata" 
    echo "  examples/                 Usage examples" 
    echo ""
    echo "Quick commands:"
    echo "  just doctor    Check toolchain health"
    echo "  just heal      Fix missing tools"
    echo "  just help-me   Common workflows"
    echo "  just default   List all recipes"
    echo ""
    echo "Read more: README.adoc, EXPLAINME.adoc"

# Show help for common workflows
help-me:
    #!/usr/bin/env bash
    echo "═══════════════════════════════════════════════════"
    echo "  007 Lang — Common Workflows"
    echo "═══════════════════════════════════════════════════"
    echo ""
    echo "FIRST TIME SETUP:"
    echo "  just doctor           Check toolchain"
    echo "  just heal             Fix missing tools"
    echo ""
    echo "DEVELOPMENT:" 
    echo "  cargo build           Build the project" 
    echo "  cargo test            Run tests" 
    echo "" 
    echo "PRE-COMMIT:"
    echo "  just assail           Run panic-attacker scan"
    echo ""
    echo "LEARN:"
    echo "  just tour             Guided project tour"
    echo "  just default          List all recipes"


# Print the current CRG grade (reads from READINESS.md '**Current Grade:** X' line)
crg-grade:
    @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \
    [ -z "$$grade" ] && grade="X"; \
    echo "$$grade"

# Generate a shields.io badge markdown for the current CRG grade
# Looks for '**Current Grade:** X' in READINESS.md; falls back to X
crg-badge:
    @grade=$$(grep -oP '(?<=\*\*Current Grade:\*\* )[A-FX]' READINESS.md 2>/dev/null | head -1); \
    [ -z "$$grade" ] && grade="X"; \
    case "$$grade" in \
      A) color="brightgreen" ;; B) color="green" ;; C) color="yellow" ;; \
      D) color="orange" ;; E) color="red" ;; F) color="critical" ;; \
      *) color="lightgrey" ;; esac; \
    echo "[![CRG $$grade](https://img.shields.io/badge/CRG-$$grade-$$color?style=flat-square)](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades)"

# ═══════════════════════════════════════════════════════════════════════════════
# 007-MCP CARTRIDGE (BoJ)
# ═══════════════════════════════════════════════════════════════════════════════
# Source lives in cartridges/007-mcp/ (DD-24). The cartridge exposes the
# full oo7 CLI surface + on-enter/on-exit lifecycle hooks as MCP tools.
# Adapter binds loopback-only on 127.0.0.1:1066 (Idris2 IsLoopback proof).

# BoJ server repo root (override with BOJ_SERVER_DIR env-var).
BOJ_SERVER_DIR := env_var_or_default("BOJ_SERVER_DIR", "/var/mnt/eclipse/repos/boj-server")

# Build the 007-mcp cartridge (FFI + adapter + cartridge.json).
cartridge-build:
    @echo "→ Building 007-mcp FFI…"
    cd cartridges/007-mcp/ffi && zig build test && zig build
    @echo "→ Building 007-mcp adapter…"
    cd cartridges/007-mcp/adapter && zig build
    @echo "→ Generating cartridge.json from cartridge.ncl…"
    cd cartridges/007-mcp && nickel export --format json --output cartridge.json cartridge.ncl
    @echo "✓ 007-mcp built."

# Run 007-mcp cartridge tests.
cartridge-test:
    cd cartridges/007-mcp/ffi && zig build test
    cd cartridges/007-mcp/adapter && zig build test
    cd cartridges/007-mcp && nickel export --format json cartridge.ncl > /dev/null && echo "✓ cartridge.ncl valid"

# Deploy built cartridge into boj-server/cartridges/007-mcp/.
# Non-destructive: caller commits in boj-server repo separately.
cartridge-install: cartridge-build
    #!/usr/bin/env bash
    set -euo pipefail
    TARGET="${BOJ_SERVER_DIR}/cartridges/007-mcp"
    if [ ! -d "${BOJ_SERVER_DIR}" ]; then
      echo "! BOJ_SERVER_DIR='${BOJ_SERVER_DIR}' does not exist; set BOJ_SERVER_DIR" >&2
      exit 1
    fi
    echo "→ Installing 007-mcp into ${TARGET}…"
    mkdir -p "${TARGET}"/{abi/Oo7Mcp,ffi,adapter,schemas,docs}
    cp cartridges/007-mcp/cartridge.ncl               "${TARGET}/cartridge.ncl"
    cp cartridges/007-mcp/cartridge.json              "${TARGET}/cartridge.json"
    cp cartridges/007-mcp/README.adoc                 "${TARGET}/README.adoc"
    cp cartridges/007-mcp/abi/Oo7Mcp/SafeCli.idr      "${TARGET}/abi/Oo7Mcp/SafeCli.idr"
    cp cartridges/007-mcp/schemas/memory-tag-map.a2ml "${TARGET}/schemas/memory-tag-map.a2ml"
    if [ -d cartridges/007-mcp/ffi/zig-out ]; then
      cp -r cartridges/007-mcp/ffi/zig-out            "${TARGET}/ffi/zig-out"
    fi
    if [ -d cartridges/007-mcp/adapter/zig-out ]; then
      cp -r cartridges/007-mcp/adapter/zig-out        "${TARGET}/adapter/zig-out"
    fi
    echo "✓ 007-mcp installed at ${TARGET}"
    echo "  Remember: commit + push boj-server separately (GitHub is source of truth)."

# Run the adapter locally (for dev).
cartridge-run:
    cd cartridges/007-mcp/adapter && OO7_WORKTREE="$(pwd)/../../.." ./zig-out/bin/oo7_adapter

# Health probe against a running adapter.
cartridge-health:
    @curl -sS http://127.0.0.1:1066/health && echo

secret-scan-trufflehog:
    @command -v trufflehog >/dev/null && trufflehog filesystem . --only-verified || true