rvlib-shipkit 0.35.8 → 0.37.0

package/src/fleet/scan-fleet.ts

@@ -0,0 +1,142 @@
+// The fleet: every repo on this disk that depends on the toolkit, and how far
+// behind each one is.
+//
+// Why a scan and not a registry: `local-projects.md` only holds repos whose
+// `docsBase` points at a wiki, which is 4 of the 10 that actually install the
+// libs. A repo that never reported is exactly the repo most likely to be
+// stale, so a registry is the wrong source for this question.
+//
+// This module DISCOVERS and REPORTS. It never updates: rule SK005 owns the
+// update, with the lease, the dirty-tree guard and the frozen guard that took
+// three bugs to get right. `--update` runs each repo's own `shipkit check`,
+// so the fix travels through that one code path.
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs'
+import { join } from 'path'
+
+export type Pkg = { name?: string; version?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
+
+export type FleetDep = {
+    name: string
+    /** the range in package.json, or `link:…` for a source-linked dep */
+    pin: string
+    /** what node_modules actually carries, null when nothing is installed */
+    installed: string | null
+    /** npm latest, null when the registry was not consulted or not reachable */
+    latest: string | null
+}
+
+/** a jump that changes the MAJOR, which is a porting job rather than a bump.
+ *
+ *  Deliberately NOT the semver rule. On a `0.x` package npm treats every
+ *  minor as breaking, and by that rule every repo here is breaking, including
+ *  the `0.24 → 0.35` shipkit jumps that rule SK005 already performs by itself
+ *  every day. A flag that fires on everything is a flag nobody reads. What
+ *  survives is the case a human has to own: `rvlib-pb-mobx 0.2.0 → 2.0.0`. */
+export function isBreaking(installed: string, latest: string): boolean {
+    const major = (v: string) => Number(v.split('-')[0]!.split('.')[0]) || 0
+    return major(installed) !== major(latest)
+}
+
+export type FleetRepo = {
+    name: string
+    dir: string
+    deps: FleetDep[]
+    /** a repo pointing at a checkout rather than a published version. Never
+     *  updated: the source IS the version, and that is a deliberate choice. */
+    linked: boolean
+    /** whether this repo can run the update itself (it has a shipkit binary) */
+    hasShipkit: boolean
+    behind: FleetDep[]
+    /** the subset of `behind` whose jump crosses a breaking boundary */
+    breaking: FleetDep[]
+}
+
+const readPkg = (dir: string): Pkg | null => {
+    const p = join(dir, 'package.json')
+    if (!existsSync(p)) return null
+    try {
+        return JSON.parse(readFileSync(p, 'utf8')) as Pkg
+    } catch {
+        return null
+    }
+}
+
+const installedVersion = (dir: string, name: string): string | null => readPkg(join(dir, 'node_modules', name))?.version ?? null
+
+/** semver-ish compare, enough to answer "is this one behind that one". A
+ *  prerelease tag sorts before its release, which is the safe direction: it
+ *  reports behind rather than pretending parity. */
+export function isBehind(installed: string, latest: string): boolean {
+    const part = (v: string) => v.split('-')[0]!.split('.').map((n) => Number(n) || 0)
+    const [a, b] = [part(installed), part(latest)]
+    for (let i = 0; i < 3; i++) {
+        if ((a[i] ?? 0) < (b[i] ?? 0)) return true
+        if ((a[i] ?? 0) > (b[i] ?? 0)) return false
+    }
+    return installed.includes('-') && !latest.includes('-')
+}
+
+export function scanFleet(root: string, o: { prefix?: string } = {}): FleetRepo[] {
+    const prefix = o.prefix ?? 'rvlib-'
+    const out: FleetRepo[] = []
+    let entries: string[]
+    try {
+        entries = readdirSync(root)
+    } catch {
+        return out
+    }
+    for (const e of entries.sort()) {
+        if (e.startsWith('.')) continue
+        const dir = join(root, e)
+        try {
+            if (!statSync(dir).isDirectory()) continue
+        } catch {
+            continue
+        }
+        const pkg = readPkg(dir)
+        if (pkg == null) continue
+        const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }
+        const names = Object.keys(all).filter((n) => n.startsWith(prefix))
+        if (names.length === 0) continue
+        const deps: FleetDep[] = names.sort().map((name) => ({ name, pin: all[name]!, installed: installedVersion(dir, name), latest: null }))
+        out.push({
+            name: e,
+            dir,
+            deps,
+            linked: deps.some((d) => d.pin.startsWith('link:') || d.pin.startsWith('file:')),
+            hasShipkit: existsSync(join(dir, 'node_modules', 'rvlib-shipkit', 'src', 'cli.ts')),
+            behind: [],
+            breaking: [],
+        })
+    }
+    return out
+}
+
+/** npm latest per PACKAGE, fetched once and shared across every repo that
+ *  depends on it. Ten repos on one lib is one request, not ten. */
+export async function resolveLatest(repos: FleetRepo[], fetchLatest: (name: string) => Promise<string | null>): Promise<Map<string, string | null>> {
+    const names = new Set<string>()
+    for (const r of repos) for (const d of r.deps) if (!d.pin.startsWith('link:') && !d.pin.startsWith('file:')) names.add(d.name)
+    const latest = new Map<string, string | null>()
+    await Promise.all(
+        [...names].map(async (n) => {
+            try {
+                latest.set(n, await fetchLatest(n))
+            } catch {
+                latest.set(n, null)
+            }
+        }),
+    )
+    for (const r of repos) {
+        for (const d of r.deps) d.latest = latest.get(d.name) ?? null
+        r.behind = r.deps.filter((d) => d.installed != null && d.latest != null && isBehind(d.installed, d.latest))
+        r.breaking = r.behind.filter((d) => isBreaking(d.installed!, d.latest!))
+    }
+    return latest
+}
+
+export async function npmLatest(name: string): Promise<string | null> {
+    const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(10_000) })
+    if (!res.ok) return null
+    return ((await res.json()) as Pkg).version ?? null
+}

