From c247121c6c994a2e4f65bd6ab9796285f170a42a Mon Sep 17 00:00:00 2001 From: neal Date: Wed, 18 Nov 2026 15:52:48 -0500 Subject: [PATCH 1/2] feat(scripts): end every result run with a verdict and sharpen remedies A review of past sessions found agents piping check output through tail or grep, losing the exit status and missing unavailable rows. Every command printing a Result table now ends with one verdict line, naming its exit status and a count per state, from libs/result.sh's EXIT trap; summarize ends the same way. The same review found remedies that misled. Generated-By trailers were typed in a dozen spellings, so attribute-commit --check now refuses one that is not a model ID at commit-msg, and the Co-Authored-By fallback spells the display name as an ID. adr-index exits 0 when its rewrite runs by hand, failing only under pre-commit. doctor's remedy under a global core.hooksPath now installs the hooks, where pre-commit install refuses. payload-parity prints the cp that mirrors a pair when exactly one copy changed. The Go audit names the Go release that clears a failure found only in the local standard library, which CI's stable Go never reports. commitlint's ignores are functions a YAML config cannot hold, so a hand-written merge takes the default-ignored "Merge into " shape, now documented and tested. Generated-By: claude-opus-5-5 --- .commitlintrc.yaml | 5 + .pre-commit-config.yaml | 9 ++ CLAUDE.md | 8 +- .../docs/github_repository_structure.md | 6 +- .../src/base-repo/.commitlintrc.yaml | 5 + .../src/base-repo/.pre-commit-config.yaml | 9 ++ .../src/base-repo/CLAUDE.md | 2 +- .../src/base-repo/scripts/adr-index | 6 +- .../src/base-repo/scripts/attribute-commit | 71 ++++++++++++-- .../src/base-repo/scripts/clean | 4 +- .../src/base-repo/scripts/detect | 2 +- .../src/base-repo/scripts/doctor | 19 +++- .../src/base-repo/scripts/libs/detect.sh | 30 +++++- .../src/base-repo/scripts/libs/result.sh | 30 ++++++ .../src/base-repo/scripts/payload-parity | 27 +++++- .../src/base-repo/scripts/summarize | 20 +++- .../base-repo/scripts/tests/adr-index-test | 21 ++++- .../scripts/tests/attribute-commit-test | 93 +++++++++++++++++-- .../base-repo/scripts/tests/capabilities-test | 52 +++++++++++ .../base-repo/scripts/tests/commitlint-test | 13 +++ .../scripts/tests/payload-parity-test | 31 +++++++ .../scripts/tests/precommit-hooks-test | 23 +++++ .../base-repo/scripts/tests/result-gate-test | 10 ++ .../base-repo/scripts/tests/summarize-test | 13 ++- apps/repo-builder/src/scripts/retrofit.py | 2 +- scripts/CLAUDE.md | 6 +- scripts/adr-index | 6 +- scripts/attribute-commit | 71 ++++++++++++-- scripts/clean | 4 +- scripts/detect | 2 +- scripts/doctor | 19 +++- scripts/libs/detect.sh | 30 +++++- scripts/libs/result.sh | 30 ++++++ scripts/payload-parity | 27 +++++- scripts/summarize | 20 +++- scripts/tests/adr-index-test | 21 ++++- scripts/tests/attribute-commit-test | 93 +++++++++++++++++-- scripts/tests/capabilities-test | 52 +++++++++++ scripts/tests/commitlint-test | 13 +++ scripts/tests/payload-parity-test | 31 +++++++ scripts/tests/precommit-hooks-test | 23 +++++ scripts/tests/result-gate-test | 10 ++ scripts/tests/summarize-test | 13 ++- 43 files changed, 904 insertions(+), 78 deletions(-) diff --git a/.commitlintrc.yaml b/.commitlintrc.yaml index 879bd9bb..21534f59 100644 --- a/.commitlintrc.yaml +++ b/.commitlintrc.yaml @@ -11,6 +11,11 @@ # third is this repository's own. Everything else -- type-enum, subject-case, # header-max-length, body-max-line-length -- is the stock preset, at error # level already. +# +# There is no `ignores` list: commitlint's entries are functions, which YAML +# cannot hold. The default ignore list already passes GitHub's and git's own +# merge subjects, so a hand-written merge commit uses one of those shapes, +# `Merge into `, rather than a `Merge #12: title` this refuses. extends: - "@commitlint/config-conventional" diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e5609401..6936e0c5 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -194,6 +194,15 @@ repos: language: script stages: [prepare-commit-msg] + # The other half of the pair: refuses a Generated-By that is missing or + # is not a model ID, with the line to write. A reader at commit-msg, so + # its order against commitlint does not matter. + - id: attribution-check + name: check the Generated-By trailer names a model ID + entry: scripts/attribute-commit --check + language: script + stages: [commit-msg] + # These hooks let Git remove only stale administrative records for linked # worktrees whose directories have already disappeared. They never remove # a live worktree directory, and SessionStart reports candidates without diff --git a/CLAUDE.md b/CLAUDE.md index e4098b43..6b678517 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,13 +34,13 @@ Use these instead of per-language tools; each detects the languages present and - `scripts/repo-settings check` — inspect GitHub-hosted security and branch settings; run explicitly, since it needs the network and administration visibility - `scripts/check` — the full local gate: `doctor`, the script tests, lint, format, type check, test, build, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use - `scripts/fix` — the write half of `check`: lint autofix, then formatting, for every stack, unconditionally and in that order so the formatter lays out what the linter rewrote. Go, Swift and Kotlin have no lint autofix and report `lint-fix` `not-applicable`. A `lint-fix` FAIL means findings remain that need hand work -- `scripts/summarize ` — run a check and print only its Result table with findings, exiting with that command's status; read `ci` and other commands through this, since `check` already does +- `scripts/summarize ` — run a check and print only its Result table with findings, then a verdict line of its exit status and a count per state, exiting with that status; read `ci` and other commands through this, since `check` already does - `scripts/clean` — recursively delete build output and tool caches (`dist`, `build`, `coverage`, `__pycache__`, `.*_cache`, `*.pyc`) - `scripts/run [unit] [--entry ] [-- args…]` — start a unit per its declared `run` fact. The unit name is required when `apps/` holds several; `--entry` names one program from the unit's own language manifest (a `[project.scripts]` name, a `bin` key, a main package's import path) and is required when it declares several. Arguments after `--` pass through unchanged - `scripts/integration` — run every `tests/integration/` tier, at any scope. Kept out of the gate, since a tier may need a database, container, or network the gate cannot assume - `scripts/package [unit]` — deliver what the unit ships: an executable per declared target into its `dist/`, emptied first so no stale binary reaches a release, or its `deploy/quadlet/` files validated. Not part of the gate - `scripts/structure` — audit file placement against Layout below; run by `scripts/check` and by pre-commit on every commit -- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather than repairs, so a Dependabot bump merged into the root fails until it is mirrored. The shellcheck hook skips the payload's `scripts/` on the strength of it +- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather than repairs, so a Dependabot bump merged into the root fails until it is mirrored; where exactly one copy changed since `HEAD`, a finding ends with the `cp` command that mirrors it. The shellcheck hook skips the payload's `scripts/` on the strength of it Every check runs for every language present. Results distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL`, so an intentional no-op cannot look like a runner that executed. See `scripts/CLAUDE.md` before adding a language or a check. @@ -57,8 +57,8 @@ The only non-shell code here is the Python under `apps/repo-builder/`, declared - These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files and dotfiles included. Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`. - Work reaches `main` through a pull request under `.github/PULL_REQUEST_TEMPLATE.md`; a ruleset enforces it (Repository settings below). - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why. -- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the exact command running agree, so parallel agents in one session cannot cross-attribute; and it rewrites a stray `Co-Authored-By: `, since a tool is not a co-author; a human's `Co-Authored-By:` stays. It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. -- GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check. +- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the exact command running agree, so parallel agents in one session cannot cross-attribute; and it replaces a stray `Co-Authored-By: ` with that ID, or without one rewrites it as a `Generated-By` spelling the display name as an ID, since a tool is not a co-author; a human's `Co-Authored-By:` stays. It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. There `attribute-commit --check` refuses a value that is not a model ID (lowercase, no spaces, no `[1m]`-style suffix), since hand-typed display names made the record unsearchable; replayed commits pass. +- GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check. A hand-written merge subject takes one of those shapes, `Merge into `; `.commitlintrc.yaml` says why it holds no `ignores`. - A changed `CHANGELOG.md` is structurally checked at `pre-push`, and in CI over the pull-request range; that validates an entry, not whether one was owed. This repository keeps none: `CHANGELOG.md` is an addon at `apps/github-repository-template/src/repository-addons/CHANGELOG.md`, the only changelog the check fires on here. - The commit type signals a changelog entry without deciding it: `feat`, `fix`, and anything with `!` or a `BREAKING CHANGE:` footer usually owe one; `docs`, `style`, `test`, `ci`, and `chore` usually do not. Notability is judged per pull request. - Plan mode writes to the tracked `docs/plans/`, so a plan lands in the diff with its code. diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index ac633a6c..fe9e5104 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -81,7 +81,7 @@ The specific operating parameters for the AI agent. `scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. Exits with the gate's status either way. -`scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected. +`scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it, and ends with a verdict line naming that status and a count per state. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected. `scripts/run`: Starts a unit, dispatching on the `run` fact its `.unit.json` declares — a one-shot runs the program's own entry point, a long-lived one runs the dev server, `none` exits saying there is nothing to run. Names the unit when `apps/` holds several, since a run is one foreground process; `--entry ` names one of the programs the unit's own language manifest declares, required for the same reason when it declares several; everything after `--` reaches the program unchanged. @@ -95,7 +95,7 @@ The specific operating parameters for the AI agent. `scripts/structure`: Audits where files sit against the Layout rules it holds as code — the root folder and file allowlists, the `apps/` unit-and-domain shape, the closed folder vocabulary under a domain, `src/` placement, and the Markdown-only rule for `docs/`. Called by `scripts/check` and by pre-commit on every commit. It reads the contents of exactly one file, a unit's `.unit.json`, whose whole purpose is to state what a tree cannot show; the three rules that turn on what any other file contains are reported `not-applicable` rather than guessed. Reading a declaration needs `jq`, and its absence is reported `unavailable` rather than passed over. -`scripts/payload-parity`: Refuses a divergence between a repository's own `.github/` or `scripts/` and the copy a template payload ships to generated repositories, reading both which paths exist and what each one holds from the Git index, since it runs at pre-commit and the index is the tree being committed. `scripts/CLAUDE.md` is the one root-only path, since it documents this repository's scripts. The shellcheck hook skips the payload's `scripts/` because this check holds it identical to the root's. `.github/dependabot.yml` is the one named content exception, and it differs twice. Its language entries are derived per repository from the manifests that repository tracks, so the payload copy must not carry an entry for a manifest it does not ship while the root copy carries the entry its own `pyproject.toml` earns. And where a repository tracks a `.pre-commit-config.yaml` under a payload, its `pre-commit` entry names that second directory so a hook bump reaches both copies; a repository with no payload has no such directory to name. Both differences are by design rather than by drift. Presence is still checked, so neither copy may go missing; a payload file the root deliberately dropped is excused only where `generation.features` in `.repo-template.json` records the omission, which needs `jq` and is reported `unavailable` without it; a divergence the record cannot excuse is still named on a host without `jq`. Reports `not-applicable` in a repository with no payload, which is every repository generated from one. Called by `scripts/check` and by pre-commit on every commit. +`scripts/payload-parity`: Refuses a divergence between a repository's own `.github/` or `scripts/` and the copy a template payload ships to generated repositories, reading both which paths exist and what each one holds from the Git index, since it runs at pre-commit and the index is the tree being committed. `scripts/CLAUDE.md` is the one root-only path, since it documents this repository's scripts. The shellcheck hook skips the payload's `scripts/` because this check holds it identical to the root's. `.github/dependabot.yml` is the one named content exception, and it differs twice. Its language entries are derived per repository from the manifests that repository tracks, so the payload copy must not carry an entry for a manifest it does not ship while the root copy carries the entry its own `pyproject.toml` earns. And where a repository tracks a `.pre-commit-config.yaml` under a payload, its `pre-commit` entry names that second directory so a hook bump reaches both copies; a repository with no payload has no such directory to name. Both differences are by design rather than by drift. Presence is still checked, so neither copy may go missing; a payload file the root deliberately dropped is excused only where `generation.features` in `.repo-template.json` records the omission, which needs `jq` and is reported `unavailable` without it; a divergence the record cannot excuse is still named on a host without `jq`. Where exactly one copy of a pair changed since `HEAD`, its finding ends with the `cp` and `git add` that mirror it; where both or neither did, it names no direction. Reports `not-applicable` in a repository with no payload, which is every repository generated from one. Called by `scripts/check` and by pre-commit on every commit. `.structure-allow`: Convention (not a shipped file) for the permission the Layout rules refer to — one path per line to allow a named exception, a trailing `/` to stop the audit descending into a tracked fixture tree, save for one lookup that keeps a prefix over a domain's `src/` from failing the domain it defines. Absent until a repository needs one. @@ -137,7 +137,7 @@ Toolchain folders: `scripts/structure`'s `toolchain_folders` pairs a file with t `.pre-commit-config.yaml`: Local checks that run automatically before a commit. -`.commitlintrc.yaml`: Commit message rules (Conventional Commits), plus a required `Generated-By:` trailer naming the model that wrote the commit. `scripts/attribute-commit` writes that trailer at `prepare-commit-msg` from `CLAUDE_COMMIT_MODEL`, the model ID an agent's user-level hook exports, or else from the entry that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//` naming the exact command running, or by rewriting an agent's `Co-Authored-By` line; the rule is what makes a commit fail when the hook is not installed rather than land unattributed, and a commit written by hand adds the trailer itself or is refused. +`.commitlintrc.yaml`: Commit message rules (Conventional Commits), plus a required `Generated-By:` trailer naming the model that wrote the commit. `scripts/attribute-commit` writes that trailer at `prepare-commit-msg` from `CLAUDE_COMMIT_MODEL`, the model ID an agent's user-level hook exports, or else from the entry that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//` naming the exact command running, or by rewriting an agent's `Co-Authored-By` line; the rule is what makes a commit fail when the hook is not installed rather than land unattributed, and a commit written by hand adds the trailer itself or is refused. `attribute-commit --check` at `commit-msg` refuses a trailer value that is not a model ID, such as a display name. ### Additions by Occasion diff --git a/apps/github-repository-template/src/base-repo/.commitlintrc.yaml b/apps/github-repository-template/src/base-repo/.commitlintrc.yaml index 879bd9bb..21534f59 100644 --- a/apps/github-repository-template/src/base-repo/.commitlintrc.yaml +++ b/apps/github-repository-template/src/base-repo/.commitlintrc.yaml @@ -11,6 +11,11 @@ # third is this repository's own. Everything else -- type-enum, subject-case, # header-max-length, body-max-line-length -- is the stock preset, at error # level already. +# +# There is no `ignores` list: commitlint's entries are functions, which YAML +# cannot hold. The default ignore list already passes GitHub's and git's own +# merge subjects, so a hand-written merge commit uses one of those shapes, +# `Merge into `, rather than a `Merge #12: title` this refuses. extends: - "@commitlint/config-conventional" diff --git a/apps/github-repository-template/src/base-repo/.pre-commit-config.yaml b/apps/github-repository-template/src/base-repo/.pre-commit-config.yaml index 4eaf1ea3..9f144d70 100644 --- a/apps/github-repository-template/src/base-repo/.pre-commit-config.yaml +++ b/apps/github-repository-template/src/base-repo/.pre-commit-config.yaml @@ -152,6 +152,15 @@ repos: language: script stages: [prepare-commit-msg] + # The other half of the pair: refuses a Generated-By that is missing or + # is not a model ID, with the line to write. A reader at commit-msg, so + # its order against commitlint does not matter. + - id: attribution-check + name: check the Generated-By trailer names a model ID + entry: scripts/attribute-commit --check + language: script + stages: [commit-msg] + # These hooks let Git remove only stale administrative records for linked # worktrees whose directories have already disappeared. They never remove # a live worktree directory, and SessionStart reports candidates without diff --git a/apps/github-repository-template/src/base-repo/CLAUDE.md b/apps/github-repository-template/src/base-repo/CLAUDE.md index 4550db22..ad89aeb6 100644 --- a/apps/github-repository-template/src/base-repo/CLAUDE.md +++ b/apps/github-repository-template/src/base-repo/CLAUDE.md @@ -8,7 +8,7 @@ Use these instead of per-language tools. `check` and `fix` run for every languag - `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, script tests, structure, lint, format, type check, test, build, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything - `scripts/fix` — lint autofix, then formatting -- `scripts/summarize ` — run a check and print only its Result table; read `ci` and other commands through this, since `check` already does +- `scripts/summarize ` — run a check and print only its Result table, then a verdict line of its exit status and a count per state; read `ci` and other commands through this, since `check` already does - `scripts/run [unit] [--entry ] [-- args…]` — start a unit; the unit name is required when `apps/` holds several `ls scripts/` lists the rest, such as `doctor`, `integration`, and `package`. diff --git a/apps/github-repository-template/src/base-repo/scripts/adr-index b/apps/github-repository-template/src/base-repo/scripts/adr-index index f954c8d9..4ce9308b 100755 --- a/apps/github-repository-template/src/base-repo/scripts/adr-index +++ b/apps/github-repository-template/src/base-repo/scripts/adr-index @@ -156,7 +156,11 @@ fi # modified-files detection, which does not fire when the index is created for # the first time: the file is untracked at that moment, so pre-commit sees no # change to a file it knows about and the commit lands without the index in it. +# +# Only under pre-commit, which sets PRE_COMMIT=1 for its hooks. Run by hand, +# the rewrite is the job done, and exiting 1 for it stopped the rest of an +# `&&` chain that had just succeeded. if [[ "$before" != "$after" ]]; then echo "Rewrote $index. Stage it with the record that changed it." >&2 - exit 1 + [[ -z "${PRE_COMMIT:-}" ]] || exit 1 fi diff --git a/apps/github-repository-template/src/base-repo/scripts/attribute-commit b/apps/github-repository-template/src/base-repo/scripts/attribute-commit index 8e35e8df..b374e3ba 100755 --- a/apps/github-repository-template/src/base-repo/scripts/attribute-commit +++ b/apps/github-repository-template/src/base-repo/scripts/attribute-commit @@ -2,7 +2,8 @@ set -euo pipefail # Write the commit's Generated-By trailer at prepare-commit-msg, before -# commitlint reads the message. +# commitlint reads the message, and with --check at commit-msg refuse a +# trailer that is missing or names no model ID. # # A tool is not a co-author, but the model is worth keeping: it is the only # per-commit record of what produced the change. The model comes from outside @@ -30,8 +31,9 @@ set -euo pipefail # --amend run by an agent is stamped like any other commit, making the agent # its author of record. # -# A Co-Authored-By addressed to noreply@anthropic.com is rewritten first, from -# habit or with Claude Code's git instructions on, and the address dropped: it +# A Co-Authored-By addressed to noreply@anthropic.com, from habit or with +# Claude Code's git instructions on, gives way to the model ID when one is +# known and otherwise becomes a Generated-By with the address dropped: it # exists so GitHub can attribute a Co-Authored-By to an account, which does not # apply to a Generated-By naming a model. A human co-author keeps their line. # @@ -54,13 +56,15 @@ set -euo pipefail # other two arguments Git supplies -- the source and the commit object -- are # not read: the in-progress state above is what tells a replay apart. +check="" +if [[ "${1:-}" == --check ]]; then + check=1 + shift +fi + msg_file="${1:-}" [[ -n "$msg_file" && -f "$msg_file" ]] || exit 0 -sed -i -E \ - 's/^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$/Generated-By: \1/' \ - "$msg_file" - replaying() { local path for path in rebase-merge rebase-apply CHERRY_PICK_HEAD; do @@ -148,14 +152,61 @@ session_model() { matching_model "${cmdline%x}" } +# --check, at commit-msg: the trailer must name a model ID. The record is only +# worth keeping if it can be searched, and hand-typed trailers drifted into +# display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 (1M context)` +# -- beside the IDs, a dozen spellings for a handful of models. The shape is +# any vendor's ID, lowercase with no spaces, not a list of Claude models, +# which would refuse the next one. A missing trailer is refused here too, with +# the line to add, since commitlint's `trailer-exists` names only the rule. +# Replayed commits are passed: they keep the trailer they were written with. +if [[ -n "$check" ]]; then + replaying && exit 0 + values="$(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p')" + if [[ -z "$values" ]]; then + echo "No Generated-By trailer. End the message with a paragraph holding" >&2 + echo "'Generated-By: ', e.g. 'Generated-By: claude-opus-5-5'." >&2 + exit 1 + fi + while IFS= read -r value; do + if [[ ! "$value" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then + echo "Generated-By: '$value' is not a model ID. Write the ID, lowercase" >&2 + echo "with no spaces or [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 + exit 1 + fi + done <<< "$values" + exit 0 +fi + +# A context-window suffix such as [1m] is a setting, not part of the model ID. +model="${CLAUDE_COMMIT_MODEL:-}" +[[ -n "$model" ]] || model="$(session_model)" +model="${model%%\[*}" + +# Claude Code's own Co-Authored-By names the model by display name. Where the +# ID is known it replaces that line, being the same fact in a form that can be +# searched; otherwise the line becomes a Generated-By naming what it named, +# spelled as an ID so --check accepts it: lowercased, a parenthetical such as +# `(1M context)` dropped, and spaces and dots made hyphens, which turns +# `Claude Opus 5.5` into `claude-opus-5-5`. +co_author='^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$' +if [[ -n "$model" ]] && ! replaying; then + sed -i -E "/$co_author/d" "$msg_file" +else + sed -i -E "/$co_author/{ + s/$co_author/\1/ + s/[[:space:]]*\([^)]*\)//g + s/[[:space:].]+/-/g + y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/ + s/^/Generated-By: / + }" "$msg_file" +fi + # --if-exists add, because git compares keys case-insensitively and would # otherwise treat a lowercase trailer as this one and skip it. --no-divider # keeps a `---` body line from pulling the trailer up mid-message; commitlint, # whose parse stops at that line, then refuses the commit rather than # accepting a trailer buried in the body. -model="${CLAUDE_COMMIT_MODEL:-}" -[[ -n "$model" ]] || model="$(session_model)" - if [[ -n "$model" ]] && ! attributed && ! replaying; then git interpret-trailers --in-place --no-divider --if-exists add \ --trailer "Generated-By: $model" "$msg_file" diff --git a/apps/github-repository-template/src/base-repo/scripts/clean b/apps/github-repository-template/src/base-repo/scripts/clean index 419c457f..3b097b6b 100755 --- a/apps/github-repository-template/src/base-repo/scripts/clean +++ b/apps/github-repository-template/src/base-repo/scripts/clean @@ -34,4 +34,6 @@ find . \( "${prune[@]}" \) -prune -o \ # fetched dependencies' own trees, so it is removed whole here. rm -rf node_modules/.cache target/debug/.fingerprint "$CMAKE_BUILD_DIR" -echo "Cleaned common generated files and caches. Add project-specific cleanup to scripts/clean." +# Project-specific cleanup goes above this line. The hint lives here rather +# than in the output, where every run repeated it to a reader who only cleaned. +echo "Cleaned common generated files and caches." diff --git a/apps/github-repository-template/src/base-repo/scripts/detect b/apps/github-repository-template/src/base-repo/scripts/detect index f08ea607..e73d2524 100755 --- a/apps/github-repository-template/src/base-repo/scripts/detect +++ b/apps/github-repository-template/src/base-repo/scripts/detect @@ -15,7 +15,7 @@ Usage: scripts/detect languages Present languages, one per line github-output language=true|false lines, plus trivy, for $GITHUB_OUTPUT codeql-matrix matrix= for $GITHUB_OUTPUT, for the CodeQL job's strategy - probe Every capability and language pairing, wired or absent + probe Which checks exist: every capability and language pairing, wired or absent EOF } diff --git a/apps/github-repository-template/src/base-repo/scripts/doctor b/apps/github-repository-template/src/base-repo/scripts/doctor index 45d48614..4adcc6b1 100755 --- a/apps/github-repository-template/src/base-repo/scripts/doctor +++ b/apps/github-repository-template/src/base-repo/scripts/doctor @@ -85,10 +85,23 @@ if [[ -s .pre-commit-config.yaml ]]; then else uninstalled="$(pre_commit_hooks_missing .pre-commit-config.yaml)" + # `pre-commit install` refuses while core.hooksPath is set at any scope, + # and a machine-wide one is common, so the remedy there is the recipe that + # does not refuse: shims from init-templatedir, with the key pointed at them + # for this clone alone. Every configured type is written, not only the + # missing ones, because the key moves git off the directory holding the + # rest. The global key is never unset: every other repository reads it. if [[ -n "$uninstalled" ]]; then - while IFS= read -r hook_type; do - record "no $hook_type hook in this clone; run: pre-commit install" - done <<<"$uninstalled" + hooks_path="$(git config core.hooksPath || true)" + if [[ -n "$hooks_path" ]]; then + shims="$(git rev-parse --path-format=absolute --git-common-dir)/pre-commit-shims" + type_flags="$(pre_commit_hook_types .pre-commit-config.yaml | sed 's/^/-t /' | paste -sd ' ' -)" + record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $shims && git config --local core.hooksPath $shims/hooks, leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" + else + while IFS= read -r hook_type; do + record "no $hook_type hook in this clone; run: pre-commit install" + done <<<"$uninstalled" + fi fi verdict pre-commit "every configured hook is installed" fi diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh index ed5be4c1..14bf9922 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/detect.sh @@ -666,7 +666,35 @@ _capability_audit_python() { uv audit --help >/dev/null 2>&1 || return "$NO_RUNNER" uv audit --preview-features audit-command } -_capability_audit_go() { command -v govulncheck >/dev/null 2>&1 || return "$NO_RUNNER"; go_each govulncheck ./...; } +_capability_audit_go() { command -v govulncheck >/dev/null 2>&1 || return "$NO_RUNNER"; go_each _govulncheck_module; } + +# govulncheck audits the standard library of the Go that runs it, and +# security.yml installs go-version: stable, so a local Go behind stable fails +# here on CVEs CI never reports, and the findings read as the code's. The audit +# still fails, since the local binary does carry them; when every finding is in +# the standard library and has a fix, one line after the output names the Go +# that clears them all. +_govulncheck_module() { + local out status=0 + out="$(govulncheck ./... 2>&1)" || status=$? + printf '%s\n' "$out" + (( status == 0 )) || _govulncheck_stdlib_note "$out" + return "$status" +} +_govulncheck_stdlib_note() { + local found fixed local_go needed + found="$(sed -n 's/^ *Found in: //p' <<< "$1")" + fixed="$(sed -n 's/^ *Fixed in: [^@ ]*@\(go[0-9][^ ]*\)$/\1/p' <<< "$1")" + # A fix naming a Go release for every finding means each is in the standard + # library and has one; a module's fix names a module version instead. + [[ -n "$found" ]] || return 0 + (( $(wc -l <<< "$found") == $(grep -c . <<< "$fixed") )) || return 0 + local_go="${found##*@}" + needed="$(sort -V <<< "$fixed" | tail -n 1)" + echo "Every finding is in the standard library of $local_go and fixed by $needed;" + echo "CI audits with go-version: stable and reports none of them. Install $needed" + echo "or later, or rerun with GOTOOLCHAIN=$needed+auto." +} _capability_audit_rust() { command -v cargo-audit >/dev/null 2>&1 || return "$NO_RUNNER"; cargo audit; } _capability_audit_swift() { command -v trivy >/dev/null 2>&1 || return "$NO_RUNNER"; trivy_each Package.resolved; } _capability_audit_kotlin() { command -v trivy >/dev/null 2>&1 || return "$NO_RUNNER"; trivy_each gradle.lockfile; } diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/result.sh b/apps/github-repository-template/src/base-repo/scripts/libs/result.sh index 1f4dbfb6..7e008c1f 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/result.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/result.sh @@ -27,6 +27,9 @@ result_failed=0 +# Results printed per state, for the verdict line below. +declare -A result_counts=([FAIL]=0 [unavailable]=0 [not-applicable]=0 [pass]=0 [would-run]=0) + # The layout alone: result_line . What result prints # once it has judged the state, and what a table that is not a set of Results # -- the capability probe, whose words are wired and absent -- prints so it @@ -46,6 +49,7 @@ result() { ;; esac result_line "$1" "$2" "$3" + result_counts[$2]=$(( result_counts[$2] + 1 )) } # Findings for the check currently being run, printed under its result line by @@ -77,3 +81,29 @@ verdict() { tally() { return "$result_failed" } + +# The verdict, printed as the process exits: the command, its exit status, and +# a count per state, in the line scripts/summarize ends with. A reader who keeps +# only the end of the output -- `| tail`, which also hides the exit status +# behind its own -- still gets both, and unavailable is counted beside FAIL +# rather than left for a FAIL-only grep to miss. An EXIT trap rather than a +# line in tally, because tally is also called mid-command (`tally || exit 1`) +# and the status worth reporting is the one the process ends with. +# +# Printed only once a result line was, so a script sourcing these libraries for +# their helpers stays silent. A subshell neither inherits the trap nor passes +# its counts back, so a result belongs in the shell that exits. Installed only +# where no EXIT trap is set yet, so the test harness keeps its cleanup; a +# script that sets its own afterwards replaces this one, and calls +# result_exit_verdict from it to keep the line. +result_exit_verdict() { + local status=$? state line="" total=0 + for state in FAIL unavailable not-applicable pass would-run; do + total=$(( total + result_counts[$state] )) + [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue + line+=" ${result_counts[$state]} $state," + done + (( total > 0 )) && echo "$0 exited $status:${line%,}" + return "$status" +} +[[ -n "$(trap -p EXIT)" ]] || trap result_exit_verdict EXIT diff --git a/apps/github-repository-template/src/base-repo/scripts/payload-parity b/apps/github-repository-template/src/base-repo/scripts/payload-parity index 52152a8e..0b68d26d 100755 --- a/apps/github-repository-template/src/base-repo/scripts/payload-parity +++ b/apps/github-repository-template/src/base-repo/scripts/payload-parity @@ -82,6 +82,29 @@ holds() { [[ $'\n'"$1"$'\n' == *$'\n'"$2"$'\n'* ]] } +# Whether a path's staged content differs from HEAD's: which copy of a +# diverged pair was edited. A missing HEAD reads as edited, so a first commit +# names no direction. +staged_edit() { + ! git diff --cached --quiet HEAD -- "$1" 2> /dev/null +} + +# The command that mirrors a diverged pair, where the staged edit settles its +# direction: exactly one copy changed since HEAD. Otherwise nothing, since a +# merged root bump changes neither copy and an edit to both changes both, and +# guessing a direction there overwrites the newer copy. +mirror_command() { + local root_copy="$1" payload_copy="$payload_root/$1" from to + if staged_edit "$root_copy" && ! staged_edit "$payload_copy"; then + from="$root_copy" to="$payload_copy" + elif staged_edit "$payload_copy" && ! staged_edit "$root_copy"; then + from="$payload_copy" to="$root_copy" + else + return 0 + fi + printf '; run: mkdir -p %q && cp %q %q && git add %q %q' "${to%/*}" "$from" "$to" "$from" "$to" +} + # The paths under each tree, relative to the root: the payload's prefix is # stripped, so one path names both copies. quotePath is off so a non-ASCII # filename arrives literally rather than C-quoted into a path that does not @@ -140,7 +163,7 @@ while IFS= read -r path; do if ! holds "$payload_paths" "$path"; then holds "$root_only" "$path" || - record "$path is in the root and not in the payload; add it to $payload_root/$path" + record "$path is in the root and not in the payload; add it to $payload_root/$path$(mirror_command "$path")" elif holds "$payload_only" "$path"; then holds "$omitted" "$path" || record "$path is in the payload and not in the root; mirror it, or record the omission under generation.features in $record_file" @@ -152,7 +175,7 @@ while IFS= read -r path; do ! git cat-file -e ":$payload_root/$path" 2> /dev/null; then record "$path cannot be read from the index; finish the merge before asking whether the trees agree" elif ! cmp -s <(git show ":$path") <(git show ":$payload_root/$path"); then - record "$path differs between the two trees; mirror the change into the other" + record "$path differs between the two trees; mirror the change into the other$(mirror_command "$path")" fi fi done < <(printf '%s\n%s\n' "$root_paths" "$payload_paths" | sort -u) diff --git a/apps/github-repository-template/src/base-repo/scripts/summarize b/apps/github-repository-template/src/base-repo/scripts/summarize index 7d2a4a60..25f0d163 100755 --- a/apps/github-repository-template/src/base-repo/scripts/summarize +++ b/apps/github-repository-template/src/base-repo/scripts/summarize @@ -18,7 +18,8 @@ set -uo pipefail # pass. # # Exits with the command's own status, so it can stand in for the command in a -# gate rather than only in a report. +# gate rather than only in a report, and ends with a verdict line naming that +# status and a count per state. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -37,7 +38,7 @@ status=$? # is a tool's own output -- cargo indents its progress -- and is dropped, after # a pass or after a FAIL's findings alike. Exit 1 from awk means the table held # nothing that failed. -awk ' +table="$(awk ' /^[A-Za-z0-9_-]+ +(pass|not-applicable|unavailable|FAIL|would-run)( |$)/ { print; under = ($2 == "FAIL"); if ($2 == "FAIL" || $2 == "unavailable") failed = 1; next } @@ -45,10 +46,11 @@ awk ' /^ [^ ]/ { if (under) print; next } { under = 0 } END { exit failed ? 0 : 1 } -' <<< "$output" +' <<< "$output")" # grep's convention: 0 means the table held a failing state, not that awk # succeeded. Named for what it answers, since every read below is negated. table_reported_failure=$? +[[ -z "$table" ]] || printf '%s\n' "$table" # Not everything a check command runs reports through the Result table: the # script suites print their own tally, and pre-commit prints its own hook list. @@ -77,4 +79,16 @@ if (( status != 0 && table_reported_failure != 0 )); then fi fi +# The verdict, always the last line: the exit status and a count per state. +# A reader who keeps only the end of the output -- `| tail`, which also hides +# the exit status behind its own -- still gets both, and an unavailable check +# is counted beside FAIL rather than left for a FAIL-only grep to miss. +verdict="$1 exited $status:" +for state in FAIL unavailable not-applicable pass would-run; do + count="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" + [[ "$state" == would-run && "$count" == 0 ]] && continue + verdict+=" $count $state," +done +echo "${verdict%,}" + exit "$status" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/adr-index-test b/apps/github-repository-template/src/base-repo/scripts/tests/adr-index-test index f42a8c66..ed125835 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/adr-index-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/adr-index-test @@ -104,10 +104,11 @@ fi # Regeneration is the check, so the script must report the rewrite itself. A # newly created index is untracked at that moment and pre-commit's own -# modified-files detection does not see it. +# modified-files detection does not see it. PRE_COMMIT=1 is what pre-commit +# sets for its hooks. fixture "a rewrite is reported" record 0001-a.md "A" accepted -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && grep -q "Rewrote $index" <<<"$out"; then pass @@ -115,6 +116,18 @@ else fail "creating the index did not fail the run, so a commit lands without it" fi +# Run by hand the rewrite is the job done; a failing exit stops the `&&` chain +# after it. +fixture "a rewrite run by hand succeeds" +record 0001-a.md "A" accepted +out="$(cd "$work" && env -u PRE_COMMIT scripts/adr-index 2>&1)" +status=$? +if (( status == 0 )) && grep -q "Rewrote $index" <<<"$out" && [[ -f "$work/$index" ]]; then + pass +else + fail "a rewrite outside pre-commit exited $status: $out" +fi + # Without this the hook fails forever: every commit touching an ADR would # rewrite an already-correct file. fixture "a correct index is left alone" @@ -134,7 +147,7 @@ record 0001-a.md "A" accepted (cd "$work" && scripts/adr-index) > /dev/null 2>&1 expected="$(cat "$work/$index")" echo "hand-written note" >> "$work/$index" -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && [[ "$expected" == "$(cat "$work/$index")" ]]; then pass @@ -157,7 +170,7 @@ fixture "removing the last record removes the index" record 0001-a.md "A" accepted (cd "$work" && scripts/adr-index) > /dev/null 2>&1 rm "$work/docs/adrs/0001-a.md" -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && [[ ! -e "$work/$index" ]]; then pass diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test b/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test index b3d9d969..f004d263 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test @@ -78,7 +78,21 @@ out="$(rewrite "feat: add a thing A body. Co-Authored-By: Claude Opus 5 ")" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5" ]]; then + pass +else + fail "the rewritten message parses as: $(trailers "$out")" +fi + +# The fallback spells the display name as an ID, so --check accepts what it +# wrote rather than refusing an agent commit made without the hook. +fixture "a display name in the agent trailer is spelled as an ID" +out="$(rewrite "feat: add a thing + +A body. + +Co-Authored-By: Claude Opus 5.5 (1M context) ")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5-5" ]]; then pass else fail "the rewritten message parses as: $(trailers "$out")" @@ -105,7 +119,7 @@ A body. Co-Authored-By: Claude Opus 5 Co-Authored-By: A Human ")" -if [[ "$(trailers "$out")" == $'Generated-By: Claude Opus 5\nCo-Authored-By: A Human ' ]]; then +if [[ "$(trailers "$out")" == $'Generated-By: claude-opus-5\nCo-Authored-By: A Human ' ]]; then pass else fail "the pair parses as: $(trailers "$out")" @@ -148,13 +162,15 @@ else fail "the message parses as: $(trailers "$out")" fi -fixture "a rewritten Co-Authored-By is kept over the session's model" +# The display name Claude Code writes is the same fact as the ID, in a form +# --check refuses, so the known ID takes its place. +fixture "the session's model replaces an agent Co-Authored-By" out="$(rewrite "feat: add a thing A body. Co-Authored-By: Claude Opus 5 " claude-opus-5-5)" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5-5" ]]; then pass else fail "the message parses as: $(trailers "$out")" @@ -373,7 +389,7 @@ else fail "the message parses as: $(trailers "$out")" fi -fixture "a rewritten Co-Authored-By is kept over an entry" +fixture "an entry's model replaces an agent Co-Authored-By" entry sess-1 glm-5.1 "$(commit_cmd)" out="$(claude_rewrite "feat: add a thing @@ -381,12 +397,77 @@ A body. Co-Authored-By: Claude Opus 5 " "$(commit_cmd)" \ CLAUDE_CODE_SESSION_ID=sess-1)" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: glm-5.1" ]]; then pass else fail "the message parses as: $(trailers "$out")" fi +fixture "a context-window suffix is dropped from the model" +out="$(rewrite "feat: add a thing + +A body." "claude-opus-5[1m]")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5" ]]; then + pass +else + fail "the message parses as: $(trailers "$out")" +fi + +# --check at commit-msg: prints nothing and exits 0 for a model ID, refuses +# anything else with the line to write. +verify() { + printf '%s\n' "$1" > "$work/COMMIT_EDITMSG" + (cd "$work" && "$script" --check "$work/COMMIT_EDITMSG" 2>&1) +} + +fixture "--check accepts a model ID" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5-5')" +status=$? +out2="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: gpt-5.1-codex')" +status2=$? +if (( status == 0 && status2 == 0 )) && [[ -z "$out$out2" ]]; then + pass +else + fail "a model ID was refused (exit $status, $status2): $out $out2" +fi + +fixture "--check refuses a display name" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: Claude Opus 5.5 (1M context)')" +status=$? +if (( status != 0 )) && grep -q "is not a model ID" <<< "$out"; then + pass +else + fail "a display name passed, exit $status: $out" +fi + +fixture "--check refuses a context-window suffix" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5[1m]')" +status=$? +if (( status != 0 )); then + pass +else + fail "a [1m] suffix passed: $out" +fi + +fixture "--check names the line a missing trailer needs" +out="$(verify $'feat: add a thing\n\nA body.')" +status=$? +if (( status != 0 )) && grep -q "Generated-By: " <<< "$out"; then + pass +else + fail "a missing trailer was not refused with the fix, exit $status: $out" +fi + +fixture "--check passes a replayed commit" +mkdir -p "$work/.git/rebase-merge" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: Claude Opus 5')" +status=$? +if (( status == 0 )); then + pass +else + fail "a replayed commit's old trailer was refused: $out" +fi + # git calls this hook for every commit, including ones whose message is already # a trailer's worth of nothing. Rewriting an absent file must not fail the commit. fixture "a missing message file is not an error" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test index c387b681..6cd66cde 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test @@ -441,6 +441,58 @@ else fail "trivy scanned $(tr '\n' ' ' < "$work/scanned")rather than both lockfiles" fi +# --- a Go audit failing only on the local standard library says so ----------- + +# govulncheck reports the standard library of the Go that runs it, and CI runs +# stable, so stdlib-only findings fixed in a newer Go are named as such. One +# finding in a module is the code's own, and gets no such line. +govulncheck_stub() { + stub govulncheck <&1 ' and not as '#N: title'" +into="$(attempt "Merge feature/x into main")" +into_status=$? +numbered="$(attempt "Merge #12: title")" +numbered_status=$? +if (( into_status == 0 && numbered_status != 0 )); then + pass +else + fail "wanted 'into' accepted and '#N:' refused, got $into_status and $numbered_status: $into $numbered" +fi + # body-leading-blank is a warning in config-conventional and an error here. The # rule name is asserted rather than just the exit status, since a malformed # message fails for several reasons and only one of them is this rule. diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test b/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test index 0f7f89f4..a084a2b8 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test @@ -121,6 +121,37 @@ write ".github/workflows/ci.yml" changed audit assert_fails ".github/workflows/ci.yml differs" +# The direction is settled by which copy changed since HEAD, so these cases +# commit the agreeing trees first. The printed command, run verbatim, is the +# fix; where both copies changed it names none rather than guess. +commit_fixture() { + stage + git -C "$work" commit -q -m "chore: agreeing trees" +} + +parity_fixture "an edit to one copy names the command that mirrors it" +commit_fixture +write ".github/workflows/ci.yml" changed +audit +fix="$(sed -n 's/.*; run: //p' "$work/.audit-output")" +if [[ "$fix" == "mkdir -p $payload/workflows && cp .github/workflows/ci.yml $payload/workflows/ci.yml && git add"* ]] \ + && (cd "$work" && eval "$fix") && run_parity && (( parity_status == 0 )); then + pass +else + fail "wanted a root-to-payload command that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" +fi + +parity_fixture "an edit to both copies names no direction" +commit_fixture +write ".github/workflows/ci.yml" one +write "$payload/workflows/ci.yml" two +audit +if (( parity_status != 0 )) && ! grep -q '; run:' "$work/.audit-output"; then + pass +else + fail "wanted a FAIL with no command, got: $(cat "$work/.audit-output")" +fi + parity_fixture "a root file absent from the payload fails" write .github/workflows/release.yml audit diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test b/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test index bcf4ec86..f89c935d 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test @@ -147,4 +147,27 @@ repos: []' fi fi +# A machine-wide core.hooksPath makes `pre-commit install` refuse, so the fix +# doctor prints there must be one that works with the key set: run verbatim, +# it leaves nothing missing, and the global key is untouched. +if command -v pre-commit >/dev/null 2>&1; then + fixture "doctor's remedy under a global core.hooksPath installs every hook" 'default_install_hook_types: [pre-commit, commit-msg] +repos: []' + printf '[core]\n\thooksPath = %s\n' "$work/global-hooks" > "$work/global-config" + remedy="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" scripts/doctor 2>&1 \ + | sed -n 's/.*so run: \(.*\), leaving init.templateDir.*/\1/p')" + if [[ -z "$remedy" ]] || [[ "$remedy" == *"pre-commit install"* ]]; then + fail "wanted the init-templatedir remedy, got: '$remedy'" + else + (cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" eval "$remedy" > /dev/null 2>&1) + got="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" pre_commit_hooks_missing .pre-commit-config.yaml)" + global="$(GIT_CONFIG_GLOBAL="$work/global-config" git config --global core.hooksPath)" + if [[ -z "$got" && "$global" == "$work/global-hooks" ]]; then + pass + else + fail "after the remedy, missing '$got', global key '$global'" + fi + fi +fi + report diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/result-gate-test b/apps/github-repository-template/src/base-repo/scripts/tests/result-gate-test index 007c9afd..f8227c47 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/result-gate-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/result-gate-test @@ -67,6 +67,16 @@ bare_package "$work" out="$(cd "$work" && scripts/ci 2>&1)" assert_unavailable $? 'lint +unavailable +node' "$out" +# The last line is what `| tail -1` keeps, so it alone must carry the exit +# status and count unavailable beside FAIL. +current="ci ends with a verdict naming its status and the unavailable lines" +want_unavailable="$(grep -cE '^[A-Za-z0-9_-]+ +unavailable( |$)' <<< "$out")" +if [[ "$(tail -n 1 <<< "$out")" =~ ^scripts/ci\ exited\ 1:\ 0\ FAIL,\ ${want_unavailable}\ unavailable,\ [0-9]+\ not-applicable,\ [0-9]+\ pass$ ]]; then + pass +else + fail "wanted a closing verdict with $want_unavailable unavailable, got: $(tail -n 1 <<< "$out")" +fi + fixture "fix fails on a language with no formatter" bare_package "$work" out="$(cd "$work" && scripts/fix 2>&1)" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/summarize-test b/apps/github-repository-template/src/base-repo/scripts/tests/summarize-test index 516261e1..49dd6687 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/summarize-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/summarize-test @@ -4,7 +4,8 @@ set -uo pipefail # What summarize keeps and what it drops. The cases run a stub command rather # than a real check, so they assert the filter's contract -- the layout # libs/result.sh documents -- and not the current output of any one check. They -# also hold that it exits with the command's own status, and that a failure +# also hold that it exits with the command's own status, that its last line is +# a verdict carrying that status and a count per state, and that a failure # outside the table leaves the whole run in tmp/summarize-failure.log. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" @@ -90,6 +91,16 @@ else fail "wanted the dropped output in tmp/summarize-failure.log" fi +# The last line is what `| tail -1` keeps, so it alone must carry the exit +# status and count unavailable beside FAIL. +current="the last line is the verdict, after any notice" +if [[ "$(tail -n 1 <<< "$out2")" == "bash exited 1: 1 FAIL, 1 unavailable, 1 not-applicable, 1 pass" ]] \ + && [[ "$(tail -n 1 <<< "$out")" == "bash exited 3: 0 FAIL, 0 unavailable, 0 not-applicable, 1 pass" ]]; then + pass +else + fail "wanted a closing verdict line, got: $(tail -n 1 <<< "$out2") / $(tail -n 1 <<< "$out")" +fi + current="a FAIL in the table needs no such notice" if ! grep -q 'outside the' <<< "$out2"; then pass diff --git a/apps/repo-builder/src/scripts/retrofit.py b/apps/repo-builder/src/scripts/retrofit.py index af4c5a47..3a65ba8e 100755 --- a/apps/repo-builder/src/scripts/retrofit.py +++ b/apps/repo-builder/src/scripts/retrofit.py @@ -911,7 +911,7 @@ def autofix(arguments: argparse.Namespace) -> dict[str, object]: SHIM_MARKER = "File generated by pre-commit" HOOK_TEST_FILE = "docs/retrofit-hook-test.md" AGENT_TRAILER = "Co-Authored-By: Retrofit Hook Test " -REWRITTEN_TRAILER = "Generated-By: Retrofit Hook Test" +REWRITTEN_TRAILER = "Generated-By: retrofit-hook-test" MESSAGE_HOOK_TYPES = ("prepare-commit-msg", "commit-msg") diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md index 5d12e747..eeadcd73 100644 --- a/scripts/CLAUDE.md +++ b/scripts/CLAUDE.md @@ -12,15 +12,15 @@ Each script's header comment says what it does and why it is shaped that way, an - Run by a person: `doctor`, `check`, `fix`, `clean`, `run`, `integration`, `package`, `summarize`, `repo-settings check` - Called by `.github/`: `ci`, `security`, `release`, `detect`, `changelog-check`, `system-packages`, `script-tests` -- Called by pre-commit: `adr-index`, `structure`, `payload-parity`, `attribute-commit` (`prepare-commit-msg`), `changelog-check` and `protect-branch` (`pre-push`), `worktree-cleanup` (`post-checkout`, `post-merge`, and SessionStart with `--report`) +- Called by pre-commit: `adr-index`, `structure`, `payload-parity`, `attribute-commit` (`prepare-commit-msg`, and `--check` at `commit-msg`), `changelog-check` and `protect-branch` (`pre-push`), `worktree-cleanup` (`post-checkout`, `post-merge`, and SessionStart with `--report`) - Sourced: `libs/detect.sh`, `libs/result.sh`, `libs/unit.sh`, `libs/precommit.sh`, `libs/dependabot.sh`, `libs/quadlet.sh`, `tests/libs/harness.sh` ## Local Contracts - **`libs/detect.sh` owns every language decision.** Commands name a capability, never an adapter; `DETECT_LANGUAGES` and `DETECT_PRUNE_DIRS` are the lists. -- **The toolchains are the machine's, not a pinned set.** `check` runs whatever compiler, linter, and formatter the machine has; `.github/actions/setup-toolchains` installs each fresh on the runner (`go-version: stable`, `node-version: lts/*`, `swift-version: latest`, `rustup component add` over a rustup the host must already have). pre-commit pins what it owns by `rev`, so a check that passes locally and fails in CI is a version difference before it is a flaky runner. rustup is the one prerequisite neither installs; the setup action and `security.yml`'s cargo-audit step fail with one line naming the host. Pin a toolchain in the repository that has the language: a pin shipped from the payload obliges every generated repository to bump a file for a language it may not have, and Dependabot has no ecosystem for any of them. +- **The toolchains are the machine's, not a pinned set.** `check` runs whatever compiler, linter, and formatter the machine has; `.github/actions/setup-toolchains` installs each fresh on the runner (`go-version: stable`, `node-version: lts/*`, `swift-version: latest`, `rustup component add` over a rustup the host must already have). pre-commit pins what it owns by `rev`, so a check that passes locally and fails in CI is a version difference before it is a flaky runner, and the reverse holds for the Go audit, which reads the local Go's standard library and names the release that clears a failure found only there. rustup is the one prerequisite neither installs; the setup action and `security.yml`'s cargo-audit step fail with one line naming the host. Pin a toolchain in the repository that has the language: a pin shipped from the payload obliges every generated repository to bump a file for a language it may not have, and Dependabot has no ecosystem for any of them. - **A check that did not run is not a check that passed.** `unavailable` fails the run whenever the check was expected. -- **`libs/result.sh`'s printed layout is an interface**, parsed by `summarize`; `tally` is a command's last line and its exit status. +- **`libs/result.sh`'s printed layout is an interface**, parsed by `summarize`; `tally` is a command's exit status, and the verdict its EXIT trap prints (` exited : `) is the last line, in the shape `summarize` ends with. Print results in the shell that exits, since a subshell's counts never reach the trap, and a script setting its own EXIT trap calls `result_exit_verdict` from it. - **A check owns no stdin.** `script-tests` closes fd 0 for each suite and `check` for `structure`, and the dispatch closes it for every capability but `run`, so a stdin-draining tool cannot hang the gate. The `*_each` helpers take their list on fd 3, and pipes end in a variable, never a reader that exits early, since `pipefail` turns SIGPIPE into 141, read as absent. - **An adapter is honest about what it did.** Capture the tool's exit status, not only its output. No function stands in for an absent one: the probe reads `absent` off the function table and the dispatch reports `unavailable`. A runner that exits non-zero without a real failure is translated, and `libs/detect.sh`'s header lists the four. - **`libs/*.sh` and `harness.sh` are sourced, never executed**: no shebang, no executable bit, `.sh`. Every other script is extensionless and executable; pre-commit reads a shebang only on one. diff --git a/scripts/adr-index b/scripts/adr-index index f954c8d9..4ce9308b 100755 --- a/scripts/adr-index +++ b/scripts/adr-index @@ -156,7 +156,11 @@ fi # modified-files detection, which does not fire when the index is created for # the first time: the file is untracked at that moment, so pre-commit sees no # change to a file it knows about and the commit lands without the index in it. +# +# Only under pre-commit, which sets PRE_COMMIT=1 for its hooks. Run by hand, +# the rewrite is the job done, and exiting 1 for it stopped the rest of an +# `&&` chain that had just succeeded. if [[ "$before" != "$after" ]]; then echo "Rewrote $index. Stage it with the record that changed it." >&2 - exit 1 + [[ -z "${PRE_COMMIT:-}" ]] || exit 1 fi diff --git a/scripts/attribute-commit b/scripts/attribute-commit index 8e35e8df..b374e3ba 100755 --- a/scripts/attribute-commit +++ b/scripts/attribute-commit @@ -2,7 +2,8 @@ set -euo pipefail # Write the commit's Generated-By trailer at prepare-commit-msg, before -# commitlint reads the message. +# commitlint reads the message, and with --check at commit-msg refuse a +# trailer that is missing or names no model ID. # # A tool is not a co-author, but the model is worth keeping: it is the only # per-commit record of what produced the change. The model comes from outside @@ -30,8 +31,9 @@ set -euo pipefail # --amend run by an agent is stamped like any other commit, making the agent # its author of record. # -# A Co-Authored-By addressed to noreply@anthropic.com is rewritten first, from -# habit or with Claude Code's git instructions on, and the address dropped: it +# A Co-Authored-By addressed to noreply@anthropic.com, from habit or with +# Claude Code's git instructions on, gives way to the model ID when one is +# known and otherwise becomes a Generated-By with the address dropped: it # exists so GitHub can attribute a Co-Authored-By to an account, which does not # apply to a Generated-By naming a model. A human co-author keeps their line. # @@ -54,13 +56,15 @@ set -euo pipefail # other two arguments Git supplies -- the source and the commit object -- are # not read: the in-progress state above is what tells a replay apart. +check="" +if [[ "${1:-}" == --check ]]; then + check=1 + shift +fi + msg_file="${1:-}" [[ -n "$msg_file" && -f "$msg_file" ]] || exit 0 -sed -i -E \ - 's/^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$/Generated-By: \1/' \ - "$msg_file" - replaying() { local path for path in rebase-merge rebase-apply CHERRY_PICK_HEAD; do @@ -148,14 +152,61 @@ session_model() { matching_model "${cmdline%x}" } +# --check, at commit-msg: the trailer must name a model ID. The record is only +# worth keeping if it can be searched, and hand-typed trailers drifted into +# display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 (1M context)` +# -- beside the IDs, a dozen spellings for a handful of models. The shape is +# any vendor's ID, lowercase with no spaces, not a list of Claude models, +# which would refuse the next one. A missing trailer is refused here too, with +# the line to add, since commitlint's `trailer-exists` names only the rule. +# Replayed commits are passed: they keep the trailer they were written with. +if [[ -n "$check" ]]; then + replaying && exit 0 + values="$(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p')" + if [[ -z "$values" ]]; then + echo "No Generated-By trailer. End the message with a paragraph holding" >&2 + echo "'Generated-By: ', e.g. 'Generated-By: claude-opus-5-5'." >&2 + exit 1 + fi + while IFS= read -r value; do + if [[ ! "$value" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then + echo "Generated-By: '$value' is not a model ID. Write the ID, lowercase" >&2 + echo "with no spaces or [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 + exit 1 + fi + done <<< "$values" + exit 0 +fi + +# A context-window suffix such as [1m] is a setting, not part of the model ID. +model="${CLAUDE_COMMIT_MODEL:-}" +[[ -n "$model" ]] || model="$(session_model)" +model="${model%%\[*}" + +# Claude Code's own Co-Authored-By names the model by display name. Where the +# ID is known it replaces that line, being the same fact in a form that can be +# searched; otherwise the line becomes a Generated-By naming what it named, +# spelled as an ID so --check accepts it: lowercased, a parenthetical such as +# `(1M context)` dropped, and spaces and dots made hyphens, which turns +# `Claude Opus 5.5` into `claude-opus-5-5`. +co_author='^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$' +if [[ -n "$model" ]] && ! replaying; then + sed -i -E "/$co_author/d" "$msg_file" +else + sed -i -E "/$co_author/{ + s/$co_author/\1/ + s/[[:space:]]*\([^)]*\)//g + s/[[:space:].]+/-/g + y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/ + s/^/Generated-By: / + }" "$msg_file" +fi + # --if-exists add, because git compares keys case-insensitively and would # otherwise treat a lowercase trailer as this one and skip it. --no-divider # keeps a `---` body line from pulling the trailer up mid-message; commitlint, # whose parse stops at that line, then refuses the commit rather than # accepting a trailer buried in the body. -model="${CLAUDE_COMMIT_MODEL:-}" -[[ -n "$model" ]] || model="$(session_model)" - if [[ -n "$model" ]] && ! attributed && ! replaying; then git interpret-trailers --in-place --no-divider --if-exists add \ --trailer "Generated-By: $model" "$msg_file" diff --git a/scripts/clean b/scripts/clean index 419c457f..3b097b6b 100755 --- a/scripts/clean +++ b/scripts/clean @@ -34,4 +34,6 @@ find . \( "${prune[@]}" \) -prune -o \ # fetched dependencies' own trees, so it is removed whole here. rm -rf node_modules/.cache target/debug/.fingerprint "$CMAKE_BUILD_DIR" -echo "Cleaned common generated files and caches. Add project-specific cleanup to scripts/clean." +# Project-specific cleanup goes above this line. The hint lives here rather +# than in the output, where every run repeated it to a reader who only cleaned. +echo "Cleaned common generated files and caches." diff --git a/scripts/detect b/scripts/detect index f08ea607..e73d2524 100755 --- a/scripts/detect +++ b/scripts/detect @@ -15,7 +15,7 @@ Usage: scripts/detect languages Present languages, one per line github-output language=true|false lines, plus trivy, for $GITHUB_OUTPUT codeql-matrix matrix= for $GITHUB_OUTPUT, for the CodeQL job's strategy - probe Every capability and language pairing, wired or absent + probe Which checks exist: every capability and language pairing, wired or absent EOF } diff --git a/scripts/doctor b/scripts/doctor index 45d48614..4adcc6b1 100755 --- a/scripts/doctor +++ b/scripts/doctor @@ -85,10 +85,23 @@ if [[ -s .pre-commit-config.yaml ]]; then else uninstalled="$(pre_commit_hooks_missing .pre-commit-config.yaml)" + # `pre-commit install` refuses while core.hooksPath is set at any scope, + # and a machine-wide one is common, so the remedy there is the recipe that + # does not refuse: shims from init-templatedir, with the key pointed at them + # for this clone alone. Every configured type is written, not only the + # missing ones, because the key moves git off the directory holding the + # rest. The global key is never unset: every other repository reads it. if [[ -n "$uninstalled" ]]; then - while IFS= read -r hook_type; do - record "no $hook_type hook in this clone; run: pre-commit install" - done <<<"$uninstalled" + hooks_path="$(git config core.hooksPath || true)" + if [[ -n "$hooks_path" ]]; then + shims="$(git rev-parse --path-format=absolute --git-common-dir)/pre-commit-shims" + type_flags="$(pre_commit_hook_types .pre-commit-config.yaml | sed 's/^/-t /' | paste -sd ' ' -)" + record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $shims && git config --local core.hooksPath $shims/hooks, leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" + else + while IFS= read -r hook_type; do + record "no $hook_type hook in this clone; run: pre-commit install" + done <<<"$uninstalled" + fi fi verdict pre-commit "every configured hook is installed" fi diff --git a/scripts/libs/detect.sh b/scripts/libs/detect.sh index ed5be4c1..14bf9922 100644 --- a/scripts/libs/detect.sh +++ b/scripts/libs/detect.sh @@ -666,7 +666,35 @@ _capability_audit_python() { uv audit --help >/dev/null 2>&1 || return "$NO_RUNNER" uv audit --preview-features audit-command } -_capability_audit_go() { command -v govulncheck >/dev/null 2>&1 || return "$NO_RUNNER"; go_each govulncheck ./...; } +_capability_audit_go() { command -v govulncheck >/dev/null 2>&1 || return "$NO_RUNNER"; go_each _govulncheck_module; } + +# govulncheck audits the standard library of the Go that runs it, and +# security.yml installs go-version: stable, so a local Go behind stable fails +# here on CVEs CI never reports, and the findings read as the code's. The audit +# still fails, since the local binary does carry them; when every finding is in +# the standard library and has a fix, one line after the output names the Go +# that clears them all. +_govulncheck_module() { + local out status=0 + out="$(govulncheck ./... 2>&1)" || status=$? + printf '%s\n' "$out" + (( status == 0 )) || _govulncheck_stdlib_note "$out" + return "$status" +} +_govulncheck_stdlib_note() { + local found fixed local_go needed + found="$(sed -n 's/^ *Found in: //p' <<< "$1")" + fixed="$(sed -n 's/^ *Fixed in: [^@ ]*@\(go[0-9][^ ]*\)$/\1/p' <<< "$1")" + # A fix naming a Go release for every finding means each is in the standard + # library and has one; a module's fix names a module version instead. + [[ -n "$found" ]] || return 0 + (( $(wc -l <<< "$found") == $(grep -c . <<< "$fixed") )) || return 0 + local_go="${found##*@}" + needed="$(sort -V <<< "$fixed" | tail -n 1)" + echo "Every finding is in the standard library of $local_go and fixed by $needed;" + echo "CI audits with go-version: stable and reports none of them. Install $needed" + echo "or later, or rerun with GOTOOLCHAIN=$needed+auto." +} _capability_audit_rust() { command -v cargo-audit >/dev/null 2>&1 || return "$NO_RUNNER"; cargo audit; } _capability_audit_swift() { command -v trivy >/dev/null 2>&1 || return "$NO_RUNNER"; trivy_each Package.resolved; } _capability_audit_kotlin() { command -v trivy >/dev/null 2>&1 || return "$NO_RUNNER"; trivy_each gradle.lockfile; } diff --git a/scripts/libs/result.sh b/scripts/libs/result.sh index 1f4dbfb6..7e008c1f 100644 --- a/scripts/libs/result.sh +++ b/scripts/libs/result.sh @@ -27,6 +27,9 @@ result_failed=0 +# Results printed per state, for the verdict line below. +declare -A result_counts=([FAIL]=0 [unavailable]=0 [not-applicable]=0 [pass]=0 [would-run]=0) + # The layout alone: result_line . What result prints # once it has judged the state, and what a table that is not a set of Results # -- the capability probe, whose words are wired and absent -- prints so it @@ -46,6 +49,7 @@ result() { ;; esac result_line "$1" "$2" "$3" + result_counts[$2]=$(( result_counts[$2] + 1 )) } # Findings for the check currently being run, printed under its result line by @@ -77,3 +81,29 @@ verdict() { tally() { return "$result_failed" } + +# The verdict, printed as the process exits: the command, its exit status, and +# a count per state, in the line scripts/summarize ends with. A reader who keeps +# only the end of the output -- `| tail`, which also hides the exit status +# behind its own -- still gets both, and unavailable is counted beside FAIL +# rather than left for a FAIL-only grep to miss. An EXIT trap rather than a +# line in tally, because tally is also called mid-command (`tally || exit 1`) +# and the status worth reporting is the one the process ends with. +# +# Printed only once a result line was, so a script sourcing these libraries for +# their helpers stays silent. A subshell neither inherits the trap nor passes +# its counts back, so a result belongs in the shell that exits. Installed only +# where no EXIT trap is set yet, so the test harness keeps its cleanup; a +# script that sets its own afterwards replaces this one, and calls +# result_exit_verdict from it to keep the line. +result_exit_verdict() { + local status=$? state line="" total=0 + for state in FAIL unavailable not-applicable pass would-run; do + total=$(( total + result_counts[$state] )) + [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue + line+=" ${result_counts[$state]} $state," + done + (( total > 0 )) && echo "$0 exited $status:${line%,}" + return "$status" +} +[[ -n "$(trap -p EXIT)" ]] || trap result_exit_verdict EXIT diff --git a/scripts/payload-parity b/scripts/payload-parity index 52152a8e..0b68d26d 100755 --- a/scripts/payload-parity +++ b/scripts/payload-parity @@ -82,6 +82,29 @@ holds() { [[ $'\n'"$1"$'\n' == *$'\n'"$2"$'\n'* ]] } +# Whether a path's staged content differs from HEAD's: which copy of a +# diverged pair was edited. A missing HEAD reads as edited, so a first commit +# names no direction. +staged_edit() { + ! git diff --cached --quiet HEAD -- "$1" 2> /dev/null +} + +# The command that mirrors a diverged pair, where the staged edit settles its +# direction: exactly one copy changed since HEAD. Otherwise nothing, since a +# merged root bump changes neither copy and an edit to both changes both, and +# guessing a direction there overwrites the newer copy. +mirror_command() { + local root_copy="$1" payload_copy="$payload_root/$1" from to + if staged_edit "$root_copy" && ! staged_edit "$payload_copy"; then + from="$root_copy" to="$payload_copy" + elif staged_edit "$payload_copy" && ! staged_edit "$root_copy"; then + from="$payload_copy" to="$root_copy" + else + return 0 + fi + printf '; run: mkdir -p %q && cp %q %q && git add %q %q' "${to%/*}" "$from" "$to" "$from" "$to" +} + # The paths under each tree, relative to the root: the payload's prefix is # stripped, so one path names both copies. quotePath is off so a non-ASCII # filename arrives literally rather than C-quoted into a path that does not @@ -140,7 +163,7 @@ while IFS= read -r path; do if ! holds "$payload_paths" "$path"; then holds "$root_only" "$path" || - record "$path is in the root and not in the payload; add it to $payload_root/$path" + record "$path is in the root and not in the payload; add it to $payload_root/$path$(mirror_command "$path")" elif holds "$payload_only" "$path"; then holds "$omitted" "$path" || record "$path is in the payload and not in the root; mirror it, or record the omission under generation.features in $record_file" @@ -152,7 +175,7 @@ while IFS= read -r path; do ! git cat-file -e ":$payload_root/$path" 2> /dev/null; then record "$path cannot be read from the index; finish the merge before asking whether the trees agree" elif ! cmp -s <(git show ":$path") <(git show ":$payload_root/$path"); then - record "$path differs between the two trees; mirror the change into the other" + record "$path differs between the two trees; mirror the change into the other$(mirror_command "$path")" fi fi done < <(printf '%s\n%s\n' "$root_paths" "$payload_paths" | sort -u) diff --git a/scripts/summarize b/scripts/summarize index 7d2a4a60..25f0d163 100755 --- a/scripts/summarize +++ b/scripts/summarize @@ -18,7 +18,8 @@ set -uo pipefail # pass. # # Exits with the command's own status, so it can stand in for the command in a -# gate rather than only in a report. +# gate rather than only in a report, and ends with a verdict line naming that +# status and a count per state. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" @@ -37,7 +38,7 @@ status=$? # is a tool's own output -- cargo indents its progress -- and is dropped, after # a pass or after a FAIL's findings alike. Exit 1 from awk means the table held # nothing that failed. -awk ' +table="$(awk ' /^[A-Za-z0-9_-]+ +(pass|not-applicable|unavailable|FAIL|would-run)( |$)/ { print; under = ($2 == "FAIL"); if ($2 == "FAIL" || $2 == "unavailable") failed = 1; next } @@ -45,10 +46,11 @@ awk ' /^ [^ ]/ { if (under) print; next } { under = 0 } END { exit failed ? 0 : 1 } -' <<< "$output" +' <<< "$output")" # grep's convention: 0 means the table held a failing state, not that awk # succeeded. Named for what it answers, since every read below is negated. table_reported_failure=$? +[[ -z "$table" ]] || printf '%s\n' "$table" # Not everything a check command runs reports through the Result table: the # script suites print their own tally, and pre-commit prints its own hook list. @@ -77,4 +79,16 @@ if (( status != 0 && table_reported_failure != 0 )); then fi fi +# The verdict, always the last line: the exit status and a count per state. +# A reader who keeps only the end of the output -- `| tail`, which also hides +# the exit status behind its own -- still gets both, and an unavailable check +# is counted beside FAIL rather than left for a FAIL-only grep to miss. +verdict="$1 exited $status:" +for state in FAIL unavailable not-applicable pass would-run; do + count="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" + [[ "$state" == would-run && "$count" == 0 ]] && continue + verdict+=" $count $state," +done +echo "${verdict%,}" + exit "$status" diff --git a/scripts/tests/adr-index-test b/scripts/tests/adr-index-test index f42a8c66..ed125835 100755 --- a/scripts/tests/adr-index-test +++ b/scripts/tests/adr-index-test @@ -104,10 +104,11 @@ fi # Regeneration is the check, so the script must report the rewrite itself. A # newly created index is untracked at that moment and pre-commit's own -# modified-files detection does not see it. +# modified-files detection does not see it. PRE_COMMIT=1 is what pre-commit +# sets for its hooks. fixture "a rewrite is reported" record 0001-a.md "A" accepted -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && grep -q "Rewrote $index" <<<"$out"; then pass @@ -115,6 +116,18 @@ else fail "creating the index did not fail the run, so a commit lands without it" fi +# Run by hand the rewrite is the job done; a failing exit stops the `&&` chain +# after it. +fixture "a rewrite run by hand succeeds" +record 0001-a.md "A" accepted +out="$(cd "$work" && env -u PRE_COMMIT scripts/adr-index 2>&1)" +status=$? +if (( status == 0 )) && grep -q "Rewrote $index" <<<"$out" && [[ -f "$work/$index" ]]; then + pass +else + fail "a rewrite outside pre-commit exited $status: $out" +fi + # Without this the hook fails forever: every commit touching an ADR would # rewrite an already-correct file. fixture "a correct index is left alone" @@ -134,7 +147,7 @@ record 0001-a.md "A" accepted (cd "$work" && scripts/adr-index) > /dev/null 2>&1 expected="$(cat "$work/$index")" echo "hand-written note" >> "$work/$index" -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && [[ "$expected" == "$(cat "$work/$index")" ]]; then pass @@ -157,7 +170,7 @@ fixture "removing the last record removes the index" record 0001-a.md "A" accepted (cd "$work" && scripts/adr-index) > /dev/null 2>&1 rm "$work/docs/adrs/0001-a.md" -out="$(cd "$work" && scripts/adr-index 2>&1)" +out="$(cd "$work" && PRE_COMMIT=1 scripts/adr-index 2>&1)" status=$? if (( status != 0 )) && [[ ! -e "$work/$index" ]]; then pass diff --git a/scripts/tests/attribute-commit-test b/scripts/tests/attribute-commit-test index b3d9d969..f004d263 100755 --- a/scripts/tests/attribute-commit-test +++ b/scripts/tests/attribute-commit-test @@ -78,7 +78,21 @@ out="$(rewrite "feat: add a thing A body. Co-Authored-By: Claude Opus 5 ")" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5" ]]; then + pass +else + fail "the rewritten message parses as: $(trailers "$out")" +fi + +# The fallback spells the display name as an ID, so --check accepts what it +# wrote rather than refusing an agent commit made without the hook. +fixture "a display name in the agent trailer is spelled as an ID" +out="$(rewrite "feat: add a thing + +A body. + +Co-Authored-By: Claude Opus 5.5 (1M context) ")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5-5" ]]; then pass else fail "the rewritten message parses as: $(trailers "$out")" @@ -105,7 +119,7 @@ A body. Co-Authored-By: Claude Opus 5 Co-Authored-By: A Human ")" -if [[ "$(trailers "$out")" == $'Generated-By: Claude Opus 5\nCo-Authored-By: A Human ' ]]; then +if [[ "$(trailers "$out")" == $'Generated-By: claude-opus-5\nCo-Authored-By: A Human ' ]]; then pass else fail "the pair parses as: $(trailers "$out")" @@ -148,13 +162,15 @@ else fail "the message parses as: $(trailers "$out")" fi -fixture "a rewritten Co-Authored-By is kept over the session's model" +# The display name Claude Code writes is the same fact as the ID, in a form +# --check refuses, so the known ID takes its place. +fixture "the session's model replaces an agent Co-Authored-By" out="$(rewrite "feat: add a thing A body. Co-Authored-By: Claude Opus 5 " claude-opus-5-5)" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5-5" ]]; then pass else fail "the message parses as: $(trailers "$out")" @@ -373,7 +389,7 @@ else fail "the message parses as: $(trailers "$out")" fi -fixture "a rewritten Co-Authored-By is kept over an entry" +fixture "an entry's model replaces an agent Co-Authored-By" entry sess-1 glm-5.1 "$(commit_cmd)" out="$(claude_rewrite "feat: add a thing @@ -381,12 +397,77 @@ A body. Co-Authored-By: Claude Opus 5 " "$(commit_cmd)" \ CLAUDE_CODE_SESSION_ID=sess-1)" -if [[ "$(trailers "$out")" == "Generated-By: Claude Opus 5" ]]; then +if [[ "$(trailers "$out")" == "Generated-By: glm-5.1" ]]; then pass else fail "the message parses as: $(trailers "$out")" fi +fixture "a context-window suffix is dropped from the model" +out="$(rewrite "feat: add a thing + +A body." "claude-opus-5[1m]")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-5" ]]; then + pass +else + fail "the message parses as: $(trailers "$out")" +fi + +# --check at commit-msg: prints nothing and exits 0 for a model ID, refuses +# anything else with the line to write. +verify() { + printf '%s\n' "$1" > "$work/COMMIT_EDITMSG" + (cd "$work" && "$script" --check "$work/COMMIT_EDITMSG" 2>&1) +} + +fixture "--check accepts a model ID" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5-5')" +status=$? +out2="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: gpt-5.1-codex')" +status2=$? +if (( status == 0 && status2 == 0 )) && [[ -z "$out$out2" ]]; then + pass +else + fail "a model ID was refused (exit $status, $status2): $out $out2" +fi + +fixture "--check refuses a display name" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: Claude Opus 5.5 (1M context)')" +status=$? +if (( status != 0 )) && grep -q "is not a model ID" <<< "$out"; then + pass +else + fail "a display name passed, exit $status: $out" +fi + +fixture "--check refuses a context-window suffix" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5[1m]')" +status=$? +if (( status != 0 )); then + pass +else + fail "a [1m] suffix passed: $out" +fi + +fixture "--check names the line a missing trailer needs" +out="$(verify $'feat: add a thing\n\nA body.')" +status=$? +if (( status != 0 )) && grep -q "Generated-By: " <<< "$out"; then + pass +else + fail "a missing trailer was not refused with the fix, exit $status: $out" +fi + +fixture "--check passes a replayed commit" +mkdir -p "$work/.git/rebase-merge" +out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: Claude Opus 5')" +status=$? +if (( status == 0 )); then + pass +else + fail "a replayed commit's old trailer was refused: $out" +fi + # git calls this hook for every commit, including ones whose message is already # a trailer's worth of nothing. Rewriting an absent file must not fail the commit. fixture "a missing message file is not an error" diff --git a/scripts/tests/capabilities-test b/scripts/tests/capabilities-test index c387b681..6cd66cde 100755 --- a/scripts/tests/capabilities-test +++ b/scripts/tests/capabilities-test @@ -441,6 +441,58 @@ else fail "trivy scanned $(tr '\n' ' ' < "$work/scanned")rather than both lockfiles" fi +# --- a Go audit failing only on the local standard library says so ----------- + +# govulncheck reports the standard library of the Go that runs it, and CI runs +# stable, so stdlib-only findings fixed in a newer Go are named as such. One +# finding in a module is the code's own, and gets no such line. +govulncheck_stub() { + stub govulncheck <&1 ' and not as '#N: title'" +into="$(attempt "Merge feature/x into main")" +into_status=$? +numbered="$(attempt "Merge #12: title")" +numbered_status=$? +if (( into_status == 0 && numbered_status != 0 )); then + pass +else + fail "wanted 'into' accepted and '#N:' refused, got $into_status and $numbered_status: $into $numbered" +fi + # body-leading-blank is a warning in config-conventional and an error here. The # rule name is asserted rather than just the exit status, since a malformed # message fails for several reasons and only one of them is this rule. diff --git a/scripts/tests/payload-parity-test b/scripts/tests/payload-parity-test index 0f7f89f4..a084a2b8 100755 --- a/scripts/tests/payload-parity-test +++ b/scripts/tests/payload-parity-test @@ -121,6 +121,37 @@ write ".github/workflows/ci.yml" changed audit assert_fails ".github/workflows/ci.yml differs" +# The direction is settled by which copy changed since HEAD, so these cases +# commit the agreeing trees first. The printed command, run verbatim, is the +# fix; where both copies changed it names none rather than guess. +commit_fixture() { + stage + git -C "$work" commit -q -m "chore: agreeing trees" +} + +parity_fixture "an edit to one copy names the command that mirrors it" +commit_fixture +write ".github/workflows/ci.yml" changed +audit +fix="$(sed -n 's/.*; run: //p' "$work/.audit-output")" +if [[ "$fix" == "mkdir -p $payload/workflows && cp .github/workflows/ci.yml $payload/workflows/ci.yml && git add"* ]] \ + && (cd "$work" && eval "$fix") && run_parity && (( parity_status == 0 )); then + pass +else + fail "wanted a root-to-payload command that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" +fi + +parity_fixture "an edit to both copies names no direction" +commit_fixture +write ".github/workflows/ci.yml" one +write "$payload/workflows/ci.yml" two +audit +if (( parity_status != 0 )) && ! grep -q '; run:' "$work/.audit-output"; then + pass +else + fail "wanted a FAIL with no command, got: $(cat "$work/.audit-output")" +fi + parity_fixture "a root file absent from the payload fails" write .github/workflows/release.yml audit diff --git a/scripts/tests/precommit-hooks-test b/scripts/tests/precommit-hooks-test index bcf4ec86..f89c935d 100755 --- a/scripts/tests/precommit-hooks-test +++ b/scripts/tests/precommit-hooks-test @@ -147,4 +147,27 @@ repos: []' fi fi +# A machine-wide core.hooksPath makes `pre-commit install` refuse, so the fix +# doctor prints there must be one that works with the key set: run verbatim, +# it leaves nothing missing, and the global key is untouched. +if command -v pre-commit >/dev/null 2>&1; then + fixture "doctor's remedy under a global core.hooksPath installs every hook" 'default_install_hook_types: [pre-commit, commit-msg] +repos: []' + printf '[core]\n\thooksPath = %s\n' "$work/global-hooks" > "$work/global-config" + remedy="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" scripts/doctor 2>&1 \ + | sed -n 's/.*so run: \(.*\), leaving init.templateDir.*/\1/p')" + if [[ -z "$remedy" ]] || [[ "$remedy" == *"pre-commit install"* ]]; then + fail "wanted the init-templatedir remedy, got: '$remedy'" + else + (cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" eval "$remedy" > /dev/null 2>&1) + got="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" pre_commit_hooks_missing .pre-commit-config.yaml)" + global="$(GIT_CONFIG_GLOBAL="$work/global-config" git config --global core.hooksPath)" + if [[ -z "$got" && "$global" == "$work/global-hooks" ]]; then + pass + else + fail "after the remedy, missing '$got', global key '$global'" + fi + fi +fi + report diff --git a/scripts/tests/result-gate-test b/scripts/tests/result-gate-test index 007c9afd..f8227c47 100755 --- a/scripts/tests/result-gate-test +++ b/scripts/tests/result-gate-test @@ -67,6 +67,16 @@ bare_package "$work" out="$(cd "$work" && scripts/ci 2>&1)" assert_unavailable $? 'lint +unavailable +node' "$out" +# The last line is what `| tail -1` keeps, so it alone must carry the exit +# status and count unavailable beside FAIL. +current="ci ends with a verdict naming its status and the unavailable lines" +want_unavailable="$(grep -cE '^[A-Za-z0-9_-]+ +unavailable( |$)' <<< "$out")" +if [[ "$(tail -n 1 <<< "$out")" =~ ^scripts/ci\ exited\ 1:\ 0\ FAIL,\ ${want_unavailable}\ unavailable,\ [0-9]+\ not-applicable,\ [0-9]+\ pass$ ]]; then + pass +else + fail "wanted a closing verdict with $want_unavailable unavailable, got: $(tail -n 1 <<< "$out")" +fi + fixture "fix fails on a language with no formatter" bare_package "$work" out="$(cd "$work" && scripts/fix 2>&1)" diff --git a/scripts/tests/summarize-test b/scripts/tests/summarize-test index 516261e1..49dd6687 100755 --- a/scripts/tests/summarize-test +++ b/scripts/tests/summarize-test @@ -4,7 +4,8 @@ set -uo pipefail # What summarize keeps and what it drops. The cases run a stub command rather # than a real check, so they assert the filter's contract -- the layout # libs/result.sh documents -- and not the current output of any one check. They -# also hold that it exits with the command's own status, and that a failure +# also hold that it exits with the command's own status, that its last line is +# a verdict carrying that status and a count per state, and that a failure # outside the table leaves the whole run in tmp/summarize-failure.log. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" @@ -90,6 +91,16 @@ else fail "wanted the dropped output in tmp/summarize-failure.log" fi +# The last line is what `| tail -1` keeps, so it alone must carry the exit +# status and count unavailable beside FAIL. +current="the last line is the verdict, after any notice" +if [[ "$(tail -n 1 <<< "$out2")" == "bash exited 1: 1 FAIL, 1 unavailable, 1 not-applicable, 1 pass" ]] \ + && [[ "$(tail -n 1 <<< "$out")" == "bash exited 3: 0 FAIL, 0 unavailable, 0 not-applicable, 1 pass" ]]; then + pass +else + fail "wanted a closing verdict line, got: $(tail -n 1 <<< "$out2") / $(tail -n 1 <<< "$out")" +fi + current="a FAIL in the table needs no such notice" if ! grep -q 'outside the' <<< "$out2"; then pass From 18b1b0610a913cd498979d269ff180811e1602a7 Mon Sep 17 00:00:00 2001 From: neal Date: Wed, 18 Nov 2026 16:49:51 -0500 Subject: [PATCH 2/2] fix(scripts): close the review's gaps in attribution, parity and doctor attribute-commit --check refused a merge, revert or fixup commit with no trailer, which commitlint's trailer-exists skips; a missing trailer is now left to commitlint, and --check refuses only a malformed value. Its ID shape admits other vendors' IDs (qwen3-coder:30b, ...@20250805, a provider path, uppercase) and still refuses spaces and a [suffix]. The display-name fallback trims a hyphen left at either end by stray spacing. payload-parity mirrored a staged deletion with a cp from the deleted copy; it now prints the git rm that mirrors it. doctor's hooksPath remedy quotes the shim paths, so it runs from a clone whose path holds a space. The verdict line is formatted once, by result_verdict in libs/result.sh, which summarize now calls for the command it ran. The retrofit hook probe accepts any Generated-By once the Co-Authored-By is gone, since a session with a known model writes the model rather than the slug. Generated-By: claude-opus-5-5 --- CLAUDE.md | 4 +- .../docs/github_repository_structure.md | 2 +- .../src/base-repo/scripts/attribute-commit | 39 +++++++++---------- .../src/base-repo/scripts/doctor | 2 +- .../src/base-repo/scripts/libs/result.sh | 26 +++++++++---- .../src/base-repo/scripts/payload-parity | 7 +++- .../src/base-repo/scripts/summarize | 16 +++++--- .../scripts/tests/attribute-commit-test | 30 +++++++++++--- .../scripts/tests/payload-parity-test | 14 +++++++ .../scripts/tests/precommit-hooks-test | 6 ++- apps/repo-builder/src/scripts/retrofit.py | 5 ++- scripts/CLAUDE.md | 2 +- scripts/attribute-commit | 39 +++++++++---------- scripts/doctor | 2 +- scripts/libs/result.sh | 26 +++++++++---- scripts/payload-parity | 7 +++- scripts/summarize | 16 +++++--- scripts/tests/attribute-commit-test | 30 +++++++++++--- scripts/tests/payload-parity-test | 14 +++++++ scripts/tests/precommit-hooks-test | 6 ++- 20 files changed, 199 insertions(+), 94 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6b678517..15ab1f71 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,7 +40,7 @@ Use these instead of per-language tools; each detects the languages present and - `scripts/integration` — run every `tests/integration/` tier, at any scope. Kept out of the gate, since a tier may need a database, container, or network the gate cannot assume - `scripts/package [unit]` — deliver what the unit ships: an executable per declared target into its `dist/`, emptied first so no stale binary reaches a release, or its `deploy/quadlet/` files validated. Not part of the gate - `scripts/structure` — audit file placement against Layout below; run by `scripts/check` and by pre-commit on every commit -- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather than repairs, so a Dependabot bump merged into the root fails until it is mirrored; where exactly one copy changed since `HEAD`, a finding ends with the `cp` command that mirrors it. The shellcheck hook skips the payload's `scripts/` on the strength of it +- `scripts/payload-parity` — refuse a divergence between `.github/` or `scripts/` and the payload's copy, `scripts/CLAUDE.md` excepted; run by `scripts/check` and by pre-commit. It reports rather than repairs, so a Dependabot bump merged into the root fails until it is mirrored; where exactly one copy changed since `HEAD`, a finding ends with the command that mirrors it: a `cp`, or a `git rm` for a deletion. The shellcheck hook skips the payload's `scripts/` on the strength of it Every check runs for every language present. Results distinguish `pass`, `not-applicable`, `unavailable`, and `FAIL`, so an intentional no-op cannot look like a runner that executed. See `scripts/CLAUDE.md` before adding a language or a check. @@ -57,7 +57,7 @@ The only non-shell code here is the Python under `apps/repo-builder/`, declared - These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files and dotfiles included. Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`. - Work reaches `main` through a pull request under `.github/PULL_REQUEST_TEMPLATE.md`; a ruleset enforces it (Repository settings below). - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why. -- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the exact command running agree, so parallel agents in one session cannot cross-attribute; and it replaces a stray `Co-Authored-By: ` with that ID, or without one rewrites it as a `Generated-By` spelling the display name as an ID, since a tool is not a co-author; a human's `Co-Authored-By:` stays. It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. There `attribute-commit --check` refuses a value that is not a model ID (lowercase, no spaces, no `[1m]`-style suffix), since hand-typed display names made the record unsearchable; replayed commits pass. +- Every commit carries a `Generated-By: ` trailer, required by `trailer-exists` in `.commitlintrc.yaml`. `scripts/attribute-commit` writes it at `prepare-commit-msg`: it inserts `Generated-By: ` from `CLAUDE_COMMIT_MODEL`, which the operator's user-level `commit-model` hook exports into an agent's git commands, or else from the entries that hook writes under `${XDG_CACHE_HOME:-~/.cache}/claude-commit-model//`, one per command, taking the model only when the entries for the exact command running agree, so parallel agents in one session cannot cross-attribute; and it replaces a stray `Co-Authored-By: ` with that ID, or without one rewrites it as a `Generated-By` spelling the display name as an ID, since a tool is not a co-author; a human's `Co-Authored-By:` stays. It inserts nothing without either source or during a rebase or cherry-pick, so those commits and any written by hand add their own line or are refused at `commit-msg`. There `attribute-commit --check` refuses a value that is not shaped as a model ID (one word, no `[1m]`-style suffix), since hand-typed display names made the record unsearchable; replayed commits pass. - GitHub's generated merge subjects are on commitlint's default ignore list and need no CI check. A hand-written merge subject takes one of those shapes, `Merge into `; `.commitlintrc.yaml` says why it holds no `ignores`. - A changed `CHANGELOG.md` is structurally checked at `pre-push`, and in CI over the pull-request range; that validates an entry, not whether one was owed. This repository keeps none: `CHANGELOG.md` is an addon at `apps/github-repository-template/src/repository-addons/CHANGELOG.md`, the only changelog the check fires on here. - The commit type signals a changelog entry without deciding it: `feat`, `fix`, and anything with `!` or a `BREAKING CHANGE:` footer usually owe one; `docs`, `style`, `test`, `ci`, and `chore` usually do not. Notability is judged per pull request. diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index fe9e5104..ebdd7f21 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -95,7 +95,7 @@ The specific operating parameters for the AI agent. `scripts/structure`: Audits where files sit against the Layout rules it holds as code — the root folder and file allowlists, the `apps/` unit-and-domain shape, the closed folder vocabulary under a domain, `src/` placement, and the Markdown-only rule for `docs/`. Called by `scripts/check` and by pre-commit on every commit. It reads the contents of exactly one file, a unit's `.unit.json`, whose whole purpose is to state what a tree cannot show; the three rules that turn on what any other file contains are reported `not-applicable` rather than guessed. Reading a declaration needs `jq`, and its absence is reported `unavailable` rather than passed over. -`scripts/payload-parity`: Refuses a divergence between a repository's own `.github/` or `scripts/` and the copy a template payload ships to generated repositories, reading both which paths exist and what each one holds from the Git index, since it runs at pre-commit and the index is the tree being committed. `scripts/CLAUDE.md` is the one root-only path, since it documents this repository's scripts. The shellcheck hook skips the payload's `scripts/` because this check holds it identical to the root's. `.github/dependabot.yml` is the one named content exception, and it differs twice. Its language entries are derived per repository from the manifests that repository tracks, so the payload copy must not carry an entry for a manifest it does not ship while the root copy carries the entry its own `pyproject.toml` earns. And where a repository tracks a `.pre-commit-config.yaml` under a payload, its `pre-commit` entry names that second directory so a hook bump reaches both copies; a repository with no payload has no such directory to name. Both differences are by design rather than by drift. Presence is still checked, so neither copy may go missing; a payload file the root deliberately dropped is excused only where `generation.features` in `.repo-template.json` records the omission, which needs `jq` and is reported `unavailable` without it; a divergence the record cannot excuse is still named on a host without `jq`. Where exactly one copy of a pair changed since `HEAD`, its finding ends with the `cp` and `git add` that mirror it; where both or neither did, it names no direction. Reports `not-applicable` in a repository with no payload, which is every repository generated from one. Called by `scripts/check` and by pre-commit on every commit. +`scripts/payload-parity`: Refuses a divergence between a repository's own `.github/` or `scripts/` and the copy a template payload ships to generated repositories, reading both which paths exist and what each one holds from the Git index, since it runs at pre-commit and the index is the tree being committed. `scripts/CLAUDE.md` is the one root-only path, since it documents this repository's scripts. The shellcheck hook skips the payload's `scripts/` because this check holds it identical to the root's. `.github/dependabot.yml` is the one named content exception, and it differs twice. Its language entries are derived per repository from the manifests that repository tracks, so the payload copy must not carry an entry for a manifest it does not ship while the root copy carries the entry its own `pyproject.toml` earns. And where a repository tracks a `.pre-commit-config.yaml` under a payload, its `pre-commit` entry names that second directory so a hook bump reaches both copies; a repository with no payload has no such directory to name. Both differences are by design rather than by drift. Presence is still checked, so neither copy may go missing; a payload file the root deliberately dropped is excused only where `generation.features` in `.repo-template.json` records the omission, which needs `jq` and is reported `unavailable` without it; a divergence the record cannot excuse is still named on a host without `jq`. Where exactly one copy of a pair changed since `HEAD`, its finding ends with the `cp` and `git add` that mirror it, or the `git rm` that mirrors a deletion; where both or neither did, it names no direction. Reports `not-applicable` in a repository with no payload, which is every repository generated from one. Called by `scripts/check` and by pre-commit on every commit. `.structure-allow`: Convention (not a shipped file) for the permission the Layout rules refer to — one path per line to allow a named exception, a trailing `/` to stop the audit descending into a tracked fixture tree, save for one lookup that keeps a prefix over a domain's `src/` from failing the domain it defines. Absent until a repository needs one. diff --git a/apps/github-repository-template/src/base-repo/scripts/attribute-commit b/apps/github-repository-template/src/base-repo/scripts/attribute-commit index b374e3ba..b5a3f1e9 100755 --- a/apps/github-repository-template/src/base-repo/scripts/attribute-commit +++ b/apps/github-repository-template/src/base-repo/scripts/attribute-commit @@ -2,8 +2,8 @@ set -euo pipefail # Write the commit's Generated-By trailer at prepare-commit-msg, before -# commitlint reads the message, and with --check at commit-msg refuse a -# trailer that is missing or names no model ID. +# commitlint reads the message, and with --check at commit-msg refuse one +# that names no model ID. # # A tool is not a co-author, but the model is worth keeping: it is the only # per-commit record of what produced the change. The model comes from outside @@ -152,29 +152,25 @@ session_model() { matching_model "${cmdline%x}" } -# --check, at commit-msg: the trailer must name a model ID. The record is only -# worth keeping if it can be searched, and hand-typed trailers drifted into -# display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 (1M context)` -# -- beside the IDs, a dozen spellings for a handful of models. The shape is -# any vendor's ID, lowercase with no spaces, not a list of Claude models, -# which would refuse the next one. A missing trailer is refused here too, with -# the line to add, since commitlint's `trailer-exists` names only the rule. +# --check, at commit-msg: a Generated-By trailer must name a model ID. The +# record is only worth keeping if it can be searched, and hand-typed trailers +# drifted into display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 +# (1M context)` -- beside the IDs, a dozen spellings for a handful of models. +# What is checked is the shape of any vendor's ID, one word with no [suffix], +# not a list of Claude models, which would refuse the next one; `qwen3-coder:30b` +# and `...@20250805` pass, and nothing asks whether the model exists. A missing +# trailer is left to commitlint's `trailer-exists`, which skips the merge, +# revert, and fixup subjects on its default ignore list where this could not. # Replayed commits are passed: they keep the trailer they were written with. if [[ -n "$check" ]]; then replaying && exit 0 - values="$(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p')" - if [[ -z "$values" ]]; then - echo "No Generated-By trailer. End the message with a paragraph holding" >&2 - echo "'Generated-By: ', e.g. 'Generated-By: claude-opus-5-5'." >&2 - exit 1 - fi while IFS= read -r value; do - if [[ ! "$value" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then - echo "Generated-By: '$value' is not a model ID. Write the ID, lowercase" >&2 - echo "with no spaces or [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 + if [[ ! "$value" =~ ^[A-Za-z0-9][A-Za-z0-9._:@/-]*$ ]]; then + echo "Generated-By: '$value' is not a model ID. Write the ID, one word" >&2 + echo "with no [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 exit 1 fi - done <<< "$values" + done < <(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p') exit 0 fi @@ -187,8 +183,8 @@ model="${model%%\[*}" # ID is known it replaces that line, being the same fact in a form that can be # searched; otherwise the line becomes a Generated-By naming what it named, # spelled as an ID so --check accepts it: lowercased, a parenthetical such as -# `(1M context)` dropped, and spaces and dots made hyphens, which turns -# `Claude Opus 5.5` into `claude-opus-5-5`. +# `(1M context)` dropped, spaces and dots made hyphens, and a hyphen left at +# either end trimmed, which turns `Claude Opus 5.5` into `claude-opus-5-5`. co_author='^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$' if [[ -n "$model" ]] && ! replaying; then sed -i -E "/$co_author/d" "$msg_file" @@ -197,6 +193,7 @@ else s/$co_author/\1/ s/[[:space:]]*\([^)]*\)//g s/[[:space:].]+/-/g + s/^-+|-+$//g y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/ s/^/Generated-By: / }" "$msg_file" diff --git a/apps/github-repository-template/src/base-repo/scripts/doctor b/apps/github-repository-template/src/base-repo/scripts/doctor index 4adcc6b1..701f17a8 100755 --- a/apps/github-repository-template/src/base-repo/scripts/doctor +++ b/apps/github-repository-template/src/base-repo/scripts/doctor @@ -96,7 +96,7 @@ if [[ -s .pre-commit-config.yaml ]]; then if [[ -n "$hooks_path" ]]; then shims="$(git rev-parse --path-format=absolute --git-common-dir)/pre-commit-shims" type_flags="$(pre_commit_hook_types .pre-commit-config.yaml | sed 's/^/-t /' | paste -sd ' ' -)" - record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $shims && git config --local core.hooksPath $shims/hooks, leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" + record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $(printf %q "$shims") && git config --local core.hooksPath $(printf %q "$shims/hooks"), leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" else while IFS= read -r hook_type; do record "no $hook_type hook in this clone; run: pre-commit install" diff --git a/apps/github-repository-template/src/base-repo/scripts/libs/result.sh b/apps/github-repository-template/src/base-repo/scripts/libs/result.sh index 7e008c1f..94803cd6 100644 --- a/apps/github-repository-template/src/base-repo/scripts/libs/result.sh +++ b/apps/github-repository-template/src/base-repo/scripts/libs/result.sh @@ -82,8 +82,20 @@ tally() { return "$result_failed" } -# The verdict, printed as the process exits: the command, its exit status, and -# a count per state, in the line scripts/summarize ends with. A reader who keeps +# The verdict line: result_verdict , the command as invoked, +# its exit status, and a count per state from result_counts, would-run left out +# at zero. scripts/summarize fills result_counts from the table it parsed and +# ends with this same line. +result_verdict() { + local state line="" + for state in FAIL unavailable not-applicable pass would-run; do + [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue + line+=" ${result_counts[$state]} $state," + done + echo "$1 exited $2:${line%,}" +} + +# The verdict, printed as the process exits. A reader who keeps # only the end of the output -- `| tail`, which also hides the exit status # behind its own -- still gets both, and unavailable is counted beside FAIL # rather than left for a FAIL-only grep to miss. An EXIT trap rather than a @@ -97,13 +109,11 @@ tally() { # script that sets its own afterwards replaces this one, and calls # result_exit_verdict from it to keep the line. result_exit_verdict() { - local status=$? state line="" total=0 - for state in FAIL unavailable not-applicable pass would-run; do - total=$(( total + result_counts[$state] )) - [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue - line+=" ${result_counts[$state]} $state," + local status=$? count total=0 + for count in "${result_counts[@]}"; do + total=$(( total + count )) done - (( total > 0 )) && echo "$0 exited $status:${line%,}" + (( total > 0 )) && result_verdict "$0" "$status" return "$status" } [[ -n "$(trap -p EXIT)" ]] || trap result_exit_verdict EXIT diff --git a/apps/github-repository-template/src/base-repo/scripts/payload-parity b/apps/github-repository-template/src/base-repo/scripts/payload-parity index 0b68d26d..c0820aa5 100755 --- a/apps/github-repository-template/src/base-repo/scripts/payload-parity +++ b/apps/github-repository-template/src/base-repo/scripts/payload-parity @@ -92,7 +92,8 @@ staged_edit() { # The command that mirrors a diverged pair, where the staged edit settles its # direction: exactly one copy changed since HEAD. Otherwise nothing, since a # merged root bump changes neither copy and an edit to both changes both, and -# guessing a direction there overwrites the newer copy. +# guessing a direction there overwrites the newer copy. A staged deletion is +# such an edit, and is mirrored by removing the other copy. mirror_command() { local root_copy="$1" payload_copy="$payload_root/$1" from to if staged_edit "$root_copy" && ! staged_edit "$payload_copy"; then @@ -102,6 +103,10 @@ mirror_command() { else return 0 fi + if ! git cat-file -e ":$from" 2> /dev/null; then + printf '; run: git rm %q' "$to" + return 0 + fi printf '; run: mkdir -p %q && cp %q %q && git add %q %q' "${to%/*}" "$from" "$to" "$from" "$to" } diff --git a/apps/github-repository-template/src/base-repo/scripts/summarize b/apps/github-repository-template/src/base-repo/scripts/summarize index 25f0d163..8bd927ff 100755 --- a/apps/github-repository-template/src/base-repo/scripts/summarize +++ b/apps/github-repository-template/src/base-repo/scripts/summarize @@ -23,6 +23,13 @@ set -uo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +# For result_verdict alone. The verdict is the command's, not this script's, +# so the EXIT trap sourcing installs is dropped. +# shellcheck source-path=SCRIPTDIR +# shellcheck source=libs/result.sh +source "$repo_root/scripts/libs/result.sh" +trap - EXIT + if (( $# == 0 )); then echo "usage: scripts/summarize [args...]" >&2 echo " e.g. scripts/summarize scripts/ci" >&2 @@ -83,12 +90,9 @@ fi # A reader who keeps only the end of the output -- `| tail`, which also hides # the exit status behind its own -- still gets both, and an unavailable check # is counted beside FAIL rather than left for a FAIL-only grep to miss. -verdict="$1 exited $status:" -for state in FAIL unavailable not-applicable pass would-run; do - count="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" - [[ "$state" == would-run && "$count" == 0 ]] && continue - verdict+=" $count $state," +for state in "${!result_counts[@]}"; do + result_counts[$state]="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" done -echo "${verdict%,}" +result_verdict "$1" "$status" exit "$status" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test b/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test index f004d263..9a785fbc 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/attribute-commit-test @@ -413,6 +413,19 @@ else fail "the message parses as: $(trailers "$out")" fi +# Spacing around the name must not leave a hyphen at either end of the ID. +fixture "extra spaces around the display name leave no end hyphen" +out="$(rewrite "feat: add a thing + +A body. + +Co-Authored-By: Claude Opus 4.6 (1M context) ")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-4-6" ]]; then + pass +else + fail "the rewritten message parses as: $(trailers "$out")" +fi + # --check at commit-msg: prints nothing and exits 0 for a model ID, refuses # anything else with the line to write. verify() { @@ -425,10 +438,13 @@ out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5-5')" status=$? out2="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: gpt-5.1-codex')" status2=$? -if (( status == 0 && status2 == 0 )) && [[ -z "$out$out2" ]]; then +# Other vendors' IDs carry a tag, a version date, or a provider path. +out3="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: qwen3-coder:30b\nGenerated-By: claude-opus-4-1@20250805\nGenerated-By: meta/Llama-3.1-8B')" +status3=$? +if (( status == 0 && status2 == 0 && status3 == 0 )) && [[ -z "$out$out2$out3" ]]; then pass else - fail "a model ID was refused (exit $status, $status2): $out $out2" + fail "a model ID was refused (exit $status, $status2, $status3): $out $out2 $out3" fi fixture "--check refuses a display name" @@ -449,13 +465,15 @@ else fail "a [1m] suffix passed: $out" fi -fixture "--check names the line a missing trailer needs" -out="$(verify $'feat: add a thing\n\nA body.')" +# commitlint's trailer-exists refuses a missing trailer and skips the merge, +# revert, and fixup subjects on its ignore list; refusing here would undo that. +fixture "--check leaves a missing trailer to commitlint" +out="$(verify $'Merge branch \'main\' into feature')" status=$? -if (( status != 0 )) && grep -q "Generated-By: " <<< "$out"; then +if (( status == 0 )) && [[ -z "$out" ]]; then pass else - fail "a missing trailer was not refused with the fix, exit $status: $out" + fail "a merge with no trailer was refused, exit $status: $out" fi fixture "--check passes a replayed commit" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test b/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test index a084a2b8..fb1384aa 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/payload-parity-test @@ -141,6 +141,20 @@ else fail "wanted a root-to-payload command that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" fi +# A staged deletion counts as the edit, and its mirror removes the other copy; +# a cp from the deleted copy would fail. +parity_fixture "a deletion of one copy names the git rm that mirrors it" +commit_fixture +rm "$work/$payload/workflows/ci.yml" +audit +fix="$(sed -n 's/.*; run: //p' "$work/.audit-output")" +if [[ "$fix" == "git rm .github/workflows/ci.yml" ]] \ + && (cd "$work" && eval "$fix" > /dev/null) && run_parity && (( parity_status == 0 )); then + pass +else + fail "wanted a git rm that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" +fi + parity_fixture "an edit to both copies names no direction" commit_fixture write ".github/workflows/ci.yml" one diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test b/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test index f89c935d..12feb4e2 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/precommit-hooks-test @@ -149,10 +149,14 @@ fi # A machine-wide core.hooksPath makes `pre-commit install` refuse, so the fix # doctor prints there must be one that works with the key set: run verbatim, -# it leaves nothing missing, and the global key is untouched. +# it leaves nothing missing, and the global key is untouched. The clone's path +# holds a space, so the remedy must quote it. if command -v pre-commit >/dev/null 2>&1; then fixture "doctor's remedy under a global core.hooksPath installs every hook" 'default_install_hook_types: [pre-commit, commit-msg] repos: []' + mv "$work" "$work with space" + work="$work with space" + PATH="$work/bin:$harness_path" printf '[core]\n\thooksPath = %s\n' "$work/global-hooks" > "$work/global-config" remedy="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" scripts/doctor 2>&1 \ | sed -n 's/.*so run: \(.*\), leaving init.templateDir.*/\1/p')" diff --git a/apps/repo-builder/src/scripts/retrofit.py b/apps/repo-builder/src/scripts/retrofit.py index 3a65ba8e..bf887c00 100755 --- a/apps/repo-builder/src/scripts/retrofit.py +++ b/apps/repo-builder/src/scripts/retrofit.py @@ -911,7 +911,6 @@ def autofix(arguments: argparse.Namespace) -> dict[str, object]: SHIM_MARKER = "File generated by pre-commit" HOOK_TEST_FILE = "docs/retrofit-hook-test.md" AGENT_TRAILER = "Co-Authored-By: Retrofit Hook Test " -REWRITTEN_TRAILER = "Generated-By: retrofit-hook-test" MESSAGE_HOOK_TYPES = ("prepare-commit-msg", "commit-msg") @@ -1183,9 +1182,11 @@ def hook_outcomes(tree: Path, default_branch: str) -> dict[str, bool]: run_git(tree, "add", "--", HOOK_TEST_FILE) message = attempt_commit(tree, f"docs: prove the hooks run\n\n{AGENT_TRAILER}\n") + # The rewrite names the session's model where one is known and spells the + # display name as an ID otherwise, so either Generated-By proves it ran. trailer_rewritten = ( message is not None - and REWRITTEN_TRAILER in message + and "\nGenerated-By: " in message and AGENT_TRAILER not in message ) landed = message is not None diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md index eeadcd73..1f78747d 100644 --- a/scripts/CLAUDE.md +++ b/scripts/CLAUDE.md @@ -20,7 +20,7 @@ Each script's header comment says what it does and why it is shaped that way, an - **`libs/detect.sh` owns every language decision.** Commands name a capability, never an adapter; `DETECT_LANGUAGES` and `DETECT_PRUNE_DIRS` are the lists. - **The toolchains are the machine's, not a pinned set.** `check` runs whatever compiler, linter, and formatter the machine has; `.github/actions/setup-toolchains` installs each fresh on the runner (`go-version: stable`, `node-version: lts/*`, `swift-version: latest`, `rustup component add` over a rustup the host must already have). pre-commit pins what it owns by `rev`, so a check that passes locally and fails in CI is a version difference before it is a flaky runner, and the reverse holds for the Go audit, which reads the local Go's standard library and names the release that clears a failure found only there. rustup is the one prerequisite neither installs; the setup action and `security.yml`'s cargo-audit step fail with one line naming the host. Pin a toolchain in the repository that has the language: a pin shipped from the payload obliges every generated repository to bump a file for a language it may not have, and Dependabot has no ecosystem for any of them. - **A check that did not run is not a check that passed.** `unavailable` fails the run whenever the check was expected. -- **`libs/result.sh`'s printed layout is an interface**, parsed by `summarize`; `tally` is a command's exit status, and the verdict its EXIT trap prints (` exited : `) is the last line, in the shape `summarize` ends with. Print results in the shell that exits, since a subshell's counts never reach the trap, and a script setting its own EXIT trap calls `result_exit_verdict` from it. +- **`libs/result.sh`'s printed layout is an interface**, parsed by `summarize`; `tally` is a command's exit status, and the verdict its EXIT trap prints through `result_verdict` (` exited : `) is the last line, and `summarize` ends with the same line for the command it ran. Print results in the shell that exits, since a subshell's counts never reach the trap, and a script setting its own EXIT trap calls `result_exit_verdict` from it. - **A check owns no stdin.** `script-tests` closes fd 0 for each suite and `check` for `structure`, and the dispatch closes it for every capability but `run`, so a stdin-draining tool cannot hang the gate. The `*_each` helpers take their list on fd 3, and pipes end in a variable, never a reader that exits early, since `pipefail` turns SIGPIPE into 141, read as absent. - **An adapter is honest about what it did.** Capture the tool's exit status, not only its output. No function stands in for an absent one: the probe reads `absent` off the function table and the dispatch reports `unavailable`. A runner that exits non-zero without a real failure is translated, and `libs/detect.sh`'s header lists the four. - **`libs/*.sh` and `harness.sh` are sourced, never executed**: no shebang, no executable bit, `.sh`. Every other script is extensionless and executable; pre-commit reads a shebang only on one. diff --git a/scripts/attribute-commit b/scripts/attribute-commit index b374e3ba..b5a3f1e9 100755 --- a/scripts/attribute-commit +++ b/scripts/attribute-commit @@ -2,8 +2,8 @@ set -euo pipefail # Write the commit's Generated-By trailer at prepare-commit-msg, before -# commitlint reads the message, and with --check at commit-msg refuse a -# trailer that is missing or names no model ID. +# commitlint reads the message, and with --check at commit-msg refuse one +# that names no model ID. # # A tool is not a co-author, but the model is worth keeping: it is the only # per-commit record of what produced the change. The model comes from outside @@ -152,29 +152,25 @@ session_model() { matching_model "${cmdline%x}" } -# --check, at commit-msg: the trailer must name a model ID. The record is only -# worth keeping if it can be searched, and hand-typed trailers drifted into -# display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 (1M context)` -# -- beside the IDs, a dozen spellings for a handful of models. The shape is -# any vendor's ID, lowercase with no spaces, not a list of Claude models, -# which would refuse the next one. A missing trailer is refused here too, with -# the line to add, since commitlint's `trailer-exists` names only the rule. +# --check, at commit-msg: a Generated-By trailer must name a model ID. The +# record is only worth keeping if it can be searched, and hand-typed trailers +# drifted into display names -- `Claude Opus 5.5`, `Opus 5`, `Claude Opus 5.5 +# (1M context)` -- beside the IDs, a dozen spellings for a handful of models. +# What is checked is the shape of any vendor's ID, one word with no [suffix], +# not a list of Claude models, which would refuse the next one; `qwen3-coder:30b` +# and `...@20250805` pass, and nothing asks whether the model exists. A missing +# trailer is left to commitlint's `trailer-exists`, which skips the merge, +# revert, and fixup subjects on its default ignore list where this could not. # Replayed commits are passed: they keep the trailer they were written with. if [[ -n "$check" ]]; then replaying && exit 0 - values="$(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p')" - if [[ -z "$values" ]]; then - echo "No Generated-By trailer. End the message with a paragraph holding" >&2 - echo "'Generated-By: ', e.g. 'Generated-By: claude-opus-5-5'." >&2 - exit 1 - fi while IFS= read -r value; do - if [[ ! "$value" =~ ^[a-z0-9][a-z0-9._-]*$ ]]; then - echo "Generated-By: '$value' is not a model ID. Write the ID, lowercase" >&2 - echo "with no spaces or [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 + if [[ ! "$value" =~ ^[A-Za-z0-9][A-Za-z0-9._:@/-]*$ ]]; then + echo "Generated-By: '$value' is not a model ID. Write the ID, one word" >&2 + echo "with no [suffix], e.g. 'Generated-By: claude-opus-5-5'." >&2 exit 1 fi - done <<< "$values" + done < <(git interpret-trailers --parse "$msg_file" | sed -n 's/^Generated-By:[[:space:]]*//p') exit 0 fi @@ -187,8 +183,8 @@ model="${model%%\[*}" # ID is known it replaces that line, being the same fact in a form that can be # searched; otherwise the line becomes a Generated-By naming what it named, # spelled as an ID so --check accepts it: lowercased, a parenthetical such as -# `(1M context)` dropped, and spaces and dots made hyphens, which turns -# `Claude Opus 5.5` into `claude-opus-5-5`. +# `(1M context)` dropped, spaces and dots made hyphens, and a hyphen left at +# either end trimmed, which turns `Claude Opus 5.5` into `claude-opus-5-5`. co_author='^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*(.+)[[:space:]]+[[:space:]]*$' if [[ -n "$model" ]] && ! replaying; then sed -i -E "/$co_author/d" "$msg_file" @@ -197,6 +193,7 @@ else s/$co_author/\1/ s/[[:space:]]*\([^)]*\)//g s/[[:space:].]+/-/g + s/^-+|-+$//g y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/ s/^/Generated-By: / }" "$msg_file" diff --git a/scripts/doctor b/scripts/doctor index 4adcc6b1..701f17a8 100755 --- a/scripts/doctor +++ b/scripts/doctor @@ -96,7 +96,7 @@ if [[ -s .pre-commit-config.yaml ]]; then if [[ -n "$hooks_path" ]]; then shims="$(git rev-parse --path-format=absolute --git-common-dir)/pre-commit-shims" type_flags="$(pre_commit_hook_types .pre-commit-config.yaml | sed 's/^/-t /' | paste -sd ' ' -)" - record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $shims && git config --local core.hooksPath $shims/hooks, leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" + record "no $(paste -sd ',' - <<<"$uninstalled" | sed 's/,/, /g') hook in $hooks_path, where core.hooksPath points git; pre-commit install refuses while that key is set, so run: pre-commit init-templatedir $type_flags $(printf %q "$shims") && git config --local core.hooksPath $(printf %q "$shims/hooks"), leaving init.templateDir unset whatever its warning suggests (a hook in $hooks_path stops firing here unless linked in as $shims/hooks/.legacy)" else while IFS= read -r hook_type; do record "no $hook_type hook in this clone; run: pre-commit install" diff --git a/scripts/libs/result.sh b/scripts/libs/result.sh index 7e008c1f..94803cd6 100644 --- a/scripts/libs/result.sh +++ b/scripts/libs/result.sh @@ -82,8 +82,20 @@ tally() { return "$result_failed" } -# The verdict, printed as the process exits: the command, its exit status, and -# a count per state, in the line scripts/summarize ends with. A reader who keeps +# The verdict line: result_verdict , the command as invoked, +# its exit status, and a count per state from result_counts, would-run left out +# at zero. scripts/summarize fills result_counts from the table it parsed and +# ends with this same line. +result_verdict() { + local state line="" + for state in FAIL unavailable not-applicable pass would-run; do + [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue + line+=" ${result_counts[$state]} $state," + done + echo "$1 exited $2:${line%,}" +} + +# The verdict, printed as the process exits. A reader who keeps # only the end of the output -- `| tail`, which also hides the exit status # behind its own -- still gets both, and unavailable is counted beside FAIL # rather than left for a FAIL-only grep to miss. An EXIT trap rather than a @@ -97,13 +109,11 @@ tally() { # script that sets its own afterwards replaces this one, and calls # result_exit_verdict from it to keep the line. result_exit_verdict() { - local status=$? state line="" total=0 - for state in FAIL unavailable not-applicable pass would-run; do - total=$(( total + result_counts[$state] )) - [[ "$state" == would-run && "${result_counts[$state]}" == 0 ]] && continue - line+=" ${result_counts[$state]} $state," + local status=$? count total=0 + for count in "${result_counts[@]}"; do + total=$(( total + count )) done - (( total > 0 )) && echo "$0 exited $status:${line%,}" + (( total > 0 )) && result_verdict "$0" "$status" return "$status" } [[ -n "$(trap -p EXIT)" ]] || trap result_exit_verdict EXIT diff --git a/scripts/payload-parity b/scripts/payload-parity index 0b68d26d..c0820aa5 100755 --- a/scripts/payload-parity +++ b/scripts/payload-parity @@ -92,7 +92,8 @@ staged_edit() { # The command that mirrors a diverged pair, where the staged edit settles its # direction: exactly one copy changed since HEAD. Otherwise nothing, since a # merged root bump changes neither copy and an edit to both changes both, and -# guessing a direction there overwrites the newer copy. +# guessing a direction there overwrites the newer copy. A staged deletion is +# such an edit, and is mirrored by removing the other copy. mirror_command() { local root_copy="$1" payload_copy="$payload_root/$1" from to if staged_edit "$root_copy" && ! staged_edit "$payload_copy"; then @@ -102,6 +103,10 @@ mirror_command() { else return 0 fi + if ! git cat-file -e ":$from" 2> /dev/null; then + printf '; run: git rm %q' "$to" + return 0 + fi printf '; run: mkdir -p %q && cp %q %q && git add %q %q' "${to%/*}" "$from" "$to" "$from" "$to" } diff --git a/scripts/summarize b/scripts/summarize index 25f0d163..8bd927ff 100755 --- a/scripts/summarize +++ b/scripts/summarize @@ -23,6 +23,13 @@ set -uo pipefail repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +# For result_verdict alone. The verdict is the command's, not this script's, +# so the EXIT trap sourcing installs is dropped. +# shellcheck source-path=SCRIPTDIR +# shellcheck source=libs/result.sh +source "$repo_root/scripts/libs/result.sh" +trap - EXIT + if (( $# == 0 )); then echo "usage: scripts/summarize [args...]" >&2 echo " e.g. scripts/summarize scripts/ci" >&2 @@ -83,12 +90,9 @@ fi # A reader who keeps only the end of the output -- `| tail`, which also hides # the exit status behind its own -- still gets both, and an unavailable check # is counted beside FAIL rather than left for a FAIL-only grep to miss. -verdict="$1 exited $status:" -for state in FAIL unavailable not-applicable pass would-run; do - count="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" - [[ "$state" == would-run && "$count" == 0 ]] && continue - verdict+=" $count $state," +for state in "${!result_counts[@]}"; do + result_counts[$state]="$(grep -cE "^[A-Za-z0-9_-]+ +$state( |\$)" <<< "$table")" done -echo "${verdict%,}" +result_verdict "$1" "$status" exit "$status" diff --git a/scripts/tests/attribute-commit-test b/scripts/tests/attribute-commit-test index f004d263..9a785fbc 100755 --- a/scripts/tests/attribute-commit-test +++ b/scripts/tests/attribute-commit-test @@ -413,6 +413,19 @@ else fail "the message parses as: $(trailers "$out")" fi +# Spacing around the name must not leave a hyphen at either end of the ID. +fixture "extra spaces around the display name leave no end hyphen" +out="$(rewrite "feat: add a thing + +A body. + +Co-Authored-By: Claude Opus 4.6 (1M context) ")" +if [[ "$(trailers "$out")" == "Generated-By: claude-opus-4-6" ]]; then + pass +else + fail "the rewritten message parses as: $(trailers "$out")" +fi + # --check at commit-msg: prints nothing and exits 0 for a model ID, refuses # anything else with the line to write. verify() { @@ -425,10 +438,13 @@ out="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: claude-opus-5-5')" status=$? out2="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: gpt-5.1-codex')" status2=$? -if (( status == 0 && status2 == 0 )) && [[ -z "$out$out2" ]]; then +# Other vendors' IDs carry a tag, a version date, or a provider path. +out3="$(verify $'feat: add a thing\n\nA body.\n\nGenerated-By: qwen3-coder:30b\nGenerated-By: claude-opus-4-1@20250805\nGenerated-By: meta/Llama-3.1-8B')" +status3=$? +if (( status == 0 && status2 == 0 && status3 == 0 )) && [[ -z "$out$out2$out3" ]]; then pass else - fail "a model ID was refused (exit $status, $status2): $out $out2" + fail "a model ID was refused (exit $status, $status2, $status3): $out $out2 $out3" fi fixture "--check refuses a display name" @@ -449,13 +465,15 @@ else fail "a [1m] suffix passed: $out" fi -fixture "--check names the line a missing trailer needs" -out="$(verify $'feat: add a thing\n\nA body.')" +# commitlint's trailer-exists refuses a missing trailer and skips the merge, +# revert, and fixup subjects on its ignore list; refusing here would undo that. +fixture "--check leaves a missing trailer to commitlint" +out="$(verify $'Merge branch \'main\' into feature')" status=$? -if (( status != 0 )) && grep -q "Generated-By: " <<< "$out"; then +if (( status == 0 )) && [[ -z "$out" ]]; then pass else - fail "a missing trailer was not refused with the fix, exit $status: $out" + fail "a merge with no trailer was refused, exit $status: $out" fi fixture "--check passes a replayed commit" diff --git a/scripts/tests/payload-parity-test b/scripts/tests/payload-parity-test index a084a2b8..fb1384aa 100755 --- a/scripts/tests/payload-parity-test +++ b/scripts/tests/payload-parity-test @@ -141,6 +141,20 @@ else fail "wanted a root-to-payload command that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" fi +# A staged deletion counts as the edit, and its mirror removes the other copy; +# a cp from the deleted copy would fail. +parity_fixture "a deletion of one copy names the git rm that mirrors it" +commit_fixture +rm "$work/$payload/workflows/ci.yml" +audit +fix="$(sed -n 's/.*; run: //p' "$work/.audit-output")" +if [[ "$fix" == "git rm .github/workflows/ci.yml" ]] \ + && (cd "$work" && eval "$fix" > /dev/null) && run_parity && (( parity_status == 0 )); then + pass +else + fail "wanted a git rm that resolves it, got '$fix', then: $(head -1 "$work/.audit-output")" +fi + parity_fixture "an edit to both copies names no direction" commit_fixture write ".github/workflows/ci.yml" one diff --git a/scripts/tests/precommit-hooks-test b/scripts/tests/precommit-hooks-test index f89c935d..12feb4e2 100755 --- a/scripts/tests/precommit-hooks-test +++ b/scripts/tests/precommit-hooks-test @@ -149,10 +149,14 @@ fi # A machine-wide core.hooksPath makes `pre-commit install` refuse, so the fix # doctor prints there must be one that works with the key set: run verbatim, -# it leaves nothing missing, and the global key is untouched. +# it leaves nothing missing, and the global key is untouched. The clone's path +# holds a space, so the remedy must quote it. if command -v pre-commit >/dev/null 2>&1; then fixture "doctor's remedy under a global core.hooksPath installs every hook" 'default_install_hook_types: [pre-commit, commit-msg] repos: []' + mv "$work" "$work with space" + work="$work with space" + PATH="$work/bin:$harness_path" printf '[core]\n\thooksPath = %s\n' "$work/global-hooks" > "$work/global-config" remedy="$(cd "$work" && GIT_CONFIG_GLOBAL="$work/global-config" scripts/doctor 2>&1 \ | sed -n 's/.*so run: \(.*\), leaving init.templateDir.*/\1/p')"