Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/workflows/ci-adr-evil-merge-guard.yaml
Original file line number Diff line number Diff line change
@@ -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
76 changes: 76 additions & 0 deletions scripts/cicd/check-adr-evil-merge.sh
Original file line number Diff line number Diff line change
@@ -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 <base-rev> [head-rev]
# <base-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 <base-rev> [head-rev]}"
head="${2:-HEAD}"
path='docs/adr/'
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
# 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 "<merge> <parent1> <parent2> ..."
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"
174 changes: 174 additions & 0 deletions scripts/cicd/check-adr-evil-merge.test.ts
Original file line number Diff line number Diff line change
@@ -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<typeof runScript>): 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')
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
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', '<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')
})
})
10 changes: 9 additions & 1 deletion scripts/cicd/check-adr-links.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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=$?
Expand Down
33 changes: 33 additions & 0 deletions scripts/cicd/check-adr-links.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Loading