diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml index 5af32f9..d9f9188 100644 --- a/.github/workflows/quality.yml +++ b/.github/workflows/quality.yml @@ -25,6 +25,8 @@ jobs: contents: read steps: - uses: actions/checkout@v7.0.1 + - name: STATE validator silence/firing controls + run: bash tests/validate_state_test.sh - name: Check file permissions run: | find . -type f -perm /111 -name "*.sh" | head -10 || true diff --git a/build/just/validate.just b/build/just/validate.just index af7f4d1..d185af2 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -53,13 +53,9 @@ validate-rsr: # Validate STATE.a2ml syntax validate-state: - @if [ -f ".machine_readable/descriptiles/STATE.a2ml" ]; then \ - grep -q '^\[metadata\]' .machine_readable/descriptiles/STATE.a2ml && \ - grep -q 'project\s*=' .machine_readable/descriptiles/STATE.a2ml && \ - echo "STATE.a2ml: valid" || echo "STATE.a2ml: INVALID (missing required sections)"; \ - else \ - echo "No .machine_readable/descriptiles/STATE.a2ml found"; \ - fi + #!/usr/bin/env bash + set -euo pipefail + bash scripts/validate-state.sh # Validate AI installation guide completeness (finishbot pre-release check) validate-ai-install: diff --git a/scripts/validate-state.sh b/scripts/validate-state.sh new file mode 100644 index 0000000..620c8ab --- /dev/null +++ b/scripts/validate-state.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Validate the required STATE.a2ml metadata section. +# Exit contract: 0 valid; 1 invalid project metadata; 2 unable to inspect input. +set -uo pipefail + +if [ "$#" -gt 1 ]; then + echo "validate-state: expected at most one STATE.a2ml path" >&2 + exit 2 +fi + +state="${1:-.machine_readable/descriptiles/STATE.a2ml}" +if [ ! -e "$state" ] || [ ! -f "$state" ]; then + echo "STATE.a2ml: INVALID (required file missing or not a regular file: $state)" >&2 + exit 1 +fi +if [ ! -r "$state" ]; then + echo "STATE.a2ml: INERT/SETUP (file is not readable: $state)" >&2 + exit 2 +fi + +metadata_seen=0 +project_seen=0 +in_metadata=0 + +while IFS= read -r line || [ -n "$line" ]; do + line="${line#"${line%%[![:space:]]*}"}" + + if [[ "$line" =~ ^\[([A-Za-z0-9_-]+)\][[:space:]]*(#.*)?$ ]]; then + section="${BASH_REMATCH[1]}" + if [ "$section" = "metadata" ]; then + metadata_seen=1 + in_metadata=1 + else + in_metadata=0 + fi + continue + fi + + if [ "$in_metadata" -eq 1 ] && [[ "$line" =~ ^project[[:space:]]*=[[:space:]]*(.*)$ ]]; then + value="${BASH_REMATCH[1]}" + value="${value#"${value%%[![:space:]]*}"}" + value="${value%"${value##*[![:space:]]}"}" + if [ -n "$value" ] && [ "$value" != '""' ] && [ "$value" != "''" ] && [[ ! "$value" =~ ^# ]]; then + project_seen=1 + fi + fi +done < "$state" + +if [ "$metadata_seen" -ne 1 ]; then + echo "STATE.a2ml: INVALID (missing [metadata] section)" >&2 + exit 1 +fi +if [ "$project_seen" -ne 1 ]; then + echo "STATE.a2ml: INVALID (missing non-empty project declaration inside [metadata])" >&2 + exit 1 +fi + +echo "STATE.a2ml: valid" diff --git a/tests/validate_state_test.sh b/tests/validate_state_test.sh new file mode 100644 index 0000000..c8a5f5d --- /dev/null +++ b/tests/validate_state_test.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Adversarial regression tests for the fail-closed STATE metadata validator. +set -euo pipefail + +REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +VALIDATOR="$REPO_ROOT/scripts/validate-state.sh" +WORK="$(mktemp -d)" +trap 'rm -rf "$WORK"' EXIT + +fail() { + echo "FAIL: $*" >&2 + if [ -f "$WORK/output" ]; then sed 's/^/ /' "$WORK/output" >&2; fi + exit 1 +} + +expect_rc() { + local expected="$1" label="$2" actual=0 + shift 2 + "$@" >"$WORK/output" 2>&1 || actual=$? + [ "$actual" -eq "$expected" ] || fail "$label: expected exit $expected, got $actual" + echo "PASS: $label (exit $actual)" +} + +mkdir -p "$WORK/valid" "$WORK/no-metadata" "$WORK/no-project" "$WORK/wrong-section" "$WORK/empty-project" +cat > "$WORK/valid/STATE.a2ml" <<'STATE' +# leading comments are harmless +[metadata] + project = "scaffoldia" +version = "0.1.0" + +[project-context] +name = "scaffoldia" +STATE + +cat > "$WORK/no-metadata/STATE.a2ml" <<'STATE' +[project-context] +project = "not metadata" +STATE + +cat > "$WORK/no-project/STATE.a2ml" <<'STATE' +[metadata] +version = "0.1.0" +STATE + +cat > "$WORK/wrong-section/STATE.a2ml" <<'STATE' +[metadata] +version = "0.1.0" + +[project-context] +project = "outside metadata" +STATE + +cat > "$WORK/empty-project/STATE.a2ml" <<'STATE' +[metadata] +project = "" + +[project-context] +name = "scaffoldia" +STATE + +expect_rc 0 "valid metadata and project declaration" bash "$VALIDATOR" "$WORK/valid/STATE.a2ml" +expect_rc 1 "missing required file is invalid" bash "$VALIDATOR" "$WORK/missing/STATE.a2ml" +expect_rc 1 "missing metadata section is invalid" bash "$VALIDATOR" "$WORK/no-metadata/STATE.a2ml" +expect_rc 1 "missing project declaration is invalid" bash "$VALIDATOR" "$WORK/no-project/STATE.a2ml" +expect_rc 1 "project outside metadata does not satisfy the contract" bash "$VALIDATOR" "$WORK/wrong-section/STATE.a2ml" +expect_rc 1 "empty project declaration is invalid" bash "$VALIDATOR" "$WORK/empty-project/STATE.a2ml" +expect_rc 2 "ambiguous arguments are setup failure" bash "$VALIDATOR" one two + +echo "PASS: all STATE metadata failure controls behaved as required"