summercms/scripts/check-phase11.1.sh

#!/usr/bin/env bash
# Phase 11.1 fail-closed gate (documentation for humans and AI agents:
# DOCS-01 to DOCS-08).
#
# The semantic checks (identifiers, links and anchors, src= snippets,
# command names, consuming-application names, fence policy) live in Go and
# run through `go test` and `summer docs:build --check`. This script only
# orchestrates them and adds repository-level assertions: preconditions,
# the dependency delta, the built output and the forbidden-name sweep.
# --self-test plants one violation per rule in a scratch copy and requires
# docs:build --check to refuse it for that rule.
set -euo pipefail

ROOT="${PHASE11_1_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
PHASE11_DIR="$ROOT/.planning/phases/11-jobs-realtime-and-search-infrastructure"
DEPS_BASE="${PHASE11_1_DEPS_BASE:-9033d81}"
# Module paths this phase may add to go.mod (D-15).
ALLOWED_NEW_DEPS="github.com/alecthomas/chroma/v2 github.com/dlclark/regexp2/v2"
# Phase 11 modules that must be documented before the docs are written.
PHASE11_MODULES=(conga lighthouse flare beachcomber)
# D-11 consuming-application spellings, byte-level alternation so it works
# in any locale (the accented variant matches the Phase 11 hygiene regex).
FORBIDDEN_RE='fonoteka|p(l|ł|Ł)(y|ý|Ý)tarium'

usage() {
	cat >&2 <<'EOF'
usage:
  check-phase11.1.sh --preconditions
  check-phase11.1.sh --deps
  check-phase11.1.sh --docs
  check-phase11.1.sh --forbidden
  check-phase11.1.sh --claude
  check-phase11.1.sh --self-test
  check-phase11.1.sh --go
  check-phase11.1.sh --all
EOF
	exit 2
}

refuse() {
	echo "refuse: $*" >&2
	return 1
}

# build_summer compiles the summer tool into $1 once per mode.
build_summer() {
	(cd "$ROOT" && go build -o "$1" ./cmd/summer)
}

run_preconditions() {
	[ -f "$PHASE11_DIR/11-08-SUMMARY.md" ] || refuse "gap plan 11-08 has no SUMMARY (module READMEs are not stable yet)"
	local m
	for m in "${PHASE11_MODULES[@]}"; do
		[ -f "$ROOT/modules/$m/README.md" ] || refuse "modules/$m has no README.md"
		grep -qF "| [$m](modules/$m/README.md) |" "$ROOT/README.md" || refuse "root README has no table row for $m"
	done
	echo "phase11.1 preconditions passed"
}

# module_paths prints the module paths required by a go.mod file.
module_paths() {
	(cd "$ROOT" && go mod edit -json "$1") | python3 -c '
import json, sys
for r in json.load(sys.stdin).get("Require") or []:
    print(r["Path"])
' | sort -u
}

run_deps() {
	local tmp base now removed added dep
	tmp="$(mktemp -d)"
	trap 'rm -rf "$tmp"' RETURN
	git -C "$ROOT" show "$DEPS_BASE:go.mod" >"$tmp/base.mod"
	cp "$ROOT/go.mod" "$tmp/now.mod"
	base="$(module_paths "$tmp/base.mod")"
	now="$(module_paths "$tmp/now.mod")"
	removed="$(comm -23 <(echo "$base") <(echo "$now"))"
	[ -z "$removed" ] || refuse "go.mod dropped modules since $DEPS_BASE: $removed"
	added="$(comm -13 <(echo "$base") <(echo "$now"))"
	for dep in $added; do
		case " $ALLOWED_NEW_DEPS " in
		*" $dep "*) ;;
		*) refuse "go.mod added $dep, which no phase decision approves" ;;
		esac
	done
	# D-15: chroma/v2 highlights code at build time, as a direct requirement.
	(cd "$ROOT" && go mod edit -json) | python3 -c '
import json, sys
direct = [r for r in json.load(sys.stdin).get("Require") or [] if r["Path"] == "github.com/alecthomas/chroma/v2" and not r.get("Indirect")]
sys.exit(0 if direct else 1)
' || refuse "go.mod does not require github.com/alecthomas/chroma/v2 directly"
	if grep -q 'goldmark-highlighting' "$ROOT/go.mod"; then
		refuse "go.mod requires goldmark-highlighting (D-15 rejects it)"
	fi
	echo "phase11.1 deps passed"
}

run_docs() {
	local tmp site name
	tmp="$(mktemp -d)"
	trap 'rm -rf "$tmp"' RETURN
	build_summer "$tmp/summer"
	site="$tmp/site"
	(cd "$ROOT" && "$tmp/summer" docs:build --root "$ROOT" --out "$site") || refuse "docs:build failed"
	for name in index.html index.md llms.txt llms-full.txt search-index.json assets/site.css .summer-docs; do
		[ -f "$site/$name" ] || refuse "docs:build output has no $name"
	done
	if find "$site" -name '*.go' | grep -q .; then
		refuse "docs:build output contains .go files"
	fi
	echo "phase11.1 docs passed"
}

# forbidden_hits prints the files under the given paths that name a
# consuming application, never the matching lines.
forbidden_hits() {
	grep -rliE "$FORBIDDEN_RE" "$@" 2>/dev/null || true
}