package/src/git-bootstrap.ts

@@ -101,7 +101,7 @@ const samePath = (a: string, b: string): boolean => {
     }
 }
 
-type RepoView = { nameWithOwner?: string; isPrivate?: boolean; url?: string; sshUrl?: string }
+type RepoView = { nameWithOwner?: string; isPrivate?: boolean; sshUrl?: string }
 
 /** phase one: this dir IS a git work tree root. false means the caller must
  *  not publish anything (a subdirectory of another repo, or git refused), and
@@ -194,7 +194,7 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     const login = firstGhLine(user.out)
     if (!NAME_RE.test(login)) return void p(`WARN no remote wired: gh did not answer with a login (${login})`)
     const target = `${login}/${name}`
-    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,url,sshUrl']
+    const viewArgs = ['repo', 'view', target, '--json', 'nameWithOwner,isPrivate,sshUrl']
 
     let view = await gh(viewArgs)
     let created = false
@@ -217,9 +217,15 @@ export async function publishRepo(root: string, opts: PublishOpts = {}): Promise
     }
 
     const info = carveGhJson<RepoView>(view.out)
-    const proto = await gh(['config', 'get', 'git_protocol'])
-    const url = (firstGhLine(proto.out) === 'ssh' ? info?.sshUrl : info?.url) ?? info?.url ?? info?.sshUrl
-    if (url == null) return void p(`WARN no remote wired: gh answer unreadable (${firstGhLine(view.out)})`)
+    // ALWAYS the ssh url gh gave, never the https one and never `gh config
+    // get git_protocol`: an https origin re-asks for a credential on every
+    // push, and a machine answering `https` there wires a remote that reports
+    // success and fails at the first push. An answer carrying no sshUrl is
+    // unreadable, not an invitation to build one: this module knows no host,
+    // and a guessed `github.com` remote against an enterprise gh is the same
+    // silent failure one host over
+    const url = info?.sshUrl
+    if (url == null) return void p(`WARN no remote wired: gh answered without an ssh url (${firstGhLine(view.out)})`)
 
     const add = await git(['remote', 'add', 'origin', url])
     if (add.code !== 0) return void p(`WARN no remote wired: git remote add failed (${firstGhLine(add.out)})`)

package/src/hooks/leak-guard.ts

@@ -4,10 +4,23 @@
 //
 // the keyword file is deliberately untracked (a list of things to grep for
 // is itself private). absent file → loud skip, never a silent pass.
+//
+// a keyword matches as a SUBSTRING, which is what catches a private name
+// glued into a hostname or an identifier. The cost is a false positive a repo
+// cannot escape: a four letter row lands inside a dependency name or inside a
+// base64 integrity hash in a lockfile, and that lockfile is uncommittable
+// forever. A guard that cries wolf is a guard people answer with --no-verify,
+// which protects nothing. Two answers, in this order. `w:<word>` rows match on
+// word boundaries, which makes the PATTERN smarter rather than the guard
+// looser. An ALLOWLIST waives a known-good match in a named context, and every
+// waiver that fires is PRINTED with its reason, so a reader sees what was let
+// through and why.
+import { createHash } from 'crypto'
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { basename, join } from 'path'
 
-export type LeakHit = { where: string; pattern: string }
+export type LeakHit = { where: string; pattern: string; file?: string }
+export type LeakWaiver = LeakHit & { reason: string; source: string }
 
 /** what a hit REPORTS. The matched string is private by construction, and a
  *  gate that prints it verbatim puts it in a terminal, a CI log and any paste
@@ -15,16 +28,66 @@ export type LeakHit = { where: string; pattern: string }
 export const maskPattern = (p: string): string =>
     p.startsWith('re:') || p.length <= 6 ? p : `${p.slice(0, 3)}…${p.slice(-2)} (${p.length} chars)`
 
+/** a stable name for a pattern that does not CARRY it, so a tracked allowlist
+ *  points at a private keyword without becoming a copy of the private keyword
+ *  list. Printed beside every hit, which is how a waiver gets written without
+ *  anyone typing the word.
+ *
+ *  Honest scope: this stops the list being READ off a tracked file. It is no
+ *  defence against a targeted guess, because a short keyword has a small
+ *  search space and whoever already suspects the word can confirm it. */
+export const patternFingerprint = (pattern: string): string =>
+    'fp:' + createHash('sha256').update(pattern.toLowerCase()).digest('hex').slice(0, 12)
+
+/** one known-good match a repo (or this machine) waives.
+ *
+ *  `paths` alone waives every pattern in those files. `patterns` alone waives
+ *  those patterns everywhere. The PAIR is the shape to reach for: this
+ *  pattern, in these files, while the same pattern still blocks anywhere else.
+ *  `inHashes` narrows further, to a match that lands inside a content hash. */
+export type LeakAllowEntry = {
+    /** why this match is known good. Printed every time the waiver fires, so
+     *  a reader months later can judge it. Required. */
+    reason: string
+    /** staged paths this entry covers: a repo-relative path, a bare basename
+     *  ('bun.lock'), or a 'dir/' prefix. Absent = every target, the commit
+     *  message included. */
+    paths?: string[]
+    /** the patterns this entry waives, named by FINGERPRINT (`fp:` + 12 hex,
+     *  printed beside every hit). Absent = every pattern, on `paths` alone.
+     *  A TRACKED source (repo.config.ts) takes the fingerprint form only: a
+     *  literal there puts the private keyword into git. */
+    patterns?: string[]
+    /** waive only a match that falls inside a content hash (an npm `sha512-…`
+     *  integrity field, a 40+ char base64 run). The bytes of a content address
+     *  are arithmetic, not prose, so a keyword inside one is noise. The same
+     *  keyword on a normal line of the same file still blocks. */
+    inHashes?: boolean
+}
+
 export type LeakGuardResult =
     | { status: 'skipped'; reason: string }
