From 1c76d1b1c1d5786bdb874919fb48167c3bc4b435 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:04:01 +0000 Subject: [PATCH 1/2] fix(validation): fail closed on missing or malformed STATE metadata (#70) --- build/just/validate.just | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/build/just/validate.just b/build/just/validate.just index af7f4d1..66fd2ea 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -53,13 +53,18 @@ 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"; \ + #!/usr/bin/env bash + set -euo pipefail + state=".machine_readable/descriptiles/STATE.a2ml" + if [ ! -f "$state" ]; then + echo "STATE.a2ml: INVALID (file missing)" >&2 + exit 1 + fi + if ! grep -Eq '^\[metadata\][[:space:]]*$' "$state" || ! grep -Eq '^[[:space:]]*project[[:space:]]*=' "$state"; then + echo "STATE.a2ml: INVALID (missing required sections)" >&2 + exit 1 fi + echo "STATE.a2ml: valid" # Validate AI installation guide completeness (finishbot pre-release check) validate-ai-install: From aa6948119cd538cabbb282fd339f7bf6f3a1724c Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 16 Nov 2026 16:47:24 +0000 Subject: [PATCH 2/2] fix: fail closed on invalid STATE metadata --- .github/workflows/quality.yml | 2 + build/just/validate.just | 11 +----- scripts/validate-state.sh | 61 +++++++++++++++++++++++++++++ tests/validate_state_test.sh | 72 +++++++++++++++++++++++++++++++++++ 4 files changed, 136 insertions(+), 10 deletions(-) create mode 100644 scripts/validate-state.sh create mode 100644 tests/validate_state_test.sh 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 66fd2ea..d185af2 100644 --- a/build/just/validate.just +++ b/build/just/validate.just @@ -55,16 +55,7 @@ validate-rsr: validate-state: #!/usr/bin/env bash set -euo pipefail - state=".machine_readable/descriptiles/STATE.a2ml" - if [ ! -f "$state" ]; then - echo "STATE.a2ml: INVALID (file missing)" >&2 - exit 1 - fi - if ! grep -Eq '^\[metadata\][[:space:]]*$' "$state" || ! grep -Eq '^[[:space:]]*project[[:space:]]*=' "$state"; then - echo "STATE.a2ml: INVALID (missing required sections)" >&2 - exit 1 - fi - echo "STATE.a2ml: valid" + 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"