@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/better-review/scripts/rereview-scope.mjs

@@ -0,0 +1,503 @@
+// Pick the review tier for a new HEAD, from the previous round's result file.
+//
+//   node rereview-scope.mjs --prior <previous-result.json> --base <target-branch> [--head HEAD]
+//                           [--write-skip <next-result.json>]
+//
+// Prints JSON with `tier`:
+//   skip   no reviewer runs: the previous review passed and the PR's own changes are unchanged
+//          (the same HEAD; the same patch over a base that moved only outside the PR's files;
+//          or, with both reviewed commits at hand, every PR file's own changed lines the same,
+//          at the same places, after the base moved under them).
+//          With --write-skip, the script writes the record that carries the approval to
+//          this HEAD; CI on this HEAD is the proof.
+//   delta  review `touchedFiles` (fix commits, and PR files the base moved under) in full
+//          depth and re-check `carriedFiles` only where they depend on what changed.
+//   full   review the whole diff again; `reasons` names each trigger.
+// The reviewer may widen the tier, never narrow it.
+//
+// A skip needs a previous review that is complete, anchored, and has no open P0/P1: a
+// blocker is never carried, it is fixed. A delta is allowed only when the previous round covered the whole diff (every pass done
+// or skipped for a stated reason, not oversize), and the fixes and integration changes
+// since the last full round changed at most half the PR's lines in total. Conflicted
+// files join the delta as `integrationFiles`; imported base lines do not count as fixes.
+// Unbounded integration impact forces full. The base diff remains mandatory review input.
+// Neither the round number nor a previous delta forces full: impact does. A rebase or
+// metadata-only commit that leaves the PR's own patch unchanged reuses the review, even
+// when the reviewed HEAD is gone, using a location-sensitive `patchFingerprint` as well
+// as `patchId`. A reachable prior HEAD must also have no changed PR-file content before
+// its source approval can carry. Anything this script cannot establish (unreachable
+// history without both identities, or missing fields) forces full.
+//
+// The result file of each round records `patchId`, `patchFingerprint` and
+// `fixLinesSinceFull` from this output (round 1 takes the identities from pr-context
+// and `fixLinesSinceFull: 0`).
+//
+// On a delta it also hands the reviewer its setup, so the round starts reviewing at once:
+// the open P0/P1 findings in full, the previous sweep points that sit in touched files, the
+// names the fix diff defines or changes, every line in a carried file that uses one of them,
+// and scan-diff's leads and findings for the fix diff alone.
+//
+// Exit codes: 0 tier printed, 2 usage error or unreadable prior result.
+
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import fs from 'node:fs'
+import { isMainModule } from '../../engineering-runtime/scripts/main-module.mjs'
+import { reviewCompletionProblems, reviewTier } from '../../engineering-runtime/scripts/review-completion.mjs'
+import { scanDiff } from './scan-diff.mjs'
+
+export const MAX_FIX_SHARE = 0.5
+export const MAX_CALL_SITES = 200
+export const MAX_FIX_DIFF_CHARS = 60000
+
+const USAGE = 'usage: rereview-scope.mjs --prior <previous-result.json> --base <target-branch> [--head HEAD] [--write-skip <next-result.json>]'
+export const TIERS = Object.freeze(['skip', 'delta', 'full'])
+const isBlocking = (f) => f?.severity === 'P0' || f?.severity === 'P1'
+
+export class RereviewScopeError extends Error {}
+
+// ---- pure core ----
+
+// Reasons the previous result cannot anchor a delta. Empty means it can.
+export function priorProblems(prior) {
+  const problems = reviewCompletionProblems(prior, { requirePasses: true }).map((problem) => `previous ${problem}`)
+  if (typeof prior?.head !== 'string' || prior.head.trim() === '') problems.push('previous result has no head')
+  if (typeof prior?.mergeBase !== 'string' || prior.mergeBase.trim() === '') problems.push('previous result has no mergeBase')
+  if (!Number.isInteger(prior?.round) || prior.round < 1) problems.push('previous result has no round')
+  const tier = reviewTier(prior)
+  if (tier !== undefined && !TIERS.includes(tier)) problems.push(`previous round has unknown tier ${JSON.stringify(tier)}`)
+  if ((tier === 'delta' || tier === 'skip') && !(Number.isInteger(prior.fixLinesSinceFull) && prior.fixLinesSinceFull >= 0)) {
+    problems.push(`previous ${tier} round has no fixLinesSinceFull`)
+  }
+  if (prior?.oversize === true) problems.push('previous round was oversize')
+  if (Object.hasOwn(prior ?? {}, 'fixRound') && (!Number.isSafeInteger(prior.fixRound) || prior.fixRound < 1 || prior.fixRound > prior.round)) {
+    problems.push('previous fixRound must be a positive safe integer no greater than round')
+  }
+
+  return problems
+}
+
+// Sum added + deleted lines from `git diff --numstat` output; binary files count as 1.
+export function numstatLines(text) {
+  let total = 0
+  for (const line of (text || '').split('\n')) {
+    const m = line.match(/^(\d+|-)\t(\d+|-)\t/)
+    if (!m) continue
+    total += m[1] === '-' ? 1 : Number(m[1]) + Number(m[2])
+  }
+  return total
+}
+
+// `samePatch`: the reviewed HEAD is gone, but the PR's own patch is identical to the one
+// reviewed (a content-equivalent rebase), so nothing in the PR changed.
+// `conflictFiles`: PR files the base moved under whose own PR changes also changed.
+// `baseKnown`: the previous merge-base is in this repository, so base movement is known.
+// `sameHead`: the HEAD is the one the previous round reviewed.
+// `ownUnchanged`: every PR file's own changed lines are the ones reviewed, at the same places
+// once the base's own edits are mapped out; only the base moved. CI on the new HEAD proves
+// how the two fit together.
+export function decideScope({ prior, round, prFiles, touchedFiles, baseMovedFiles, fixLines, prLines, priorHeadReachable, samePatch = false, sameHead = false, conflictFiles = [], integrationLines = 0, baseKnown = true, ownUnchanged = false }) {
+  const reasons = [...priorProblems(prior)]
+  if (!priorHeadReachable && !samePatch) reasons.push(`previous HEAD ${prior?.head} is not in this repository and its patch identities differ or are missing`)
+  if (!baseKnown) reasons.push(`previous merge-base ${prior?.mergeBase} is not in this repository`)
+  const prSet = new Set(prFiles)
+  const conflicts = new Set(conflictFiles)
+  const underPr = baseMovedFiles.filter((file) => prSet.has(file))
+  const conflicted = underPr.filter((file) => conflicts.has(file))
+  if (integrationLines === null) reasons.push('integration impact cannot be bounded; review the whole diff')
+  const mergeFiles = underPr.filter((file) => !conflicts.has(file))
+  const sinceFull = (reviewTier(prior) !== undefined && reviewTier(prior) !== 'full' && Number.isInteger(prior.fixLinesSinceFull) ? prior.fixLinesSinceFull : 0) + fixLines + (integrationLines ?? 0)
+  if (prLines > 0 && sinceFull / prLines > MAX_FIX_SHARE) {
+    reasons.push(`the fixes since the last full review changed ${sinceFull} of ${prLines} PR lines (more than ${MAX_FIX_SHARE * 100}%)`)
+  }
+  if (prLines === 0 && sinceFull > 0) reasons.push('the previously reviewed PR changes were removed')
+  const touched = new Set([...touchedFiles, ...mergeFiles, ...conflicted])
+  const passed = Array.isArray(prior?.findings) && !prior.findings.some(isBlocking)
+  const unchanged = sameHead || (samePatch && baseKnown && underPr.length === 0) || (ownUnchanged && baseKnown && priorHeadReachable)
+  const tier = reasons.length > 0 ? 'full' : passed && unchanged ? 'skip' : 'delta'
+  return {
+    tier,
+    reasons,
+    round,
+    touchedFiles: prFiles.filter((file) => touched.has(file)),
+    carriedFiles: prFiles.filter((file) => !touched.has(file)),
+    fixLines,
+    integrationLines,
+    prLines,
+    fixLinesSinceFull: tier === 'full' ? 0 : sinceFull,
+    mergeFiles,
+    integrationFiles: conflicted,
+  }
+}
+
+// Names a diff defines or changes, from its added and removed lines (not context): top-level
+// code definitions in JS/TS/Python-style syntax (unindented or exported; a local variable is
+// nobody else's contract), plus Markdown headings as link anchors (`#slug`), since prose files
+// link to each other by heading. Test files define nothing other code uses, so they are
+// skipped. Best effort: a miss leaves the reviewer's own search as the only net, so this
+// never replaces reading the fix diff.
+const DEFINITION_PATTERNS = [
+  /^(?:export\s+(?:default\s+)?)?(?:async\s+)?(?:function\*?|class|def|interface|type|enum)\s+([A-Za-z_$][\w$]*)/,
+  /^(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/,
+  /^\s*export\s+(?:default\s+)?(?:async\s+)?(?:function\*?|class|const|let|var|interface|type|enum)\s+([A-Za-z_$][\w$]*)/,
+]
+const TEST_FILE = /(^|\/)(__tests__|tests?)\/|[._-](test|spec)\.[cm]?[jt]sx?$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$/
+const NOT_NAMES = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'constructor'])
+
+export function headingSlug(text) {
+  return text.trim().toLowerCase().replace(/[`*_~]/g, '').replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/\s/g, '-')
+}
+
+export function changedSymbols(diffText) {
+  const names = new Set()
+  const anchors = new Set()
+  let file = ''
+  for (const raw of (diffText || '').split(/\r?\n/)) {
+    if (raw.startsWith('+++ ') || raw.startsWith('--- ')) { file = raw.slice(4).replace(/^[ab]\//, ''); continue }
+    if (!/^[+-]/.test(raw)) continue
+    const line = raw.slice(1)
+    if (/\.(md|mdx)$/i.test(file)) {
+      const h = line.match(/^#{1,6}\s+(.+?)\s*#*\s*$/)
+      if (h) anchors.add(`#${headingSlug(h[1])}`)
+      continue
+    }
+    if (TEST_FILE.test(file)) continue
+    for (const pattern of DEFINITION_PATTERNS) {
+      const m = line.match(pattern)
+      if (m && !NOT_NAMES.has(m[1]) && m[1].length > 2) names.add(m[1])
+    }
+  }
+  return { names: [...names].sort(), anchors: [...anchors].sort() }
+}
+
+// The previous round's sweep points whose location is a touched file.
+export function sweepRecheck(prior, touchedFiles) {
+  const touched = new Set(touchedFiles)
+  const out = []
+  for (const sweep of prior?.sweeps ?? []) {
+    for (const point of sweep?.points ?? []) {
+      const file = String(point?.location ?? '').replace(/:\d+(?:-\d+)?$/, '')
+      if (touched.has(file)) out.push({ rule: sweep.rule, ...point })
+    }
+  }
+  return out
+}
+
+// ---- git glue ----
+
+function git(args) {
+  return execFileSync('git', args, { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 }).trim()
+}
+
+// The whitespace-preserving patch id of the PR's net diff, or null for an empty diff.
+// Whitespace can change behavior (for example Python indentation), so it is not metadata.
+export function prPatchId(mergeBase, head, paths = []) {
+  const diff = execFileSync('git', ['diff', '--binary', `${mergeBase}...${head}`, ...(paths.length ? ['--', ...paths] : [])], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 })
+  if (diff.trim() === '') return null
+  const out = execFileSync('git', ['patch-id', '--verbatim'], { input: diff, encoding: 'utf8' }).trim()
+  return out.split(/\s+/)[0] || null
+}
+
+// Unlike patch-id, this preserves hunk locations as well as whitespace and binary bytes.
+// Ignore only blob ids: base edits outside the patch can change them after a rebase.
+export function prPatchFingerprint(mergeBase, head) {
+  const diff = execFileSync('git', ['diff', '--binary', `${mergeBase}...${head}`], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 })
+  if (diff.trim() === '') return null
+  const patch = diff.split('\n').filter((line) => !/^index [0-9a-f]+\.\.[0-9a-f]+(?: \d+)?$/.test(line)).join('\n')
+  return createHash('sha256').update(patch).digest('hex')
+}
+
+// Compare the PR's own changed lines, not the old/new trees (which include base imports).
+// Sequence comparison counts reordered changes too. Large or binary patches fail closed.
+export function patchImpactLines(before, after, baseDiff = '') {
+  if (before === after) return 0
+  if (before.length + after.length > MAX_FIX_DIFF_CHARS * 2) return null
+  if (/^(?:Binary files |GIT binary patch)/m.test(before + '\n' + after)) return null
+  const baseHunks = [...baseDiff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)]
+    .map((match) => ({ oldStart: Number(match[1]), oldCount: Number(match[2] ?? 1), newStart: Number(match[3]), newCount: Number(match[4] ?? 1) }))
+  // Map new-base anchors back to the reviewed base. Pure base insertions shift
+  // lines but not edit targets; anchors inside rewritten base hunks are new.
+  const reviewedAnchor = (line) => {
+    let offset = 0
+    for (const hunk of baseHunks) {
+      const start = hunk.newCount === 0 ? hunk.newStart + 1 : hunk.newStart
+      if (line < start) break
+      if (hunk.newCount > 0 && line < start + hunk.newCount) return `new:${line}`
+      offset += hunk.oldCount - hunk.newCount
+    }
+    return line + offset
+  }
+  const changed = (diff, mapAnchor = (line) => line) => {
+    const out = []
+    let hunk = false
+    let context = ''
+    let oldLine = 0
+    for (const line of diff.split('\n')) {
+      if (line.startsWith('diff --git ')) hunk = false
+      else if (line.startsWith('@@ ')) {
+        hunk = true
+        context = line.slice(line.indexOf(' @@') + 3)
+        oldLine = Number(/^@@ -(\d+)/.exec(line)?.[1])
+      } else if (hunk && /^[+-]/.test(line)) {
+        out.push(`${mapAnchor(oldLine)}\0${context}\0${line}`)
+        if (line.startsWith('-')) oldLine++
+      } else if (hunk && line.startsWith(' ')) oldLine++
+    }
+    return out
+  }
+  const a = changed(before)
+  const b = changed(after, reviewedAnchor)
+  if (a.length * b.length > 4_000_000) return null
+  let previous = new Uint32Array(b.length + 1)
+  for (const line of a) {
+    const current = new Uint32Array(b.length + 1)
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = line === b[j - 1] ? previous[j - 1] + 1 : Math.max(previous[j], current[j - 1])
+    }
+    previous = current
+  }
+  const impact = a.length + b.length - 2 * previous[b.length]
+  return impact
+}
+
+// True when a file's own PR lines are the reviewed ones at the same places, once the base's
+// edits are mapped out: `before` and `after` are the file's PR diffs (--unified=0) over the
+// reviewed and the current base, `baseDiff` the base's own change between them. A PR insertion
+// that now sits just before or after lines the base inserted at the same point kept both sides
+// of a conflict, so it is unchanged; a PR line that edits or replaces a base line is not.
+// Large or binary patches fail closed (false).
+export function ownLinesUnchanged(before, after, baseDiff = '') {
+  if (before === after) return true
+  if (before.length + after.length > MAX_FIX_DIFF_CHARS * 2) return false
+  if (/^(?:Binary files |GIT binary patch)/m.test(before + '\n' + after)) return false
+  const hunks = (diff) => [...diff.matchAll(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm)]
+    .map((m) => ({ oldStart: Number(m[1]), oldCount: Number(m[2] ?? 1), newStart: Number(m[3]), newCount: Number(m[4] ?? 1) }))
+  const base = hunks(baseDiff)
+  // A line of the current base, as a line of the reviewed base; null inside base-rewritten lines.
+  const toReviewed = (line, insertion) => {
+    let offset = 0
+    for (const h of base) {
+      if (insertion && h.oldCount === 0 && (line === h.newStart - 1 || line === h.newStart + h.newCount - 1)) return h.oldStart
+      const start = h.newCount === 0 ? h.newStart + 1 : h.newStart
+      if (line < start) break
+      if (h.newCount > 0 && line < start + h.newCount) return null
+      offset += h.oldCount - h.newCount
+    }
+    return line + offset
+  }
+  const rows = (diff, map) => {
+    const out = []
+    let hunk = null
+    let oldLine = 0
+    for (const line of diff.split('\n')) {
+      if (line.startsWith('diff --git ')) hunk = null
+      else if (line.startsWith('@@ ')) {
+        const m = /^@@ -(\d+)(?:,(\d+))?/.exec(line)
+        hunk = { insertion: Number(m[2] ?? 1) === 0 }
+        oldLine = Number(m[1])
+        // A reviewed hunk that comes back split around base lines is a change.
+        out.push('@@')
+      } else if (hunk && /^[+-]/.test(line)) {
+        const at = map(oldLine, hunk.insertion)
+        if (at === null) return null
+        out.push(`${at}\0${line}`)
+        if (line.startsWith('-')) oldLine++
+      }
+    }
+    return out
+  }
+  const a = rows(before, (line) => line)
+  const b = rows(after, toReviewed)
+  return a !== null && b !== null && a.length === b.length && a.every((row, i) => row === b[i])
+}
+
+function reachable(rev) {
+  try { git(['cat-file', '-e', `${rev}^{commit}`]); return true } catch { return false }
+}
+
+const lines = (text) => text.split('\n').filter(Boolean)
+
+export function parseCliArgs(argv) {
+  const opts = { head: 'HEAD' }
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]
+    if (flag === '--help' || flag === '-h') return { help: true }
+    if (!['--prior', '--base', '--head', '--write-skip'].includes(flag)) throw new RereviewScopeError(`unknown flag ${JSON.stringify(flag)}\n${USAGE}`)
+    const value = argv[++i]
+    if (value === undefined || value.startsWith('--')) throw new RereviewScopeError(`${flag} needs a value\n${USAGE}`)
+    opts[flag === '--write-skip' ? 'writeSkip' : flag.slice(2)] = value
+  }
+  if (!opts.prior || !opts.base) throw new RereviewScopeError(USAGE)
+  return opts
+}
+
+export function rereviewScope({ prior, base, head = 'HEAD' }) {
+  const headSha = git(['rev-parse', head])
+  const mergeBase = git(['merge-base', base, headSha])
+  const currentPrFiles = lines(git(['diff', '--no-renames', '--name-only', `${mergeBase}...${headSha}`]))
+  const prLines = numstatLines(git(['diff', '--numstat', `${mergeBase}...${headSha}`]))
+  const round = (Number.isInteger(prior?.round) ? prior.round : 0) + 1
+  const priorHeadReachable = typeof prior?.head === 'string' && reachable(prior.head)
+  const priorBaseReachable = typeof prior?.mergeBase === 'string' && reachable(prior.mergeBase)
+  const patchId = prPatchId(mergeBase, headSha)
+  const patchFingerprint = prPatchFingerprint(mergeBase, headSha)
+  const priorPatchId = priorHeadReachable && priorBaseReachable ? prPatchId(prior.mergeBase, prior.head) : prior?.patchId
+  const priorPrFiles = priorHeadReachable && priorBaseReachable
+    ? lines(git(['diff', '--no-renames', '--name-only', `${prior.mergeBase}...${prior.head}`])) : []
+  const prFiles = [...new Set([...currentPrFiles, ...priorPrFiles])]
+  const treeTouched = priorHeadReachable && prFiles.length
+    ? lines(git(['diff', '--no-renames', '--name-only', prior.head, headSha, '--', ...prFiles])) : []
+  const samePatch = typeof priorPatchId === 'string' && patchId !== null && priorPatchId === patchId
+    && (priorHeadReachable ? treeTouched.length === 0
+      : typeof prior?.patchFingerprint === 'string' && patchFingerprint === prior.patchFingerprint)
+  let baseMovedFiles = []
+  if (priorBaseReachable && prior.mergeBase !== mergeBase) {
+    baseMovedFiles = lines(git(['diff', '--no-renames', '--name-only', prior.mergeBase, mergeBase]))
+  }
+  const prSet = new Set(prFiles)
+  const overlap = baseMovedFiles.filter((file) => prSet.has(file))
+  // A PR file the base moved under had its own PR changes altered when its per-file patch
+  // differs from the reviewed one: a conflict resolution or a fix landed there too.
+  const conflictFiles = samePatch ? [] : overlap.filter((file) => !priorHeadReachable
+    || prPatchId(prior.mergeBase, prior.head, [file]) !== prPatchId(mergeBase, headSha, [file]))
+  let touchedFiles = prFiles
+  let fixLines = prLines
+  let integrationLines = 0
+  if (samePatch) {
+    touchedFiles = []
+    fixLines = 0
+  } else if (priorHeadReachable && prFiles.length > 0) {
+    touchedFiles = treeTouched
+    // Lines the base alone changed are not fix lines. Compare overlapping PR patches separately.
+    const ownFiles = prFiles.filter((file) => !overlap.includes(file))
+    fixLines = ownFiles.length ? numstatLines(git(['diff', '--numstat', prior.head, headSha, '--', ...ownFiles])) : 0
+    if (priorBaseReachable) for (const file of conflictFiles) {
+      const before = git(['diff', '--no-renames', '--unified=0', prior.mergeBase, prior.head, '--', file])
+      const after = git(['diff', '--no-renames', '--unified=0', mergeBase, headSha, '--', file])
+      const baseDiff = git(['diff', '--no-renames', '--unified=0', prior.mergeBase, mergeBase, '--', file])
+      const impact = patchImpactLines(before, after, baseDiff)
+      if (impact === null) { integrationLines = null; break }
+      integrationLines += impact
+    }
+  }
+  const sameHead = priorHeadReachable && prior.head === headSha
+  // The base moved under PR files: are the PR's own lines there still the reviewed ones?
+  let ownUnchanged = false
+  if (!samePatch && priorHeadReachable && priorBaseReachable && overlap.length > 0 && fixLines === 0 && integrationLines !== null) {
+    ownUnchanged = overlap.every((file) => ownLinesUnchanged(
+      git(['diff', '--no-renames', '--unified=0', prior.mergeBase, prior.head, '--', file]),
+      git(['diff', '--no-renames', '--unified=0', mergeBase, headSha, '--', file]),
+      git(['diff', '--no-renames', '--unified=0', prior.mergeBase, mergeBase, '--', file])))
+  }
+  const decision = decideScope({ prior, round, prFiles, touchedFiles, baseMovedFiles, fixLines, integrationLines, prLines, priorHeadReachable, samePatch, sameHead, conflictFiles, baseKnown: priorBaseReachable, ownUnchanged })
+  const openFindings = (prior?.findings ?? []).filter(isBlocking)
+  const priorFixRound = prior?.fixRound ?? prior?.round
+  const fixRound = Number.isSafeInteger(priorFixRound) && priorFixRound >= 1
+    ? priorFixRound + (reviewCompletionProblems(prior).length === 0 && openFindings.length > 0 ? 1 : 0) : null
+  const result = {
+    ...decision,
+    fixRound,
+    head: headSha,
+    mergeBase,
+    patchId,
+    patchFingerprint,
+    samePatch,
+    priorHead: prior?.head ?? null,
+    baseMovedFiles,
+    baseDiffCommand: baseMovedFiles.length ? `git diff ${prior.mergeBase} ${mergeBase}` : null,
+    fixDiffCommand: null,
+    mergeDiffCommand: overlap.length ? `git diff ${prior.mergeBase} ${mergeBase} -- ${overlap.join(' ')}` : null,
+    openFindings,
+  }
+  if (decision.tier !== 'delta') return result
+  if (decision.touchedFiles.length === 0) {
+    // Nothing in the PR changed since the reviewed round: no fix diff to review.
+    return { ...result, fixDiff: '', sweepRecheck: [], changedSymbols: { names: [], anchors: [] }, callSites: { sites: [], truncated: false }, fixScan: { findings: [], leads: [] } }
+  }
+  // With the reviewed HEAD gone (samePatch), the only change is the merge diff.
+  const fixDiffArgs = samePatch
+    ? ['diff', prior.mergeBase, mergeBase, '--', ...decision.touchedFiles]
+    : ['diff', prior.head, headSha, '--', ...decision.touchedFiles]
+  const fixDiff = git(fixDiffArgs)
+  const symbols = changedSymbols(fixDiff)
+  const scan = scanDiff(fixDiff)
+  return {
+    ...result,
+    fixDiffCommand: `git ${fixDiffArgs.join(' ')}`,
+    fixDiff: fixDiff.length > MAX_FIX_DIFF_CHARS ? null : fixDiff,
+    sweepRecheck: sweepRecheck(prior, decision.touchedFiles),
+    changedSymbols: symbols,
+    callSites: callSites([...symbols.names, ...symbols.anchors], decision.carriedFiles, headSha),
+    fixScan: { findings: scan.findings, leads: scan.leads },
+  }
+}
+
+// The result file a skip writes in place of a review: the previous approval, carried to this
+// HEAD. It ran no checks of its own, found nothing new, and copies the coverage it carries.
+export function skipRecord(prior, scope) {
+  if (scope.tier !== 'skip') throw new RereviewScopeError(`tier is ${scope.tier}, not skip: spawn the reviewer`)
+  return {
+    version: prior.version ?? 1,
+    ...(prior.unit === undefined ? {} : { unit: prior.unit }),
+    round: scope.round,
+    fixRound: scope.fixRound,
+    head: scope.head,
+    mergeBase: scope.mergeBase,
+    patchId: scope.patchId,
+    patchFingerprint: scope.patchFingerprint,
+    tier: 'skip',
+    carriedFrom: prior.head,
+    fixLinesSinceFull: scope.fixLinesSinceFull,
+    oversize: false,
+    complete: true,
+    passes: prior.passes,
+    commands: [],
+    sweeps: prior.sweeps ?? [],
+    boundaries: prior.boundaries ?? [],
+    findings: [],
+  }
+}
+
+// Lines in the carried files that use a changed name, capped so a common name cannot flood it.
+function callSites(terms, files, rev) {
+  const sites = []
+  let truncated = false
+  if (files.length === 0) return { sites, truncated }
+  for (const term of terms) {
+    const word = /^[A-Za-z_$][\w$]*$/.test(term)
+    let out = ''
+    try {
+      out = git(['grep', '-n', '-F', ...(word ? ['-w'] : []), '-e', term, rev, '--', ...files])
+    } catch { continue } // git grep exits 1 on no match
+    for (const line of lines(out)) {
+      const m = line.startsWith(`${rev}:`) ? line.slice(rev.length + 1).match(/^([^:]+):(\d+):(.*)$/) : null
+      if (!m) continue
+      if (sites.length >= MAX_CALL_SITES) { truncated = true; break }
+      sites.push({ term, file: m[1], line: Number(m[2]), text: m[3].trim().slice(0, 200) })
+    }
+  }
+  return { sites, truncated }
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    const opts = parseCliArgs(process.argv.slice(2))
+    if (opts.help) {
+      console.log(USAGE)
+    } else {
+      let prior
+      try { prior = JSON.parse(fs.readFileSync(opts.prior, 'utf8')) } catch (error) {
+        throw new RereviewScopeError(`cannot read previous result ${opts.prior}: ${error.message}`)
+      }
+      const scope = rereviewScope({ prior, base: opts.base, head: opts.head })
+      if (opts.writeSkip && scope.tier === 'skip') {
+        fs.writeFileSync(opts.writeSkip, `${JSON.stringify(skipRecord(prior, scope), null, 2)}\n`)
+        scope.skipRecord = opts.writeSkip
+      }
+      console.log(JSON.stringify(scope, null, 2))
+    }
+  } catch (error) {
+    console.error(`rereview-scope: ${error.message}`)
+    process.exitCode = 2
+  }
+}