diff --git a/.github/workflows/ci-adr-evil-merge-guard.yaml b/.github/workflows/ci-adr-evil-merge-guard.yaml new file mode 100644 index 00000000000..c7fdc9a65db --- /dev/null +++ b/.github/workflows/ci-adr-evil-merge-guard.yaml @@ -0,0 +1,25 @@ +# Description: Fails when a merge commit in the PR's history introduces a +# docs/adr/*.md file present in neither of its parents ("evil merge" of +# governance content — invisible to per-commit review tooling). +name: 'CI: ADR Evil Merge Guard' + +on: + push: + branches: + - main + pull_request: + +jobs: + adr-evil-merge: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 + - name: Check for ADR files introduced inside merge commits + run: | + base="${{ github.event.pull_request.base.sha }}" + if [ -z "$base" ]; then + base="${{ github.event.before }}" + fi + ./scripts/cicd/check-adr-evil-merge.sh "$base" HEAD diff --git a/scripts/cicd/check-adr-evil-merge.sh b/scripts/cicd/check-adr-evil-merge.sh new file mode 100755 index 00000000000..0d5f94bf927 --- /dev/null +++ b/scripts/cicd/check-adr-evil-merge.sh @@ -0,0 +1,76 @@ +#!/bin/bash +# Description: Fails when a merge commit in the scanned range introduces a +# `docs/adr/*.md` file that is present in NEITHER of its parents ("evil merge" +# of governance content). Per-commit review tooling (`gh pr diff --patch`, +# incremental bot reviews) cannot see content that only exists inside a merge +# commit, so governance artifacts smuggled in that way take zero review. +# Added by phs-48 after AGENT-SESSION-0028 landed inside PR #16768's +# "merge main" commit (own commit on main: #17483). +# +# Usage: check-adr-evil-merge.sh [head-rev] +# exclusive range start (e.g. PR base sha, or `github.event.before`) +# [head-rev] inclusive range end, defaults to HEAD +# An all-zero base (new-branch push) is a no-op success. The range scan needs +# merge-commit history: run the workflow with `fetch-depth: 0`. +set -euo pipefail + +base="${1:?usage: check-adr-evil-merge.sh [head-rev]}" +head="${2:-HEAD}" +path='docs/adr/' +# The contract in the header is `docs/adr/*.md`. Matching the whole directory +# instead would fail a merge that adds a diagram or a fixture under it and +# report that as smuggled governance content. +pathspec='docs/adr/*.md' + +if [[ "$base" =~ ^0+$ ]]; then + exit 0 +fi + +# A range this script cannot resolve is not an empty range. `|| true` turned an +# unavailable base - which is what a force-push leaves behind in +# `github.event.before` - into a silent pass, so the guard reported green +# precisely when it had not looked. Exit 2 to keep "I could not run" distinct +# from the exit 1 that means "I found one". +rev_list_err="$(mktemp)" +trap 'rm -f "$rev_list_err"' EXIT +if ! merges="$(git rev-list --merges "$base..$head" 2>"$rev_list_err")"; then + echo "ERROR: cannot resolve the revision range ${base}..${head}" >&2 + sed 's/^/ git: /' "$rev_list_err" >&2 + echo " The guard did not run, so this is NOT evidence that no ADR was" >&2 + echo " evil-merged. Check out with fetch-depth: 0, or pass a base that" >&2 + echo " still exists (a force-push can orphan github.event.before)." >&2 + exit 2 +fi +if [ -z "$merges" ]; then + exit 0 +fi + +fail=0 +for merge in $merges; do + # `rev-list --parents -n 1` prints " ..." + parents="$(git rev-list --parents -n 1 "$merge")" + read -r _ first_parent other_parents <<< "$parents" + # Files ADDED relative to parent 1 under docs/adr/; then reject when no + # other parent contains the file either, i.e. it exists only in the merge. + while IFS= read -r file; do + [ -n "$file" ] || continue + in_some_parent=0 + for parent in $other_parents; do + if git cat-file -e "${parent}:${file}" 2>/dev/null; then + in_some_parent=1 + break + fi + done + if [ "$in_some_parent" -eq 0 ]; then + echo "ERROR: merge $(git rev-parse --short "$merge") introduces ${file}" >&2 + echo " present in neither of its parents — ADR governance content must land" >&2 + echo " on its own commit so per-commit review tools can see it." >&2 + fail=1 + fi + done < <(git diff-tree -r --name-only --diff-filter=A --no-commit-id "$first_parent" "$merge" -- "$pathspec") +done + +if [ "$fail" -ne 0 ]; then + echo "One or more merge commits evil-merged files under ${path}." >&2 +fi +exit "$fail" diff --git a/scripts/cicd/check-adr-evil-merge.test.ts b/scripts/cicd/check-adr-evil-merge.test.ts new file mode 100644 index 00000000000..c9904c61738 --- /dev/null +++ b/scripts/cicd/check-adr-evil-merge.test.ts @@ -0,0 +1,174 @@ +import { execFileSync, spawnSync } from 'node:child_process' +import fs from 'node:fs' +import os from 'node:os' +import path from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' + +const SCRIPT = path.join(import.meta.dirname, 'check-adr-evil-merge.sh') +const temporaryDirectories: string[] = [] + +const GIT_ENV = { + GIT_CONFIG_GLOBAL: '/dev/null', + GIT_CONFIG_SYSTEM: '/dev/null' +} + +// The script walks merge-commit history, so fixtures need a hermetic throwaway +// repo with real (non-shallow) history. +function tempGitRepo(): { dir: string; git: (...args: string[]) => string } { + const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'adr-evil-merge-')) + temporaryDirectories.push(dir) + const env = { ...process.env, ...GIT_ENV } + const git = (...args: string[]) => + execFileSync('git', args, { cwd: dir, encoding: 'utf8', env }) + git('init', '--initial-branch=main') + git('config', 'user.email', 'ci@example.com') + git('config', 'user.name', 'CI') + return { dir, git } +} + +function write(dir: string, rel: string, contents: string): void { + const filePath = path.join(dir, rel) + fs.mkdirSync(path.dirname(filePath), { recursive: true }) + fs.writeFileSync(filePath, contents) +} + +function commitAll( + git: (...args: string[]) => string, + message: string +): string { + git('add', '.') + git('commit', '-m', message) + return git('rev-parse', 'HEAD').trim() +} + +function runScript(dir: string, base: string, head = 'HEAD') { + return spawnSync('bash', [SCRIPT, base, head], { + cwd: dir, + encoding: 'utf8', + env: { ...process.env, ...GIT_ENV } + }) +} + +afterEach(() => { + for (const directory of temporaryDirectories.splice(0)) { + fs.rmSync(directory, { recursive: true, force: true }) + } +}) + +describe('check-adr-evil-merge', () => { + // A guard that exits 0 while printing to stderr reads as a pass with a + // warning, and nobody reads CI warnings. Exit status alone cannot tell the + // two apart, so every clean case asserts silence as well. + function expectSilentPass(result: ReturnType): void { + expect({ status: result.status, stderr: result.stderr }).toEqual({ + status: 0, + stderr: '' + }) + expect(result.stdout).toBe('') + } + + it('passes when the range has no merge commits', () => { + const { dir, git } = tempGitRepo() + write(dir, 'docs/adr/TOPIC-0001.md', '# adr\n') + const base = commitAll(git, 'base') + write(dir, 'src/index.ts', 'export {}\n') + commitAll(git, 'ordinary commit adds an unrelated file') + + expectSilentPass(runScript(dir, base)) + }) + + it('passes when the ADR arrived on a branch commit and the merge only integrates it', () => { + const { dir, git } = tempGitRepo() + write(dir, 'src/index.ts', 'export {}\n') + const base = commitAll(git, 'base') + git('checkout', '-b', 'feature') + write(dir, 'docs/adr/TOPIC-0002.md', '# adr\n') + commitAll(git, 'branch commit adds the ADR') + git('checkout', 'main') + git('merge', '--no-ff', '--no-edit', 'feature') + + expectSilentPass(runScript(dir, base)) + }) + + it('fails when a merge commit introduces a docs/adr file present in neither parent', () => { + const { dir, git } = tempGitRepo() + write(dir, 'src/index.ts', 'export {}\n') + commitAll(git, 'base') + git('checkout', '-b', 'feature') + write(dir, 'src/feature.ts', 'export {}\n') + commitAll(git, 'branch commit') + git('checkout', 'main') + write(dir, 'src/main-drift.ts', 'export {}\n') + const mainDrift = commitAll(git, 'main drifts independently') + git('merge', '--no-ff', '--no-commit', 'feature') + // Smuggle governance content into the merge itself: present in NEITHER parent. + write(dir, 'docs/adr/TOPIC-0003-evil.md', '# smuggled\n') + git('add', '.') + git('commit', '-m', 'merge main and smuggle an ADR') + + const result = runScript(dir, mainDrift) + expect(result.status).toBe(1) + expect(result.stderr).toContain('docs/adr/TOPIC-0003-evil.md') + }) + + it('does not flag a merge that only resolves conflicts in files both parents already have', () => { + const { dir, git } = tempGitRepo() + write(dir, 'docs/adr/TOPIC-0004.md', '# adr\n') + commitAll(git, 'base') + git('checkout', '-b', 'feature') + write(dir, 'docs/adr/TOPIC-0004.md', '# adr with branch edit\n') + commitAll(git, 'branch edits the ADR') + git('checkout', 'main') + write(dir, 'docs/adr/TOPIC-0004.md', '# adr with main edit\n') + const mainEdit = commitAll(git, 'main edits the ADR') + expect(() => git('merge', '--no-ff', '--no-edit', 'feature')).toThrow() + write(dir, 'docs/adr/TOPIC-0004.md', '# adr resolved\n') + git('add', '.') + git('commit', '--no-edit') + + expectSilentPass(runScript(dir, mainEdit)) + }) + + it('is a no-op when the base is the all-zero new-branch sentinel', () => { + const { dir, git } = tempGitRepo() + write(dir, 'docs/adr/TOPIC-0005.md', '# adr\n') + commitAll(git, 'base') + + expectSilentPass(runScript(dir, '0'.repeat(40))) + }) + + it('ignores a non-Markdown file smuggled into a merge', () => { + const { dir, git } = tempGitRepo() + write(dir, 'src/index.ts', 'export {}\n') + commitAll(git, 'base') + git('checkout', '-b', 'feature') + write(dir, 'src/feature.ts', 'export {}\n') + commitAll(git, 'branch commit') + git('checkout', 'main') + write(dir, 'src/main-drift.ts', 'export {}\n') + const mainDrift = commitAll(git, 'main drifts independently') + git('merge', '--no-ff', '--no-commit', 'feature') + // The documented contract is `docs/adr/*.md`. A diagram is not governance + // content taking zero review, and reporting it as an evil-merged ADR + // teaches people to ignore the guard. + write(dir, 'docs/adr/diagram.svg', '\n') + git('add', '.') + git('commit', '-m', 'merge main and add an asset') + + expectSilentPass(runScript(dir, mainDrift)) + }) + + it('refuses to report a pass when the range cannot be resolved', () => { + const { dir, git } = tempGitRepo() + write(dir, 'docs/adr/TOPIC-0006.md', '# adr\n') + commitAll(git, 'base') + + // What a force-push leaves in `github.event.before`: a real-looking sha + // that no longer exists. Silently treating it as an empty range is the + // one outcome the guard must never produce. + const result = runScript(dir, 'f'.repeat(40)) + expect(result.status).not.toBe(0) + expect(result.status).not.toBe(1) + expect(result.stderr).toContain('cannot resolve the revision range') + }) +}) diff --git a/scripts/cicd/check-adr-links.sh b/scripts/cicd/check-adr-links.sh index c69d3544030..e8b6a18faa4 100755 --- a/scripts/cicd/check-adr-links.sh +++ b/scripts/cicd/check-adr-links.sh @@ -10,8 +10,16 @@ set -euo pipefail repo_root="$(git rev-parse --show-toplevel)" cd "$repo_root" +# The ADR tooling's own tests build throwaway repos whose fixtures are ADR paths +# that deliberately do not exist here (TOPIC-0001 and friends, spelled out in +# those files). They are inputs to those scripts, not references a reader could +# follow, so scanning them would make every such fixture a permanent dangling +# ref. Note this comment cannot spell such a path either: the scan reads its own +# source too. +adr_fixture_sources=':(exclude)scripts/cicd/check-adr-*.test.ts' + # git grep exit code 1 means "no matches", which is success for this check. -if refs=$(git grep -nEo 'docs/adr/[A-Za-z0-9._/-]+\.md' -- .); then +if refs=$(git grep -nEo 'docs/adr/[A-Za-z0-9._/-]+\.md' -- . "$adr_fixture_sources"); then : else grep_status=$? diff --git a/scripts/cicd/check-adr-links.test.ts b/scripts/cicd/check-adr-links.test.ts index 914e4bfeb0f..d14a550cfec 100644 --- a/scripts/cicd/check-adr-links.test.ts +++ b/scripts/cicd/check-adr-links.test.ts @@ -92,6 +92,39 @@ describe('check-adr-links', () => { expect(result.status).toBe(0) }) + it('ignores the ADR tooling tests, whose fixture paths never exist', () => { + // `check-adr-evil-merge.test.ts` writes `docs/adr/TOPIC-0001.md` into + // throwaway repos to exercise the evil-merge guard. Those strings are + // inputs to that script, not references a reader follows, so scanning + // them would make every fixture a permanent dangling ref here. + const { dir, git } = tempGitRepo() + write( + dir, + 'scripts/cicd/check-adr-evil-merge.test.ts', + `write(dir, '${adrPath('TOPIC-0001.md')}', '# fixture\\n')\n` + ) + git('add', '.') + git('commit', '-m', 'fixture') + + const result = runScript(dir) + expect(result.status).toBe(0) + }) + + it('still scans ordinary files under scripts/cicd', () => { + const { dir, git } = tempGitRepo() + write( + dir, + 'scripts/cicd/check-adr-links.sh', + `# see ${adrPath('TOPIC-0404-missing.md')}\n` + ) + git('add', '.') + git('commit', '-m', 'fixture') + + const result = runScript(dir) + expect(result.status).toBe(1) + expect(result.stderr).toContain(adrPath('TOPIC-0404-missing.md')) + }) + it('propagates git grep errors', () => { const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'adr-links-not-git-')) temporaryDirectories.push(dir)