@mnstry/atelier 0.2.0-alpha.13 → 0.2.0-alpha.14

package/src/boundary/content-rules.mjs

@@ -1,10 +1,14 @@
 import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { matchesPathPattern, normalizeRelPath } from '../project/path-match.mjs'
 import { sanitizedGitEnvironment } from '../runtime/git-adapter.mjs'
 
 export const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904'
+const EMPTY_TREES = Object.freeze({ sha1: EMPTY_TREE, sha256: '6ef19b41225c5369f1c104d45d8d85efa9b057b53b14b4b9b939dd74decc5321' })
+// Commits one push may carry before the per-commit scan refuses rather than run long.
+export const PUSH_COMMIT_SCAN_MAX = 1000
 export const ZERO_SHA_RE = /^0{40,}$/
 
 export const RULE_KINDS = Object.freeze(['content', 'path'])
@@ -128,6 +132,9 @@ export function resolveContentRules(policy) {
 }
 
 export function findException({ exceptions = [], rule, repo, path: filePath }) {
+  // Exception paths are slash-normalised patterns, so they cannot name a file whose
+  // own name holds a backslash; such a file never inherits a sibling's exception.
+  if (String(filePath ?? '').includes('\\')) return null
   const rel = normalizeRelPath(filePath)
   return (
     exceptions.find(
@@ -141,6 +148,8 @@ export function findException({ exceptions = [], rule, repo, path: filePath }) {
 
 function rulePathMatches(rule, filePath) {
   if (!Array.isArray(rule.paths) || !rule.paths.length) return true
+  // Path scopes are slash-normalised too; a backslash name is treated as in scope.
+  if (String(filePath ?? '').includes('\\')) return true
   return rule.paths.some((pattern) => matchesPathPattern(pattern, filePath))
 }
 
@@ -154,13 +163,15 @@ function rulePathMatches(rule, filePath) {
 export function scanAddedContent({ files, rules = DEFAULT_CONTENT_RULES, exceptions = [], repo = null }) {
   const findings = []
   for (const file of files) {
-    const filePath = normalizeRelPath(file.path)
+    // Paths from Git are exact repository paths and are reported as they are.
+    const filePath = String(file.path ?? '')
     for (const rule of rules) {
       const kind = rule.kind ?? 'content'
       const severity = rule.severity ?? 'error'
       const exception = findException({ exceptions, rule: rule.id, repo, path: filePath })
       if (kind === 'path') {
-        if (!file.added || !new RegExp(rule.pattern, 'i').test(filePath)) continue
+        const pathRule = new RegExp(rule.pattern, 'i')
+        if (!file.added || !(pathRule.test(filePath) || pathRule.test(normalizeRelPath(filePath)))) continue
         if (exception) continue
         findings.push({ severity, code: 'content-rule-violation', rule: rule.id, repo, path: filePath, line: null, message: `${repo ?? ''}/${filePath}: ${rule.description ?? rule.id}`.replace(/^\//, '') })
         continue
@@ -170,7 +181,7 @@ export function scanAddedContent({ files, rules = DEFAULT_CONTENT_RULES, excepti
       for (const line of file.addedLines ?? []) {
         if (!re.test(line.text)) continue
         if (exception) continue
-        findings.push({
+        const found = {
           severity,
           code: 'content-rule-violation',
           rule: rule.id,
@@ -178,45 +189,242 @@ export function scanAddedContent({ files, rules = DEFAULT_CONTENT_RULES, excepti
           path: filePath,
           line: line.number,
           message: `${repo ?? ''}/${filePath}:${line.number}: ${rule.description ?? rule.id}`.replace(/^\//, ''),
-        })
+        }
+        // A digest of the line identifies the same content across diffs; it is
+        // not enumerable, so it never appears in a report.
+        Object.defineProperty(found, 'lineDigest', { value: createHash('sha256').update(line.text).digest('hex') })
+        findings.push(found)
       }
     }
   }
   return findings
 }
 
-/** Parse `git diff` output into added files and added lines with line numbers. */
-export function parseAddedContent(diff) {
-  const files = []
+// The diff commands below pin their own output format, so repository or user
+// configuration (prefixes, colour, external diff drivers, textconv, relative
+// paths, fused hunks, submodule summaries) cannot change what the parser reads.
+// Anything it still cannot read is reported and blocks, so a key not pinned here
+// can stop a commit but cannot hide content.
+export const CANONICAL_DIFF_FLAGS = Object.freeze([
+  '--no-ext-diff',
+  '--no-textconv',
+  '--no-color',
+  '--src-prefix=a/',
+  '--dst-prefix=b/',
+  '--no-relative',
+  '--inter-hunk-context=0',
+  '--submodule=short',
+  '--full-index',
+])
+
+const OCTAL_ESCAPE = /^[0-7]{3}$/
+const SIMPLE_ESCAPES = { a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, '\\': 92 }
+
+/**
+ * Read one C-quoted path token as Git writes it (core.quotePath), starting at the
+ * opening quote. Returns the decoded path and the index after the closing quote,
+ * or null when the token is malformed.
+ */
+function readQuotedToken(text, start) {
+  if (text[start] !== '"') return null
+  const bytes = []
+  for (let index = start + 1; index < text.length; index += 1) {
+    const char = String.fromCodePoint(text.codePointAt(index))
+    if (char === '"') return { value: Buffer.from(bytes).toString('utf8'), end: index + 1 }
+    if (char !== '\\') {
+      bytes.push(...Buffer.from(char, 'utf8'))
+      index += char.length - 1
+      continue
+    }
+    const next = text[index + 1]
+    if (next === undefined) return null
+    const octal = text.slice(index + 1, index + 4)
+    if (OCTAL_ESCAPE.test(octal)) {
+      const byte = Number.parseInt(octal, 8)
+      if (byte > 255) return null
+      bytes.push(byte)
+      index += 3
+    } else if (Object.hasOwn(SIMPLE_ESCAPES, next)) {
+      bytes.push(SIMPLE_ESCAPES[next])
+      index += 1
+    } else {
+      return null
+    }
+  }
+  return null
+}
+
+/** A path as it appears after a fixed prefix in a header line, quoted or bare. */
+function prefixedPath(token, prefix) {
+  if (token.startsWith('"')) {
+    const quoted = readQuotedToken(token, 0)
+    if (!quoted || quoted.end !== token.length || !quoted.value.startsWith(prefix)) return null
+    return quoted.value.slice(prefix.length)
+  }
+  return token.startsWith(prefix) ? token.slice(prefix.length) : null
+}
+
+/**
+ * The destination path of a `diff --git` header. A bare header is ambiguous when
+ * a path contains " b/", so it is resolved only when both sides name the same
+ * path, which is every case except a rename or copy; those are resolved from the
+ * `rename to` / `copy to` lines that follow.
+ */
+export function diffHeaderPath(line) {
+  if (!line.startsWith('diff --git ')) return null
+  const rest = line.slice('diff --git '.length)
+  if (rest.startsWith('"')) {
+    const first = readQuotedToken(rest, 0)
+    if (!first || rest[first.end] !== ' ') return null
+    return prefixedPath(rest.slice(first.end + 1), 'b/')
+  }
+  if (rest.endsWith('"')) {
+    const open = rest.lastIndexOf(' "')
+    return open < 0 ? null : prefixedPath(rest.slice(open + 1), 'b/')
+  }
+  if (rest.length < 5 || (rest.length - 5) % 2 !== 0) return null
+  const half = (rest.length - 5) / 2
+  const candidate = rest.slice(2, 2 + half)
+  return half > 0 && rest === `a/${candidate} b/${candidate}` ? candidate : null
+}
+
+const HUNK_HEADER = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+const INDEX_LINE = /^index ([0-9a-f]{40,64})\.\.([0-9a-f]{40,64})(?: \d+)?$/
+
+/**
+ * Split `git diff --unified=0` output into file sections. Lines are read as
+ * content only inside a hunk, for exactly as many lines as its header counts, so
+ * content can never be read as a header and a header can never hide content. A
+ * section whose path or hunks cannot be read is returned with `incomplete` set,
+ * so the caller fails closed instead of skipping it. Paths are the exact
+ * repository paths Git reports; `newBlob` is the object id of the new content.
+ * With `detail`, each section also keeps its hunks (added and removed text) and
+ * the raw lines after its header.
+ */
+export function parseDiffSections(diff, { detail = false } = {}) {
+  const sections = []
   let current = null
+  let pendingAdded = 0
+  let pendingRemoved = 0
   let lineNumber = 0
   for (const raw of String(diff ?? '').split('\n')) {
+    if (detail && current && !raw.startsWith('diff --git ') && !raw.startsWith('* Unmerged path ')) current.lines.push(raw)
+    if (pendingAdded > 0 || pendingRemoved > 0) {
+      if (raw.startsWith('+') && pendingAdded > 0) {
+        current.addedLines.push({ number: lineNumber, text: raw.slice(1) })
+        if (detail) current.hunks.at(-1).added.push(raw.slice(1))
+        lineNumber += 1
+        pendingAdded -= 1
+        continue
+      }
+      if (raw.startsWith('-') && pendingRemoved > 0) {
+        if (detail) current.hunks.at(-1).removed.push(raw.slice(1))
+        pendingRemoved -= 1
+        continue
+      }
+      if (raw.startsWith(' ') && pendingAdded > 0 && pendingRemoved > 0) {
+        // A context line counts on both sides; none is expected, but one is harmless.
+        lineNumber += 1
+        pendingAdded -= 1
+        pendingRemoved -= 1
+        continue
+      }
+      if (raw.startsWith('\\')) continue // ""
+      current.incomplete = 'hunk-shorter-than-its-header'
+      pendingAdded = 0
+      pendingRemoved = 0
+    }
     if (raw.startsWith('diff --git ')) {
-      const header = raw.match(/^diff --git a\/(.*) b\/(.*)$/)
-      current = { path: header ? normalizeRelPath(header[2]) : null, added: false, addedLines: [] }
-      files.push(current)
+      const headerPath = diffHeaderPath(raw)
+      current = {
+        path: headerPath === null || headerPath === '' ? null : headerPath,
+        added: false,
+        deleted: false,
+        binary: false,
+        newBlob: null,
+        oldPath: null,
+        addedLines: [],
+        incomplete: null,
+        inHeader: true,
+        ...(detail ? { hunks: [], lines: [] } : {}),
+      }
+      sections.push(current)
       continue
     }
-    if (!current) continue
-    if (raw.startsWith('new file mode ')) {
-      current.added = true
+    if (raw.startsWith('* Unmerged path ')) {
+      // An unmerged entry has no patch to read; it stands as its own unreadable
+      // section instead of being taken for a line of the file before it. Git
+      // prints this name as it is, never quoted.
+      const listed = raw.slice('* Unmerged path '.length)
+      current = {
+        path: listed !== '' ? listed : null,
+        added: false,
+        deleted: false,
+        binary: false,
+        newBlob: null,
+        oldPath: null,
+        addedLines: [],
+        incomplete: 'unmerged-path',
+        inHeader: false,
+        ...(detail ? { hunks: [], lines: [] } : {}),
+      }
+      sections.push(current)
       continue
     }
-    const hunk = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/)
+    if (!current) continue
+    if (raw.startsWith('\\')) continue
+    const hunk = raw.match(HUNK_HEADER)
     if (hunk) {
-      lineNumber = Number(hunk[1])
+      current.inHeader = false
+      if (detail) current.hunks.push({ added: [], removed: [] })
+      pendingRemoved = hunk[1] === undefined ? 1 : Number(hunk[1])
+      lineNumber = Number(hunk[2])
+      pendingAdded = hunk[3] === undefined ? 1 : Number(hunk[3])
+      continue
+    }
+    if (raw.startsWith('Binary files ') && raw.endsWith(' differ')) {
+      current.inHeader = false
+      current.binary = true
       continue
     }
-    if (/^\+(?!\+)/.test(raw)) {
-      current.addedLines.push({ number: lineNumber, text: raw.slice(1) })
-      lineNumber += 1
-    } else if (/^-(?!-)/.test(raw)) {
-      // removed lines do not advance the new-file line counter
-    } else if (raw.startsWith(' ')) {
-      lineNumber += 1
+    if (!current.inHeader) {
+      if (raw !== '') current.incomplete ??= 'unexpected-line-outside-a-hunk'
+      continue
+    }
+    const index = raw.match(INDEX_LINE)
+    if (index) {
+      current.newBlob = ZERO_SHA_RE.test(index[2]) ? null : index[2]
+    } else if (raw.startsWith('new file mode ')) current.added = true
+    else if (raw.startsWith('deleted file mode ')) current.deleted = true
+    else if (raw.startsWith('rename from ') || raw.startsWith('copy from ')) {
+      const source = raw.slice(raw.indexOf(' from ') + 6)
+      const named = source.startsWith('"') ? readQuotedToken(source, 0) : { value: source, end: source.length }
+      if (named && named.end === source.length && named.value !== '') current.oldPath = named.value
+      else current.incomplete ??= 'unreadable-rename-source'
+    } else if (raw.startsWith('rename to ') || raw.startsWith('copy to ')) {
+      const target = raw.slice(raw.indexOf(' to ') + 4)
+      const named = target.startsWith('"') ? readQuotedToken(target, 0) : { value: target, end: target.length }
+      if (named && named.end === target.length && named.value !== '') current.path = named.value
+      else current.incomplete ??= 'unreadable-rename-target'
+    } else if (raw.startsWith('+++ ')) {
+      const target = raw.slice(4)
+      if (target !== '/dev/null' && current.path === null) {
+        const named = prefixedPath(target, 'b/')
+        if (named !== null && named !== '') current.path = named
+      }
     }
   }
-  return files.filter((file) => file.path)
+  if (pendingAdded > 0 || pendingRemoved > 0) current.incomplete = 'hunk-shorter-than-its-header'
+  for (const section of sections) {
+    delete section.inHeader
+    if (section.path === null) section.incomplete ??= 'unreadable-file-path'
+  }
+  return sections
+}
+
+/** Parse `git diff` output into added files and added lines with line numbers. */
+export function parseAddedContent(diff) {
+  return addedFilesFrom(parseDiffSections(diff))
 }
 
 /** Ref updates arrive on the pre-push hook's stdin as `<localRef> <localSha> <remoteRef> <remoteSha>`. */
@@ -256,12 +464,16 @@ export function parsePushRefInput(text) {
 export function gitOutputResult(repoRoot, args, {
   encoding = 'utf8',
   gitExecutable = 'git',
+  indexFile = null,
   maxBuffer = DIFF_RESULT_MAX_BYTES,
   runner = spawnSync,
 } = {}) {
   let result
+  // A hook names the index being committed (`git commit -a` writes a temporary
+  // one); every other variable from the caller's Git environment is dropped.
+  const env = indexFile ? { ...sanitizedGitEnvironment(), GIT_INDEX_FILE: indexFile } : sanitizedGitEnvironment()
   try {
-    result = runner(gitExecutable, ['-C', repoRoot, ...args], { encoding, maxBuffer, env: sanitizedGitEnvironment() })
+    result = runner(gitExecutable, ['-C', repoRoot, ...args], { encoding, maxBuffer, env })
   } catch (error) {
     return { ok: false, code: 'git-command-failed', error: error instanceof Error ? error.message : String(error), stdout: null }
   }
@@ -279,25 +491,34 @@ export function gitOutputResult(repoRoot, args, {
   return { ok: true, stdout, bytes }
 }
 
-export function pushRangeBase(repoRoot, remoteSha) {
+/** The empty tree in this repository's object format (SHA-1 or SHA-256). */
+export function emptyTreeFor(repoRoot, { runner = spawnSync } = {}) {
+  const result = gitOutputResult(repoRoot, ['rev-parse', '--show-object-format'], { maxBuffer: 1024, runner })
+  return (result.ok && EMPTY_TREES[result.stdout.trim()]) || EMPTY_TREE
+}
+
+export function pushRangeBase(repoRoot, remoteSha, { runner = spawnSync } = {}) {
   // A new branch has no remote counterpart, so everything it carries is new:
   // diff against the empty tree rather than silently scanning nothing.
-  if (!remoteSha || ZERO_SHA_RE.test(remoteSha)) return EMPTY_TREE
-  const result = spawnSync('git', ['-C', repoRoot, 'rev-parse', '--verify', '--quiet', `${remoteSha}^{commit}`], {
-    encoding: 'utf8',
-    maxBuffer: 1024 * 1024,
-  })
-  return result.status === 0 ? remoteSha : EMPTY_TREE
+  if (!remoteSha || ZERO_SHA_RE.test(remoteSha)) return emptyTreeFor(repoRoot, { runner })
+  const result = gitOutputResult(repoRoot, ['rev-parse', '--verify', '--quiet', `${remoteSha}^{commit}`], { maxBuffer: 1024 * 1024, runner })
+  return result.ok ? remoteSha : emptyTreeFor(repoRoot, { runner })
 }
 
+export const canonicalDiffArgs = (revisions, extra = []) => ['diff', ...CANONICAL_DIFF_FLAGS, '--unified=0', ...extra, ...revisions]
+// The content scan judges added lines only, so a deleted file's removed lines
+// would just spend the output limit. The semantic review reads removed lines
+// and keeps the plain form above.
+const contentDiffArgs = (revisions, extra = []) => canonicalDiffArgs(revisions, ['--irreversible-delete', ...extra])
+
 export function diffForPushRange(repoRoot, { localSha, remoteSha }, options = {}) {
-  const base = pushRangeBase(repoRoot, remoteSha)
-  const result = gitOutputResult(repoRoot, ['diff', '--unified=0', base, localSha], options)
+  const base = pushRangeBase(repoRoot, remoteSha, { runner: options.runner })
+  const result = gitOutputResult(repoRoot, contentDiffArgs([base, localSha]), options)
   return result.ok ? { ...result, base, diff: result.stdout } : { ...result, base, diff: null }
 }
 
 export function stagedDiff(repoRoot, options = {}) {
-  const result = gitOutputResult(repoRoot, ['diff', '--cached', '--unified=0'], options)
+  const result = gitOutputResult(repoRoot, contentDiffArgs(['--cached']), options)
   return result.ok ? { ...result, diff: result.stdout } : { ...result, diff: null }
 }
 
@@ -313,20 +534,21 @@ function incompleteDiagnostic({ repo, path: filePath = null, message, details =
   }
 }
 
-function binaryPathsFromDiff(diff) {
-  const paths = new Set()
-  let current = null
-  for (const line of String(diff ?? '').split('\n')) {
-    if (line.startsWith('diff --git ')) {
-      const header = line.match(/^diff --git a\/(.*) b\/(.*)$/)
-      current = header ? normalizeRelPath(header[2]) : null
-      continue
-    }
-    if (current && (line.startsWith('Binary files ') || line === 'GIT binary patch')) paths.add(current)
-  }
-  return [...paths]
+function unreadableSectionDiagnostics(sections, repo) {
+  return sections
+    .filter((section) => section.incomplete)
+    .map((section) => incompleteDiagnostic({
+      repo,
+      path: section.path,
+      message: 'a changed file could not be read from the diff, so its content was not scanned',
+      details: { reason: section.incomplete },
+    }))
 }
 
+const addedFilesFrom = (sections) => sections
+  .filter((section) => section.path !== null)
+  .map(({ path: filePath, added, addedLines }) => ({ path: filePath, added, addedLines }))
+
 function isBinaryBuffer(buffer) {
   if (buffer.subarray(0, Math.min(buffer.length, 8192)).includes(0)) return true
   try {
@@ -338,7 +560,6 @@ function isBinaryBuffer(buffer) {
 }
 
 function scanBinaryBuffer({ buffer, filePath, rules, exceptions, repo }) {
-  if (!isBinaryBuffer(buffer)) return []
   const text = buffer.toString('latin1')
   const findings = []
   for (const rule of rules) {
@@ -359,13 +580,100 @@ function scanBinaryBuffer({ buffer, filePath, rules, exceptions, repo }) {
   return findings
 }
 
-function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo, gitExecutable, gitRunner }) {
+const DECLARED_TEXT_BATCH = 200
+// A new file's diff can be twice its size (a "+" before every short line), so a
+// batch holds at most half the diff limit in blob bytes.
+const DECLARED_TEXT_BATCH_BYTES = DIFF_RESULT_MAX_BYTES / 2
+
+/**
+ * Git reports a file as binary when its attributes say so, whatever it holds
+ * (for example `*.cfg binary` in .gitattributes, which can arrive with the tree),
+ * or when the content it replaces was binary.
+ * Such text is judged like any other text: by its added lines, taken from a
+ * `--text` diff of just those paths and their rename sources. Narrowing the
+ * paths can change how Git pairs renames and copies, so a file's lines are used
+ * only when it is paired exactly as in the main diff; otherwise, or when a batch
+ * cannot be read, the file is read again on its own. Pathspecs are taken
+ * literally: core.precomposeUnicode is off for this call, because it would
+ * rewrite a decomposed name on the command line and match nothing. Returns, per
+ * path, `{ addedLines }` or `{ cause }` naming why the text was not read.
+ */
+function declaredBinaryTextLines({ repoRoot, revisions, entries, changedPaths = [], gitExecutable, gitRunner, indexFile = null }) {
+  const outcomes = new Map()
+  const read = (group) => {
+    const paths = [...new Set(group.flatMap(({ section }) => [section.path, section.oldPath].filter((value) => value && value !== '')))]
+    // A literal pathspec also matches a directory of that name, so a file that
+    // replaced a directory would bring the directory's changed files in as
+    // rename candidates and as output. Only changed entries can appear in a
+    // diff. Under a read path with nothing else read inside, one subtree
+    // exclusion covers them all; under one that holds another read path, the
+    // changed entries not read are excluded one by one. Usually there are none.
+    const reading = new Set(paths)
+    const excluded = new Set()
+    for (const read of paths) {
+      const under = changedPaths.filter((value) => value.startsWith(`${read}/`))
+      if (under.length === 0) continue
+      if (!paths.some((other) => other.startsWith(`${read}/`))) excluded.add(`${read}/`)
+      else for (const value of under) if (!reading.has(value)) excluded.add(value)
+    }
+    const result = gitOutputResult(repoRoot, [
+      '-c', 'core.precomposeUnicode=false',
+      ...contentDiffArgs(revisions, ['--text']),
+      '--',
+      ...paths.map((value) => `:(literal)${value}`),
+      ...[...excluded].map((value) => `:(exclude,literal)${value}`),
+    ], { gitExecutable, indexFile, runner: gitRunner })
+    const parsed = result.ok ? parseDiffSections(result.stdout) : []
+    for (const { section } of group) {
+      const matches = parsed.filter((candidate) => candidate.path === section.path && !candidate.deleted)
+      let cause = null
+      if (!result.ok) cause = result.code
+      else if (matches.length === 0) cause = 'missing-from-text-diff'
+      else if (matches.some((candidate) => candidate.oldPath !== section.oldPath)) cause = 'paired-differently-from-main-diff'
+      else cause = matches.find((candidate) => candidate.incomplete)?.incomplete ?? (matches.some((candidate) => candidate.binary) ? 'binary-in-text-diff' : null)
+      outcomes.set(section.path, cause ? { cause } : { addedLines: matches.flatMap((candidate) => candidate.addedLines) })
+    }
+  }
+  const groups = []
+  let group = []
+  let bytes = 0
+  for (const entry of entries) {
+    if (group.length > 0 && (group.length >= DECLARED_TEXT_BATCH || bytes + entry.bytes > DECLARED_TEXT_BATCH_BYTES)) {
+      groups.push(group)
+      group = []
+      bytes = 0
+    }
+    group.push(entry)
+    bytes += entry.bytes
+  }
+  if (group.length > 0) groups.push(group)
+  for (const batch of groups) {
+    read(batch)
+    if (batch.length === 1) continue
+    for (const entry of batch) if (outcomes.get(entry.section.path).cause) read([entry])
+  }
+  return outcomes
+}
+
+function readBinaryChanges({ repoRoot, revisions, sections, rules, exceptions, repo, gitExecutable, gitRunner, indexFile = null }) {
   const findings = []
   const diagnostics = []
   let totalBytes = 0
-  for (const filePath of binaryPathsFromDiff(diff)) {
-    const spec = revision === ':' ? `:${filePath}` : `${revision}:${filePath}`
-    const result = gitOutputResult(repoRoot, ['show', spec], {
+  const blobs = []
+  const seen = new Set()
+  const declaredText = []
+  // A deleted path is absent from the revision being scanned, so there is nothing
+  // to read: the blob it had is already in history and is not being introduced.
+  for (const section of sections) {
+    if (!section.binary || section.deleted || section.path === null || seen.has(section.path)) continue
+    seen.add(section.path)
+    const filePath = section.path
+    if (!section.newBlob) {
+      diagnostics.push(incompleteDiagnostic({ repo, path: filePath, message: 'binary content could not be identified in the diff', details: { reason: 'missing-blob-id' } }))
+      continue
+    }
+    // Read by object id: a path can be misread (":0:name" names an index stage).
+    const result = gitOutputResult(repoRoot, ['cat-file', 'blob', section.newBlob], {
       encoding: 'buffer',
       gitExecutable,
       maxBuffer: BINARY_FILE_MAX_BYTES + 1,
@@ -390,6 +698,7 @@ function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo,
       continue
     }
     totalBytes += result.bytes
+    blobs.push({ id: section.newBlob, bytes: result.bytes })
     if (totalBytes > BINARY_AGGREGATE_MAX_BYTES) {
       diagnostics.push(incompleteDiagnostic({
         repo,
@@ -399,9 +708,33 @@ function readBinaryChanges({ repoRoot, revision, diff, rules, exceptions, repo,
       }))
       break
     }
-    findings.push(...scanBinaryBuffer({ buffer: result.stdout, filePath, rules, exceptions, repo }))
+    if (isBinaryBuffer(result.stdout)) {
+      findings.push(...scanBinaryBuffer({ buffer: result.stdout, filePath, rules, exceptions, repo }))
+      continue
+    }
+    declaredText.push({ section, bytes: result.bytes })
+  }
+  if (declaredText.length > 0) {
+    const changedPaths = [...new Set(sections.flatMap((section) => [section.path, section.oldPath]).filter((value) => value && value !== ''))]
+    const outcomes = declaredBinaryTextLines({ repoRoot, revisions, entries: declaredText, changedPaths, gitExecutable, gitRunner, indexFile })
+    const contentRules = rules.filter((rule) => (rule.kind ?? 'content') === 'content')
+    for (const { section } of declaredText) {
+      const { addedLines, cause } = outcomes.get(section.path)
+      if (cause) {
+        diagnostics.push(incompleteDiagnostic({
+          repo,
+          path: section.path,
+          message: cause === 'git-output-limit-exceeded'
+            ? `text that Git reports as binary has a diff over the ${DIFF_RESULT_MAX_BYTES}-byte limit, so its content was not scanned`
+            : 'text that Git reports as binary could not be read as text, so its content was not scanned',
+          details: { reason: 'declared-binary-text-unreadable', cause },
+        }))
+        continue
+      }
+      findings.push(...scanAddedContent({ files: [{ path: section.path, added: false, addedLines }], rules: contentRules, exceptions, repo }))
+    }
   }
-  return { findings, diagnostics, bytes: totalBytes }
+  return { findings, diagnostics, bytes: totalBytes, blobs }
 }
 
 export function scanStagedRepository({
@@ -411,8 +744,9 @@ export function scanStagedRepository({
   repo = null,
   gitExecutable = 'git',
   gitRunner = spawnSync,
+  indexFile = null,
 } = {}) {
-  const acquired = stagedDiff(repoRoot, { gitExecutable, runner: gitRunner })
+  const acquired = stagedDiff(repoRoot, { gitExecutable, indexFile, runner: gitRunner })
   if (!acquired.ok) {
     return {
       findings: [],
@@ -420,38 +754,169 @@ export function scanStagedRepository({
       bytes: 0,
     }
   }
-  const files = parseAddedContent(acquired.diff)
-  const binary = readBinaryChanges({ repoRoot, revision: ':', diff: acquired.diff, rules, exceptions, repo, gitExecutable, gitRunner })
+  const sections = parseDiffSections(acquired.diff)
+  const binary = readBinaryChanges({ repoRoot, revisions: ['--cached'], sections, rules, exceptions, repo, gitExecutable, gitRunner, indexFile })
   return {
-    findings: [...scanAddedContent({ files, rules, exceptions, repo }), ...binary.findings],
-    diagnostics: binary.diagnostics,
+    findings: [...scanAddedContent({ files: addedFilesFrom(sections), rules, exceptions, repo }), ...binary.findings],
+    diagnostics: [...unreadableSectionDiagnostics(sections, repo), ...binary.diagnostics],
     bytes: acquired.bytes + binary.bytes,
   }
 }
 
+function scanRevisionRange({ repoRoot, base, tip, rules, exceptions, repo, gitRunner }) {
+  const acquired = gitOutputResult(repoRoot, contentDiffArgs([base, tip]), { runner: gitRunner })
+  if (!acquired.ok) return { acquired, keyed: [], diagnostics: [], bytes: 0, blobs: [] }
+  const sections = parseDiffSections(acquired.stdout)
+  const binary = readBinaryChanges({ repoRoot, revisions: [base, tip], sections, rules, exceptions, repo, gitRunner })
+  const findings = [...scanAddedContent({ files: addedFilesFrom(sections), rules, exceptions, repo }), ...binary.findings]
+  return {
+    acquired,
+    keyed: findings.map((item) => [findingKey(item), item]),
+    diagnostics: [...unreadableSectionDiagnostics(sections, repo), ...binary.diagnostics],
+    bytes: acquired.bytes + binary.bytes,
+    blobs: binary.blobs,
+  }
+}
+
+// What a finding reports: its rule, path and the digest of its line (binary
+// content has no line), so the same content is recognised in any diff.
+function findingKey(finding) {
+  return [finding.rule, finding.path, finding.lineDigest ?? 'binary'].join('\0')
+}
+
+/**
+ * What one commit adds. A merge adds only what is new against every parent:
+ * a side parent's own commits are judged where they were made, and content the
+ * remote already holds is not judged again. A finding is dropped only when a
+ * fully read diff against another parent shows that parent already had it, and
+ * one fully read parent diff covers everything new against all parents.
+ */
+function scanCommit({ repoRoot, commit, parents, empty, rules, exceptions, repo, gitRunner }) {
+  if (parents.length <= 1) return scanRevisionRange({ repoRoot, base: parents[0] ?? empty, tip: commit, rules, exceptions, repo, gitRunner })
+  const read = parents
+    .map((parent) => scanRevisionRange({ repoRoot, base: parent, tip: commit, rules, exceptions, repo, gitRunner }))
+    .filter((scan) => scan.acquired.ok)
+  if (read.length === 0) return { acquired: { ok: false, code: 'merge-unreadable' }, keyed: [], diagnostics: [], bytes: 0, blobs: [] }
+  const complete = read.filter((scan) => scan.diagnostics.length === 0)
+  // Any complete parent diff yields the same findings; the smallest is the one
+  // that does not re-read what the other parent already published.
+  const reference = complete.length > 0 ? complete.reduce((small, scan) => (scan.bytes < small.bytes ? scan : small)) : read[0]
+  const keyed = reference.keyed.filter(([key]) => complete.every((scan) => scan === reference || scan.keyed.some(([other]) => other === key)))
+  const diagnostics = complete.length > 0 ? [] : read.flatMap((scan) => scan.diagnostics)
+  // Evidence counts once, as the diff the commit is judged by.
+  return { acquired: reference.acquired, keyed, diagnostics, bytes: reference.bytes, blobs: reference.blobs }
+}
+
+const PLAIN_REMOTE_NAME = /^[A-Za-z0-9][A-Za-z0-9._/-]*$/
+
+/**
+ * Which tracking refs already hold what this push carries. The installed hook
+ * passes the remote Git names, which is a configured remote or a URL; a URL is
+ * matched to the remote configured with it. Only that remote's tracking refs
+ * exclude commits, so history held only by another remote is judged on its way
+ * here. A URL no remote is configured with excludes nothing but the remote's
+ * own commit. With no remote named (a hook installed before this), every
+ * remote's tracking refs exclude, as before.
+ */
+function remoteScope(repoRoot, remote, runner) {
+  if (typeof remote !== 'string' || remote === '') return { args: ['--remotes'], label: 'no remote holds' }
+  const configured = gitOutputResult(repoRoot, ['config', '--get-regexp', '^remote\\..*\\.url$'], { maxBuffer: 1024 * 1024, runner })
+  const remotes = configured.ok
+    ? configured.stdout.split('\n').filter(Boolean).map((line) => {
+      const space = line.indexOf(' ')
+      return { name: line.slice('remote.'.length, space).replace(/\.url$/, ''), url: line.slice(space + 1) }
+    })
+    : []
+  const named = remotes.find((item) => item.name === remote) ?? remotes.find((item) => item.url === remote)
+  if (named && PLAIN_REMOTE_NAME.test(named.name)) {
+    // `--remotes=origin` would also take a remote named `origin/x`; leave those out.
+    const nested = remotes.filter((item) => item.name.startsWith(`${named.name}/`)).map((item) => `--exclude=${item.name}/*`)
+    return { args: [...nested, `--remotes=${named.name}`], label: `${named.name} does not hold` }
+  }
+  return { args: [], label: `${remote} does not hold` }
+}
+
 export function scanPushUpdate({
   repoRoot,
   update,
   rules = DEFAULT_CONTENT_RULES,
   exceptions = [],
   repo = null,
+  remote = null,
   gitRunner = spawnSync,
+  maxCommits = PUSH_COMMIT_SCAN_MAX,
+  maxBytes = CHECK_AGGREGATE_MAX_BYTES,
 } = {}) {
-  const acquired = diffForPushRange(repoRoot, update, { runner: gitRunner })
-  if (!acquired.ok) {
+  const base = pushRangeBase(repoRoot, update.remoteSha, { runner: gitRunner })
+  const net = scanRevisionRange({ repoRoot, base, tip: update.localSha, rules, exceptions, repo, gitRunner })
+  if (!net.acquired.ok) {
     return {
       findings: [],
-      diagnostics: [incompleteDiagnostic({ repo, message: 'push evidence could not be acquired', details: { reason: acquired.code } })],
+      diagnostics: [incompleteDiagnostic({ repo, message: 'push evidence could not be acquired', details: { reason: net.acquired.code } })],
       bytes: 0,
     }
   }
-  const files = parseAddedContent(acquired.diff)
-  const binary = readBinaryChanges({ repoRoot, revision: update.localSha, diff: acquired.diff, rules, exceptions, repo })
-  return {
-    findings: [...scanAddedContent({ files, rules, exceptions, repo }), ...binary.findings],
-    diagnostics: binary.diagnostics,
-    bytes: acquired.bytes + binary.bytes,
+  const reported = new Map(net.keyed)
+  const findings = net.keyed.map(([, item]) => item)
+  const diagnostics = [...net.diagnostics]
+  // Every path is judged wherever it appears, but each blob counts once toward
+  // the evidence budget, however many diffs read it.
+  const counted = new Set()
+  const evidence = (scan) => scan.bytes - scan.blobs.reduce((repeat, blob) => {
+    if (counted.has(blob.id)) return repeat + blob.bytes
+    counted.add(blob.id)
+    return repeat
+  }, 0)
+  let bytes = evidence(net)
+  const scope = remoteScope(repoRoot, remote, gitRunner)
+  // Parents before children, so a commit is judged before a merge that brings it in.
+  const listed = gitOutputResult(repoRoot, ['rev-list', '--topo-order', '--reverse', '--parents', `--max-count=${maxCommits + 1}`, update.localSha, '--not', ...(base === update.remoteSha ? [base] : []), ...scope.args], { runner: gitRunner })
+  if (!listed.ok) {
+    diagnostics.push(incompleteDiagnostic({ repo, message: 'the commits in this push could not be listed', details: { reason: listed.code } }))
+    return { findings, diagnostics, bytes }
+  }
+  const commits = listed.stdout.split('\n').filter(Boolean).map((line) => line.split(' '))
+  if (commits.length > maxCommits) {
+    diagnostics.push(incompleteDiagnostic({
+      repo,
+      message: `this push carries more than ${maxCommits} commits that ${scope.label}, more than are judged one by one; push it in smaller parts, an earlier commit first (git push <remote> <commit>:<ref>)`,
+      details: { reason: 'push-range-too-long', limit: maxCommits },
+    }))
+    return { findings, diagnostics, bytes }
+  }
+  // One commit straight on the remote's tip is the endpoint change already judged.
+  if (commits.length === 1 && commits[0].length === 2 && commits[0][1] === base) return { findings, diagnostics, bytes }
+  const empty = emptyTreeFor(repoRoot, { runner: gitRunner })
+  for (const [commit, ...parents] of commits) {
+    const step = scanCommit({ repoRoot, commit, parents, empty, rules, exceptions, repo, gitRunner })
+    const short = commit.slice(0, 12)
+    if (!step.acquired.ok) {
+      diagnostics.push(incompleteDiagnostic({ repo, message: `commit ${short} could not be read`, details: { reason: step.acquired.code, commit } }))
+      continue
+    }
+    bytes += evidence(step)
+    for (const [key, item] of step.keyed) {
+      const retained = reported.get(key)
+      if (retained) {
+        // Already reported: record where else it was published.
+        if (!retained.commit) retained.commits = [...(retained.commits ?? []), commit]
+        continue
+      }
+      const placed = { ...item, commit, message: `${item.message} (in commit ${short})` }
+      reported.set(key, placed)
+      findings.push(placed)
+    }
+    diagnostics.push(...step.diagnostics.map((item) => ({ ...item, message: `${item.message} (in commit ${short})`, details: { ...item.details, commit } })))
+    if (bytes > maxBytes) {
+      diagnostics.push(incompleteDiagnostic({
+        repo,
+        message: `push evidence exceeds the ${maxBytes}-byte aggregate limit; push it in smaller parts`,
+        details: { reason: 'push-evidence-too-large', limitBytes: maxBytes, commit },
+      }))
+      break
+    }
   }
+  return { findings, diagnostics, bytes }
 }
 
 /**