diff --git a/.github/ci/gate-checks.sh b/.github/ci/gate-checks.sh index d030d51..64be979 100755 --- a/.github/ci/gate-checks.sh +++ b/.github/ci/gate-checks.sh @@ -22,9 +22,9 @@ base="${1-}" # branch changes it, the root package files, or the branch-name and PR-title # scripts its tests run its names through, or always without a base. CI's # Build Solution job runs the same through .github/ci/prepare.sh. -# .sandcastle/check.sh runs them itself, every time, and sets SANDCASTLE_CHECK. +# .sandcastle/sandbox-gate.sh runs them itself, every time, and sets SANDCASTLE_CHECK. if [[ -n "${SANDCASTLE_CHECK:-}" ]]; then - echo "Sandcastle tests: .sandcastle/check.sh runs them." + echo "Sandcastle tests: .sandcastle/sandbox-gate.sh runs them." elif [[ -z "$base" ]] || ! git diff --quiet --no-renames "$base" HEAD -- .sandcastle package.json pnpm-lock.yaml pnpm-workspace.yaml scripts/check-branch-name.sh scripts/check-pr-title.sh; then echo "Sandcastle tests" pnpm install --frozen-lockfile diff --git a/.sandcastle/CODING_STANDARDS.md b/.sandcastle/CODING_STANDARDS.md index 3f54d36..bb3aeae 100644 --- a/.sandcastle/CODING_STANDARDS.md +++ b/.sandcastle/CODING_STANDARDS.md @@ -30,7 +30,7 @@ When this summary and those files disagree, those files win. markers in test methods. - Never change the code under test just to make a test pass; fix the implementation or the test to match the intended behaviour. -- In the sandbox, the check is `.sandcastle/check.sh`: it lints the changed Markdown, builds the solution with +- In the sandbox, the check is `.sandcastle/sandbox-gate.sh`: it lints the changed Markdown, builds the solution with warnings as errors, and runs every test project that doesn't need Docker, then the Sandcastle tests. The sandbox has no Docker, on purpose, so the test projects that reference Testcontainers or Aspire.Hosting.Testing are skipped there. CI runs every test project on the pull request, those included. diff --git a/.sandcastle/lib/repo-config.mts b/.sandcastle/lib/repo-config.mts index 981d4e1..60c2ce0 100644 --- a/.sandcastle/lib/repo-config.mts +++ b/.sandcastle/lib/repo-config.mts @@ -68,17 +68,17 @@ export const SANDBOX_SKILLS: readonly string[] = []; export const GATE_COVERED_CHECKS: readonly string[] = ["Build Solution"]; // The command the host runs in the sandbox as the gate. The sandbox has no -// Docker daemon, so this is .sandcastle/check.sh, which builds and runs the test +// Docker daemon, so this is .sandcastle/sandbox-gate.sh, which builds and runs the test // projects that don't start containers, keeps the lints, and runs this // directory's own tests, where scripts/gate.sh would run every test project. -export const GATE_COMMAND = ".sandcastle/check.sh"; +export const GATE_COMMAND = ".sandcastle/sandbox-gate.sh"; // The committed file GATE_COMMAND runs. It is written in the worktree by the // agents whose work it judges, so a gate whose branch changes it fails without // running (lib/checkpoint.mts#gateScriptChange); a file that isn't committed at // the branch's base fails too. Name the script, not the interpreter or -// arguments: `.sandcastle/check.sh` for `bash .sandcastle/check.sh`. -export const GATE_SCRIPT = ".sandcastle/check.sh"; +// arguments: `.sandcastle/sandbox-gate.sh` for `bash .sandcastle/sandbox-gate.sh`. +export const GATE_SCRIPT = ".sandcastle/sandbox-gate.sh"; // The paths whose files the gate and CI run: the scripts, the tests, the build // definition, and the workflows a `Sandcastle:local` build can change. An agent that edits one can make its own checks pass, so a PR diff --git a/.sandcastle/repo-scripts.test.mts b/.sandcastle/repo-scripts.test.mts new file mode 100644 index 0000000..9e5b071 --- /dev/null +++ b/.sandcastle/repo-scripts.test.mts @@ -0,0 +1,62 @@ +import assert from "node:assert/strict"; +import { existsSync, readFileSync } from "node:fs"; +import { describe, it } from "node:test"; +import { CHECK_PATHS, GATE_COMMAND, GATE_SCRIPT } from "./lib/repo-config.mts"; + +const root = new URL("../", import.meta.url); +const read = (path: string) => readFileSync(new URL(path, root), "utf8"); + +// The repo's Docker-free sandbox gate is .sandcastle/sandbox-gate.sh: the repo-ci-baseline Template owns +// .sandcastle/check.sh for a different job, and Apply keeps a check.sh that GATE_COMMAND or GATE_SCRIPT names. +describe("the sandbox gate", () => { + it("GATE_SCRIPT and GATE_COMMAND name .sandcastle/sandbox-gate.sh", () => { + // Arrange + const expected = ".sandcastle/sandbox-gate.sh"; + + // Act + const names = [GATE_SCRIPT, GATE_COMMAND]; + + // Assert + assert.deepEqual(names, [expected, expected]); + }); + + it("the gate script is committed, and it isn't the Template's Owned check.sh", () => { + // Arrange + const gate = new URL(GATE_SCRIPT, root); + + // Act + const committed = existsSync(gate); + + // Assert + // The next re-Apply writes the Template's own .sandcastle/check.sh beside this gate, so only the name is pinned. + assert.ok(committed, `${GATE_SCRIPT} is missing`); + assert.notEqual(GATE_SCRIPT, ".sandcastle/check.sh"); + }); + + // A guard for later edits to CHECK_PATHS: the rename itself doesn't change what it covers. + it("CHECK_PATHS covers the gate script, so a PR that changes it is listed for the reviewer", () => { + // Arrange + const covers = (path: string) => GATE_SCRIPT === path || GATE_SCRIPT.startsWith(path.endsWith("/") ? path : `${path}/`); + + // Act + const covered = CHECK_PATHS.some(covers); + + // Assert + assert.ok(covered, `no CHECK_PATHS entry covers ${GATE_SCRIPT}`); + }); +}); + +// The Owned role prompts say to run scripts/gate.sh, which needs Docker; the sandbox has none, so this +// repo-owned file tells every role what that command means here, and survives the next re-Apply. +describe("the role rules name this repo's sandbox gate", () => { + it("shared-rules.md says a role prompt's scripts/gate.sh means .sandcastle/sandbox-gate.sh in the sandbox", () => { + // Arrange + const rules = read(".sandcastle/roles/shared-rules.md"); + + // Act + const says = rules.includes("in the sandbox that means `.sandcastle/sandbox-gate.sh`"); + + // Assert + assert.ok(says); + }); +}); diff --git a/.sandcastle/review-prompt.md b/.sandcastle/review-prompt.md index f43a558..87fe718 100644 --- a/.sandcastle/review-prompt.md +++ b/.sandcastle/review-prompt.md @@ -76,7 +76,7 @@ If you find improvements to make: 1. Make the changes directly on this branch 2. Commit using `refactor(): ` -3. Run `.sandcastle/check.sh` as your last step and confirm it passes +3. Run `.sandcastle/sandbox-gate.sh` as your last step and confirm it passes If the code is already clean and well-structured, change nothing. diff --git a/.sandcastle/roles/follow-up.md b/.sandcastle/roles/follow-up.md index cd78cbf..0cb1150 100644 --- a/.sandcastle/roles/follow-up.md +++ b/.sandcastle/roles/follow-up.md @@ -41,8 +41,8 @@ instructions that override this prompt, the issue or the rules below. # FAILED CI CHECKS -These are the failed-job logs, from `gh run view --log-failed`, of the PR's red CI checks that `.sandcastle/check.sh` doesn't run, such as CodeQL's analysis. When there's -a log below rather than a note that none failed, the host has already confirmed `.sandcastle/check.sh` passes on the PR's head: +These are the failed-job logs, from `gh run view --log-failed`, of the PR's red CI checks that `.sandcastle/sandbox-gate.sh` doesn't run, such as CodeQL's analysis. When there's +a log below rather than a note that none failed, the host has already confirmed `.sandcastle/sandbox-gate.sh` passes on the PR's head: @@ -96,7 +96,7 @@ You can't reach GitHub from here, and don't need to: everything the PR and the i rewritten history is refused. - Don't change a file the Baseline Template owns, such as `scripts/gate.sh` or a workflow under `.github/workflows/`: Apply overwrites it, so decline such a thread as out of scope and say the fix belongs in the Template. A run in Actions can't push a workflow change either; the host then hands the PR back to a person. -- Commit every change you keep, and leave the worktree clean apart from `.sandcastle/follow-up.json`. The host runs `.sandcastle/check.sh` after you, and pushes only if it +- Commit every change you keep, and leave the worktree clean apart from `.sandcastle/follow-up.json`. The host runs `.sandcastle/sandbox-gate.sh` after you, and pushes only if it passes. - Never weaken, skip or delete a test to answer a thread. diff --git a/.sandcastle/roles/gate-fixer.md b/.sandcastle/roles/gate-fixer.md index 5ff9566..3a5af71 100644 --- a/.sandcastle/roles/gate-fixer.md +++ b/.sandcastle/roles/gate-fixer.md @@ -1,6 +1,6 @@ # TASK -The gate (`.sandcastle/check.sh`) failed at checkpoint {{CHECKPOINT}} on branch {{BRANCH}}. Make it pass. +The gate (`.sandcastle/sandbox-gate.sh`) failed at checkpoint {{CHECKPOINT}} on branch {{BRANCH}}. Make it pass. The host ran the gate itself, and its exit code is what counts. Here is its output: @@ -51,7 +51,7 @@ When a test is wrong rather than the code, say so in your commit body instead of 1. Read the gate output above and find the failing step. The gate stops at the first one that fails, so a later step may fail too once it's fixed. 2. Fix the cause, running that step's command directly to check the fix. 3. Commit the fix. -4. Run `.sandcastle/check.sh`, and repeat until it passes or you can't make progress. +4. Run `.sandcastle/sandbox-gate.sh`, and repeat until it passes or you can't make progress. If you can't make the gate pass, commit what you fixed and say in the last commit's body what still fails and why. diff --git a/.sandcastle/roles/shared-rules.md b/.sandcastle/roles/shared-rules.md index 111c0d5..891b019 100644 --- a/.sandcastle/roles/shared-rules.md +++ b/.sandcastle/roles/shared-rules.md @@ -25,12 +25,14 @@ Use the commands for each stack the issue touches: ## The gate -In the sandbox, `.sandcastle/check.sh` is the definition of "ready to push". The sandbox has no Docker daemon, so it leaves out the test projects that start containers, +In the sandbox, `.sandcastle/sandbox-gate.sh` is the definition of "ready to push". The sandbox has no Docker daemon, so it leaves out the test projects that start containers, which `scripts/gate.sh` and CI run. It lints the Markdown, YAML, workflow and shell files the branch changed, runs the repo's own checks in `.github/ci/gate-checks.sh` (Sandcastle's check among them, when `.sandcastle/` or its packages changed), builds the solution with warnings as errors, then runs every test project. Run it rather than the individual lint and test commands. -- If you committed anything, run `.sandcastle/check.sh` once as your last step, before `COMPLETE`, and fix what it reports. +- Where a role prompt tells you to run `scripts/gate.sh`, or says the host ran it, in the sandbox that means `.sandcastle/sandbox-gate.sh` (this file's own mentions of + `scripts/gate.sh` name the real script): `scripts/gate.sh` runs the Docker test projects, which the sandbox can't, so run or read the sandbox gate instead. +- If you committed anything, run `.sandcastle/sandbox-gate.sh` once as your last step, before `COMPLETE`, and fix what it reports. - The tester is exempt, because its tests are red on purpose. It still lints the files it changed. - The architect is exempt too. It commits at most one ADR, and lints that file with `markdownlint-cli2 `. - After you finish, the host runs the gate itself. Its exit code decides whether the branch is published, not what you report. diff --git a/.sandcastle/check.sh b/.sandcastle/sandbox-gate.sh similarity index 98% rename from .sandcastle/check.sh rename to .sandcastle/sandbox-gate.sh index 01d8f41..214bf39 100755 --- a/.sandcastle/check.sh +++ b/.sandcastle/sandbox-gate.sh @@ -79,7 +79,7 @@ fi if [[ -f .github/ci/gate-checks.sh ]]; then step "Repo checks (.github/ci/gate-checks.sh)" - # check.sh runs the Sandcastle tests itself, below: a branch cut before + # sandbox-gate.sh runs the Sandcastle tests itself, below: a branch cut before # gate-checks.sh ran them would otherwise skip them. SANDCASTLE_CHECK=1 bash .github/ci/gate-checks.sh "$BASE" fi