-    | { status: 'clean'; patterns: number }
-    | { status: 'hit'; hits: LeakHit[]; patterns: number }
+    | { status: 'clean'; patterns: number; waived: LeakWaiver[]; notes: string[] }
+    | { status: 'hit'; hits: LeakHit[]; patterns: number; waived: LeakWaiver[]; notes: string[] }
+
+export type ParsedPatterns = {
+    substrings: string[]
+    words: { word: string; re: RegExp }[]
+    regexes: { row: string; re: RegExp }[]
+}
+
+const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 /** Parse the keyword file: blank lines and `#` comments dropped, `re:<pattern>`
- *  rows become case-insensitive regexes, everything else a case-insensitive
- *  substring. */
-export function parsePatterns(text: string): { substrings: string[]; regexes: { row: string; re: RegExp }[] } {
+ *  rows become case-insensitive regexes, `w:<word>` rows match on word
+ *  boundaries, everything else a case-insensitive substring.
+ *
+ *  A `w:` row REPORTS as the bare word, so its mask and its fingerprint are
+ *  the same with or without the prefix: adding the prefix to a row never
+ *  invalidates a waiver already written against it. */
+export function parsePatterns(text: string): ParsedPatterns {
     const substrings: string[] = []
+    const words: { word: string; re: RegExp }[] = []
     const regexes: { row: string; re: RegExp }[] = []
     for (const raw of text.split('\n')) {
         const row = raw.trim()
@@ -32,24 +95,134 @@ export function parsePatterns(text: string): { substrings: string[]; regexes: {
         if (row.startsWith('re:')) {
             try { regexes.push({ row, re: new RegExp(row.slice(3), 'i') }) }
             catch { /* a malformed row must not disable the whole guard */ }
+        } else if (row.startsWith('w:')) {
+            const word = row.slice(2).trim().toLowerCase()
+            // \b is ascii-only in JS, which lets an accented name match inside
+            // a longer accented word: the boundary is spelled in unicode
+            if (word !== '') words.push({ word, re: new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(word)}(?![\\p{L}\\p{N}_])`, 'giu') })
         } else substrings.push(row.toLowerCase())
     }
-    return { substrings, regexes }
+    return { substrings, words, regexes }
 }
 
-function scan(haystack: string, where: string, p: ReturnType<typeof parsePatterns>, hits: LeakHit[]): void {
-    const lower = haystack.toLowerCase()
-    for (const s of p.substrings) if (lower.includes(s)) hits.push({ where, pattern: s })
-    for (const r of p.regexes) if (r.re.test(haystack)) hits.push({ where, pattern: r.row })
+type Span = [start: number, end: number]
+
+// a substring row is matched by a case-insensitive REGEX rather than by
+// indexOf over a lowercased copy: one unicode character (İ) lowercases into
+// two, which slides every offset after it, and the offsets are what decide
+// whether a match sits inside a content hash. Compiled once per keyword.
+const subRe = new Map<string, RegExp>()
+const substringRegex = (s: string): RegExp => {
+    const hit = subRe.get(s)
+    if (hit != null) return hit
+    const re = new RegExp(escapeRegex(s), 'gi')
+    subRe.set(s, re)
+    return re
 }
 
-export type LeakGuardOpts = {
-    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
-    keywordFile?: string
-    /** extra text to scan (a commit message, a release note) */
-    text?: { label: string; content: string }[]
-    /** scan the staged diff + staged paths (default true) */
-    staged?: boolean
+/** every occurrence of every pattern, keyed by the id a hit reports. */
+function occurrences(haystack: string, p: ParsedPatterns): Map<string, Span[]> {
+    const found = new Map<string, Span[]>()
+    const push = (id: string, span: Span): void => {
+        const prev = found.get(id)
+        if (prev == null) found.set(id, [span])
+        else prev.push(span)
+    }
+    for (const s of p.substrings) for (const m of haystack.matchAll(substringRegex(s))) push(s, [m.index, m.index + m[0].length])
+    for (const w of p.words) for (const m of haystack.matchAll(w.re)) push(w.word, [m.index, m.index + m[0].length])
+    for (const r of p.regexes) {
+        const g = new RegExp(r.re.source, r.re.flags.includes('g') ? r.re.flags : r.re.flags + 'g')
+        for (const m of haystack.matchAll(g)) push(r.row, [m.index, m.index + m[0].length])
+    }
+    return found
+}
+
+// an npm/yarn integrity field, and any long base64 run. ONLY an entry that
+// asked for `inHashes` consults this: an api token is also a long base64 run,
+// so skipping these by default would be the guard going quiet on the exact
+// shape it exists to catch.
+const HASH_SPAN = /(?:sha\d{1,3}|md5)-[A-Za-z0-9+/=]{16,}|[A-Za-z0-9+/]{40,}={0,2}/gi
+
+const hashSpans = (text: string): Span[] => [...text.matchAll(HASH_SPAN)].map((m): Span => [m.index, m.index + m[0].length])
+
+const inside = (span: Span, spans: Span[]): boolean => spans.some(([a, b]) => span[0] >= a && span[1] <= b)
+
+/** a path selector: a repo-relative path, a bare basename, or a 'dir/' prefix. */
+function pathCovered(file: string | undefined, selectors: string[]): boolean {
+    if (file == null) return false
+    return selectors.some((s) => s === file || (s.endsWith('/') && file.startsWith(s)) || (!s.includes('/') && basename(file) === s))
+}
+
+export type LoadedAllow = LeakAllowEntry & { source: string }
+
+/** what the guard reads: one file's added lines, one staged path, or a text
+ *  the caller handed in (a commit message). */
+export type ScanTarget = { where: string; content: string; file?: string }
+
+/** the whole decision, with no git and no disk in it: which matches block,
+ *  which are waived, by whom, and why. */
+export function evaluateLeak(targets: ScanTarget[], p: ParsedPatterns, allow: LoadedAllow[]): { hits: LeakHit[]; waived: LeakWaiver[] } {
+    const hits: LeakHit[] = []
+    const waived: LeakWaiver[] = []
+    // one row per distinct (where, file, pattern): a keyword hit 40 times in
+    // one file is one finding
+    const seen = new Set<string>()
+    for (const t of targets) {
+        const found = occurrences(t.content, p)
+        if (found.size === 0) continue
+        let hashes: Span[] | null = null
+        for (const [id, spans] of found) {
+            const key = `${t.where} ${t.file ?? ''} ${id}`
+            if (seen.has(key)) continue
+            seen.add(key)
+            const fp = patternFingerprint(id)
+            const entry = allow.find((a) => {
+                if (a.paths != null && !pathCovered(t.file, a.paths)) return false
+                if (a.patterns != null && !a.patterns.some((x) => x === fp || x.toLowerCase() === id)) return false
+                if (a.inHashes === true) {
+                    hashes ??= hashSpans(t.content)
+                    if (!spans.every((s) => inside(s, hashes!))) return false
+                }
+                return true
+            })
+            if (entry == null) hits.push({ where: t.where, pattern: id, file: t.file })
+            else waived.push({ where: t.where, pattern: id, file: t.file, reason: entry.reason, source: entry.source })
+        }
+    }
+    return { hits, waived }
+}
+
+const ALLOW_KEYS = ['reason', 'paths', 'patterns', 'inHashes']
+const FINGERPRINT = /^fp:[0-9a-f]{12}$/
+
+/** why an entry cannot be used, or null. `tracked` = the source is committed
+ *  (repo.config.ts), where a literal pattern publishes the private word the
+ *  guard exists to keep out of git. */
+export function leakAllowProblem(entry: unknown, where: string, tracked: boolean): string | null {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) return `${where}: every entry is an object`
+    const e = entry as Record<string, unknown>
+    for (const k of Object.keys(e)) if (!ALLOW_KEYS.includes(k)) return `${where}: unknown key '${k}' (known: ${ALLOW_KEYS.join(', ')})`
+    if (typeof e['reason'] !== 'string' || e['reason'].trim() === '') return `${where}: needs a 'reason' — a waiver nobody can judge later is a hole`
+    if (e['paths'] == null && e['patterns'] == null)
+        return `${where}: needs 'paths' or 'patterns' — an entry with neither waives every pattern in every file, which is the guard switched off`
+    for (const k of ['paths', 'patterns'] as const) {
+        const v = e[k]
+        if (v == null) continue
+        if (!Array.isArray(v) || v.length === 0 || v.some((x) => typeof x !== 'string' || x.trim() === ''))
+            return `${where}: '${k}' is a non-empty array of non-empty strings`
+    }
+    if (e['inHashes'] != null && typeof e['inHashes'] !== 'boolean') return `${where}: 'inHashes' is a boolean`
+    if (tracked)
+        for (const x of (e['patterns'] as string[] | undefined) ?? [])
+            if (!FINGERPRINT.test(x))
+                return `${where}: '${x}' — a tracked allowlist names a pattern by FINGERPRINT (fp:…, printed beside every hit), never by value, or the private keyword lands in git`
+    return null
+}
+
+/** every problem in a declared allowlist. `defineRepo` throws on the first. */
+export function leakAllowProblems(entries: unknown, where: string, tracked: boolean): string[] {
+    if (!Array.isArray(entries)) return [`${where}: leakAllow is an array of entries`]
+    return entries.map((e, i) => leakAllowProblem(e, `${where}[${i}]`, tracked)).filter((x): x is string => x != null)
 }
 
 /** the machine-global list every repo's guard also reads: one private list
@@ -62,36 +235,138 @@ export function globalKeywordFile(): string | null {
     return existsSync(p) ? p : null
 }
 
+/** the machine-global allowlist, the twin of the keyword file. It is private,
+ *  so it may name a pattern by value as well as by fingerprint. */
+export function globalAllowFile(): string | null {
+    const home = process.env.HOME ?? ''
+    if (home === '') return null
+    const p = join(home, '.rv-private', 'leak-allow.json')
+    return existsSync(p) ? p : null
+}
+
+/** read an allowlist file (`LeakAllowEntry[]` as JSON). A file that will not
+ *  parse, or an entry that cannot be used, is a NOTE and never a failure: a
+ *  waiver that does not load leaves the guard stricter, never looser. */
+export function loadAllowFile(path: string, tracked: boolean): { entries: LoadedAllow[]; notes: string[] } {
+    let parsed: unknown
+    try { parsed = JSON.parse(readFileSync(path, 'utf8')) }
+    catch (e) { return { entries: [], notes: [`${path} is not readable JSON (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — its waivers are IGNORED`] } }
+    if (!Array.isArray(parsed)) return { entries: [], notes: [`${path} holds an array of allowlist entries — its waivers are IGNORED`] }
+    const entries: LoadedAllow[] = []
+    const notes: string[] = []
+    parsed.forEach((raw, i) => {
+        const problem = leakAllowProblem(raw, `${path}[${i}]`, tracked)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else entries.push({ ...(raw as LeakAllowEntry), source: `${basename(path)}[${i}]` })
+    })
+    return { entries, notes }
+}
+
+export type LeakGuardOpts = {
+    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
+    keywordFile?: string
+    /** extra text to scan (a commit message, a release note) */
+    text?: { label: string; content: string }[]
+    /** scan the staged diff + staged paths (default true) */
+    staged?: boolean
+    /** the repo's declared waivers (repo.config.ts hooks.leakAllow). Tracked,
+     *  so fingerprints only. */
+    allow?: LeakAllowEntry[]
+    /** override the machine-global allowlist path; null reads none */
+    allowFile?: string | null
+}
+
+/** git c-quotes a path that carries a space or a non-ascii byte. */
+function unquotePath(p: string): string {
+    if (!p.startsWith('"')) return p
+    try { return JSON.parse(p) as string } catch { return p.slice(1, -1) }
+}
+
+/** `@@ -old,n +new,m @@`, the only line that says how long a hunk body is. */
+const HUNK_HEADER = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/
+
+/** ADDED lines only, grouped by the file that receives them: what this commit
+ *  puts INTO the object store. Removed and context lines are already in
+ *  history, and a commit that DELETES private content must never be blocked by
+ *  that content. The grouping is what lets a waiver name a file.
+ *
+ *  A `+++ x` line is a file header only OUTSIDE a hunk body. Inside one it is
+ *  an added line whose own text starts with `++`, and reading it as a header
+ *  is a hole in both directions: `++ /dev/null` would drop every added line
+ *  after it in that file, and `++ b/bun.lock` would file them under a name a
+ *  waiver covers. So the hunk body is COUNTED, from the size its header
+ *  declares. A header this does not recognise (a combined `@@@` diff) opens an
+ *  unbounded body that only the next file closes, which is the safe direction:
+ *  content is still scanned, and no line inside it can name a file. */
+export function addedLinesByFile(diff: string): { file: string; content: string }[] {
+    const out: { file: string; content: string }[] = []
+    let current: { file: string; lines: string[] } | null = null
+    let oldLeft = 0
+    let newLeft = 0
+    const flush = (): void => {
+        if (current != null && current.lines.length > 0) out.push({ file: current.file, content: current.lines.join('\n') })
+        current = null
+    }
+    const add = (line: string): void => { if (current != null) current.lines.push(line.slice(1)) }
+    for (const line of diff.split('\n')) {
+        // a `diff --git ` at column 0 can never be diff CONTENT: a content line
+        // always carries its ' ', '+' or '-' prefix first
+        if (line.startsWith('diff --git ')) {
+            flush()
+            oldLeft = 0
+            newLeft = 0
+        } else if (oldLeft > 0 || newLeft > 0) {
+            if (line.startsWith('+')) { newLeft--; add(line) }
+            else if (line.startsWith('-')) oldLeft--
+            else if (!line.startsWith('\\')) { oldLeft--; newLeft-- } // '' counts for neither
+        } else if (line.startsWith('@@')) {
+            const h = HUNK_HEADER.exec(line)
+            oldLeft = h == null ? Infinity : h[1] == null ? 1 : Number(h[1])
+            newLeft = h == null ? Infinity : h[2] == null ? 1 : Number(h[2])
+        } else if (line.startsWith('+++ ')) {
+            flush()
+            const p = unquotePath(line.slice(4).trim())
+            current = p === '/dev/null' ? null : { file: p.startsWith('b/') ? p.slice(2) : p, lines: [] }
+        } else if (line.startsWith('+')) add(line) // a stray added line outside any hunk is still content
+    }
+    flush()
+    return out
+}
+
 export function runLeakGuard(root: string, o: LeakGuardOpts = {}): LeakGuardResult {
     const rel = o.keywordFile ?? '.rv-private/banned-keywords.txt'
     const file = join(root, rel)
     const sources = [existsSync(file) ? file : null, globalKeywordFile()].filter((f): f is string => f != null)
     if (sources.length === 0) return { status: 'skipped', reason: `${rel} not found and no ~/.rv-private/banned-keywords.txt — no keyword list, no leak guard` }
     const patterns = parsePatterns(sources.map((f) => readFileSync(f, 'utf8')).join('\n'))
-    const count = patterns.substrings.length + patterns.regexes.length
+    const count = patterns.substrings.length + patterns.words.length + patterns.regexes.length
     if (count === 0) return { status: 'skipped', reason: `keyword file(s) have no patterns (${sources.join(', ')})` }
 
-    const hits: LeakHit[] = []
+    const notes: string[] = []
+    const allow: LoadedAllow[] = []
+    ;(o.allow ?? []).forEach((e, i) => {
+        const problem = leakAllowProblem(e, `repo.config.ts hooks.leakAllow[${i}]`, true)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else allow.push({ ...e, source: `repo.config.ts hooks.leakAllow[${i}]` })
+    })
+    const globalAllow = o.allowFile === undefined ? globalAllowFile() : o.allowFile
+    if (globalAllow != null && existsSync(globalAllow)) {
+        const g = loadAllowFile(globalAllow, false)
+        allow.push(...g.entries)
+        notes.push(...g.notes)
+    }
+
+    const targets: ScanTarget[] = []
     if (o.staged !== false) {
-        // staged CONTENT (what lands in the object store) and staged PATHS
-        // (a filename can leak as loudly as a line of code)
         const diff = Bun.spawnSync(['git', 'diff', '--cached'], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
-        if (diff.exitCode === 0) {
-            // ADDED lines only: what this commit puts INTO the object store.
-            // removed/context lines are already in history, and a commit that
-            // deletes private content must never be blocked by that content
-            const added = diff.stdout.toString().split('\n')
-                .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
-                .join('\n')
-            scan(added, 'staged content', patterns, hits)
-        }
+        if (diff.exitCode === 0)
+            for (const f of addedLinesByFile(diff.stdout.toString())) targets.push({ where: 'staged content', file: f.file, content: f.content })
+        // a filename can leak as loudly as a line of code
         const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
-        if (names.exitCode === 0) scan(names.stdout.toString(), 'staged path', patterns, hits)
+        if (names.exitCode === 0) for (const n of names.stdout.toString().split('\n')) if (n.trim() !== '') targets.push({ where: 'staged path', file: n, content: n })
     }
-    for (const t of o.text ?? []) scan(t.content, t.label, patterns, hits)
+    for (const t of o.text ?? []) targets.push({ where: t.label, content: t.content })
 
-    // one row per distinct (where, pattern) — a keyword hit 40 times is one finding
-    const seen = new Set<string>()
-    const unique = hits.filter((h) => { const k = h.where + ' ' + h.pattern; if (seen.has(k)) return false; seen.add(k); return true })
-    return unique.length > 0 ? { status: 'hit', hits: unique, patterns: count } : { status: 'clean', patterns: count }
+    const { hits, waived } = evaluateLeak(targets, patterns, allow)
+    return hits.length > 0 ? { status: 'hit', hits, patterns: count, waived, notes } : { status: 'clean', patterns: count, waived, notes }
 }