run_forbidden() {
	local tmp hits
	tmp="$(mktemp -d)"
	trap 'rm -rf "$tmp"' RETURN
	build_summer "$tmp/summer"
	(cd "$ROOT" && "$tmp/summer" docs:build --root "$ROOT" --out "$tmp/site" >/dev/null) || refuse "docs:build failed"
	hits="$(forbidden_hits "$ROOT/docs" "$tmp/site")"
	[ -z "$hits" ] || refuse "consuming-application name in: $(echo "$hits" | sed "s|$tmp/||; s|$ROOT/||" | tr '\n' ' ')"
	echo "phase11.1 forbidden passed"
}

# The D-13 / DOCS-08 rules CLAUDE.md's Documentation section must carry.
CLAUDE_RULES=(
	'also updates the affected pages under `docs/` in the same change'
	'`go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check` check identifiers'
	'Every identifier named in a README or a docs page must exist in the package.'
	'Config keys named in README or docs pages are not checked automatically yet'
)

run_claude() {
	local section rule
	section="$(awk '/^## Documentation$/{on=1; next} /^## /{on=0} on' "$ROOT/CLAUDE.md")"
	[ -n "$section" ] || refuse "CLAUDE.md has no Documentation section"
	for rule in "${CLAUDE_RULES[@]}"; do
		grep -Fq -- "$rule" <<<"$section" || refuse "CLAUDE.md Documentation section is missing: $rule"
	done
	echo "phase11.1 claude passed"
}

run_go() {
	(cd "$ROOT" && go vet ./...)
	(cd "$ROOT" && go test ./...)
	echo "phase11.1 go passed"
}

# expect_refusal runs docs:build --check on the scratch root and requires a
# non-zero exit whose output names the rule.
expect_refusal() {
	local name="$1" want="$2" summer="$3" root="$4" output
	if output="$(cd "$root" && GOWORK=off "$summer" docs:build --check --root "$root" 2>&1)"; then
		echo "refuse: self-test accepted planted $name" >&2
		exit 1
	fi
	if ! grep -Fq -- "$want" <<<"$output"; then
		echo "refuse: self-test $name failed for the wrong rule: $output" >&2
		exit 1
	fi
}

# restore copies a pristine file back over its planted scratch copy.
restore() {
	cp "$1/$3" "$2/$3"
}

run_self_test() {
	bash -n "${BASH_SOURCE[0]}"
	local tmp scratch pristine summer
	tmp="$(mktemp -d)"
	trap 'rm -rf "$tmp"' RETURN
	scratch="$tmp/root"
	pristine="$tmp/pristine"
	summer="$tmp/summer"
	build_summer "$summer"
	mkdir -p "$scratch" "$pristine"
	cp -R "$ROOT/docs" "$ROOT/modules" "$ROOT/go.mod" "$ROOT/go.sum" "$scratch/"
	cp -R "$ROOT/docs" "$pristine/"

	(cd "$scratch" && GOWORK=off "$summer" docs:build --check --root "$scratch" >/dev/null) ||
		refuse "self-test baseline: the unplanted scratch copy does not pass docs:build --check"

	printf '\nSee `bonfire.NoSuchThing`.\n' >>"$scratch/docs/index.md"
	expect_refusal 'unknown identifier' 'identifier: bonfire.NoSuchThing does not exist in modules/bonfire' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	mkdir "$scratch/modules/zzplant"
	printf 'package zzplant\n' >"$scratch/modules/zzplant/zzplant.go"
	expect_refusal 'missing README' 'readme: package has Go files but no README.md' "$summer" "$scratch"
	rm -rf "$scratch/modules/zzplant"

	sed -i 's/Hello, %s/Hi, %s/' "$scratch/docs/setup/installation.md"
	expect_refusal 'drifted snippet' 'snippet: body differs' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/setup/installation.md

	sed -i '1a colour: red' "$scratch/docs/setup/installation.md"
	expect_refusal 'frontmatter typo' 'frontmatter: unknown field' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/setup/installation.md

	printf '\nSee [nowhere](#no-such-anchor).\n' >>"$scratch/docs/index.md"
	expect_refusal 'broken anchor' 'link: #no-such-anchor not found in' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	printf '\nRun `summer no:such`.\n' >>"$scratch/docs/index.md"
	expect_refusal 'unknown command' '"no:such" is not a summer or application command' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	# Built from two halves so this script's plant is not itself a hit.
	printf '\nThe %s%s application.\n' 'fono' 'teka' >>"$scratch/docs/index.md"
	expect_refusal 'forbidden name' 'forbidden: consuming-application name in output' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	printf '\n```go\nx := 1\n```\n' >>"$scratch/docs/index.md"
	expect_refusal 'go fence without src=' 'snippet: go code block has no src= reference' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	printf '\n> [!DANGER]\n> Planted.\n' >>"$scratch/docs/index.md"
	expect_refusal 'unknown callout' 'callout: unknown type DANGER (use NOTE, TIP or WARNING)' "$summer" "$scratch"
	restore "$pristine" "$scratch" docs/index.md

	echo "phase11.1 self-test passed"
}

case "${1:-}" in
--preconditions) run_preconditions ;;
--deps) run_deps ;;
--docs) run_docs ;;
--forbidden) run_forbidden ;;
--claude) run_claude ;;
--self-test) run_self_test ;;
--go) run_go ;;
--all)
	run_preconditions
	run_deps
	run_self_test
	run_docs
	run_forbidden
	run_claude
	run_go
	echo "phase11.1 all passed"
	;;
*) usage ;;
esac