rvlib-shipkit 1.9.0 → 2.0.0

package/src/core/waivers.ts

@@ -0,0 +1,125 @@
+// the in-file waiver grammar: a site a check reports can be waived where it
+// stands, in whatever comment the file type has, and only with a reason.
+//
+//   sk-disable-next-line <ID>[, <ID>…] -- <reason>   the line below it
+//   sk-disable-line <ID>[, <ID>…] -- <reason>        its own line
+//   sk-disable-file <ID>[, <ID>…] -- <reason>        every site of the file
+//
+// carriers: `<!-- … -->` in markdown and html (fenced and inline code left
+// out, so a page can show the grammar), `//` and `/* … */` in ts and js, `#`
+// in sh, yaml, toml and python, all of them in an unknown type. A directive
+// inside a string literal still counts: a test builds its samples at runtime.
+// core/check-ctx.ts applies them, through `c`, so the waiving file is read
+// into the check's key.
+
+/** the token a file must contain before it is parsed at all */
+export const DIRECTIVE_MARK = 'sk-disable-'
+
+export type DirectiveScope = 'next-line' | 'line' | 'file'
+
+export type Directive = {
+    scope: DirectiveScope
+    /** the check ids it names */
+    ids: string[]
+    /** null when the directive gave none, which waives nothing */
+    reason: string | null
+    /** 1-based line of the directive itself */
+    line: number
+}
+
+type Carrier = 'html' | 'slash' | 'block' | 'hash'
+
+const MARKDOWN = new Set(['md', 'mdx', 'markdown'])
+const HTML = new Set(['html', 'htm', 'xml', 'svg', 'vue'])
+const C_LIKE = new Set(['ts', 'tsx', 'mts', 'cts', 'js', 'jsx', 'mjs', 'cjs', 'css', 'scss', 'less', 'jsonc', 'json5', 'go', 'rs', 'swift', 'java', 'kt', 'c', 'h', 'cpp', 'zig'])
+const HASH = new Set(['sh', 'bash', 'zsh', 'fish', 'yaml', 'yml', 'toml', 'py', 'rb', 'pl', 'r', 'ini', 'conf', 'cfg', 'env', 'gitignore', 'dockerignore', 'nix'])
+const HASH_NAMES = new Set(['Dockerfile', 'Makefile', 'Procfile', 'CODEOWNERS', '.gitignore', '.gitattributes', '.npmignore', '.dockerignore'])
+
+function carriersOf(path: string): { carriers: Carrier[]; markdown: boolean } {
+    const name = path.split('/').at(-1) ?? path
+    const ext = name.includes('.') ? name.split('.').at(-1)!.toLowerCase() : ''
+    if (MARKDOWN.has(ext)) return { carriers: ['html'], markdown: true }
+    if (HTML.has(ext)) return { carriers: ['html'], markdown: false }
+    if (C_LIKE.has(ext)) return { carriers: ['slash', 'block'], markdown: false }
+    if (HASH.has(ext) || HASH_NAMES.has(name)) return { carriers: ['hash'], markdown: false }
+    return { carriers: ['html', 'slash', 'block', 'hash'], markdown: false }
+}
+
+const KEYWORD = 'sk-disable-(next-line|line|file)(?![\\w-])'
+const OPENERS: Record<Carrier, RegExp> = {
+    html: new RegExp(`<!--\\s*${KEYWORD}(.*?)(?:-->|$)`, 'g'),
+    slash: new RegExp(`//\\s*${KEYWORD}(.*)$`, 'g'),
+    block: new RegExp(`/\\*\\s*${KEYWORD}(.*?)(?:\\*/|$)`, 'g'),
+    hash: new RegExp(`(?:^|\\s)#\\s*${KEYWORD}(.*)$`, 'g'),
+}
+
+// a lone dash, never two: `RV027--why` is an id and a glued reason, reported.
+// It ends on a letter or digit, so `RV027: why` is an id and no reason
+const ID = '[A-Za-z0-9](?:(?:[\\w./:]|-(?!-))*[A-Za-z0-9])?'
+const BODY = new RegExp(`^\\s+(${ID}(?:\\s*,\\s*${ID})*)(.*)$`)
+const REASON = /^\s+--\s*(.*?)\s*$/
+
+/** a markdown line with its inline code spans blanked, so a page that shows
+ *  the grammar in backticks declares nothing */
+const withoutInlineCode = (line: string): string => line.replace(/(`+)[\s\S]*?\1/g, (m) => ' '.repeat(m.length))
+
+/** every directive in a file, in line order. A keyword followed by no id is
+ *  not a directive at all (`<ID>` in prose about the grammar). One that names
+ *  ids but no ` -- <reason>` is kept with `reason: null`, so the check it
+ *  names can say it was ignored */
+export function parseDirectives(path: string, text: string): Directive[] {
+    if (!text.includes(DIRECTIVE_MARK)) return []
+    const { carriers, markdown } = carriersOf(path)
+    const fenced = markdown ? fences(text.slice(0, text.lastIndexOf(DIRECTIVE_MARK))) : []
+    const out: Directive[] = []
+    // only the lines holding the mark are read: a journal of a megabyte that
+    // mentions the grammar twice costs two lines
+    let lineNo = 1
+    let counted = 0
+    let last = -1
+    for (let at = text.indexOf(DIRECTIVE_MARK); at !== -1; at = text.indexOf(DIRECTIVE_MARK, at + 1)) {
+        const start = text.lastIndexOf('\n', at) + 1
+        if (start === last) continue
+        last = start
+        for (let n = text.indexOf('\n', counted); n !== -1 && n < start; n = text.indexOf('\n', n + 1)) { lineNo++; counted = n + 1 }
+        if (fenced.some(([a, b]) => start >= a && start < b)) continue
+        const end = text.indexOf('\n', at)
+        const raw = text.slice(start, end === -1 ? text.length : end)
+        const line = markdown ? withoutInlineCode(raw) : raw
+        for (const c of carriers) {
+            for (const m of line.matchAll(OPENERS[c])) {
+                const body = BODY.exec(m[2]!)
+                if (body == null) continue
+                const reason = REASON.exec(body[2]!)?.[1] ?? ''
+                out.push({ scope: m[1] as DirectiveScope, ids: body[1]!.split(',').map((s) => s.trim()), reason: reason === '' ? null : reason, line: lineNo })
+            }
+        }
+    }
+    return out
+}
+
+/** the char spans of the fenced blocks of a markdown text, fence lines
+ *  included, an unclosed one running to the end. Given the text up to its
+ *  last mark only, so a long journal is not walked past it */
+function fences(text: string): [number, number][] {
+    const spans: [number, number][] = []
+    let open: { at: number; fence: string } | null = null
+    for (const m of text.matchAll(/^[ \t]{0,3}(`{3,}|~{3,})/gm)) {
+        const f = m[1]!
+        if (open == null) open = { at: m.index!, fence: f }
+        else if (f[0] === open.fence[0] && f.length >= open.fence.length) { spans.push([open.at, m.index! + m[0].length]); open = null }
+    }
+    if (open != null) spans.push([open.at, text.length])
+    return spans
+}
+
+/** whether a directive reaches a site of its file: a site with no line is
+ *  reached by a file directive only */
+export function reaches(d: Directive, line: number | undefined): boolean {
+    if (d.scope === 'file') return true
+    if (line == null) return false
+    return d.scope === 'line' ? line === d.line : line === d.line + 1
+}
+
+/** how a directive reads in a report */
+export const spell = (d: Directive, id: string): string => `sk-disable-${d.scope} ${id}`

package/src/core/when-block.ts

@@ -29,14 +29,9 @@ import { join } from 'path'
 import { atomicWrite } from './locked-write.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import type { SlowSuite, TestsConfig } from '../suite/judge-suites.ts'
-import { normWord, proseWordsProblems, type ProseAllowWord, type ProseBanWord, type ProseWords } from '../prose/ste.ts'
 
 export const GATE_BEGIN = '// >>> shipkit gate — managed block, the hub writes it, edit outside the markers'
 export const GATE_END = '// <<< shipkit gate'
-/** the second managed block, INSIDE the `prose: {` object: the repo's own
- *  word lists for rule SK014. Same writer, same paranoia, its own markers */
-export const WORDS_BEGIN = '// >>> shipkit prose words — managed block, the hub writes it, edit outside the markers'
-export const WORDS_END = '// <<< shipkit prose words'
 
 /** every key this block owns. A repo declaring one of them outside the
  *  markers keeps it, and the block refuses to write rather than duplicate it */
@@ -55,13 +50,6 @@ export type GateBlock = {
     tests: TestsConfig
     /** true when a key this block owns is declared outside the markers */
     declaredOutside: boolean
-    /** the prose word lists as the config loads them */
-    words: ProseWords
-    /** the words block: `no-prose` when the config has no `prose: {` object
-     *  to write into, and the lists then mean nothing to rule SK014 anyway */
-    wordsState: BlockState | 'no-prose'
-    /** true when `prose.words` is declared outside the words markers */
-    wordsOutside: boolean
 }
 
 export type GateEdit = {
@@ -71,16 +59,6 @@ export type GateEdit = {
     slow?: SlowSuite[]
     /** suite files to drop back to the quick tier */
     slowRemove?: string[]
-    /** the prose word lists: entries to add or replace (keyed by word), and
-     *  words to drop from either list */
-    words?: WordsEdit
-}
-
-export type WordsEdit = {
-    allow?: ProseAllowWord[]
-    ban?: ProseBanWord[]
-    /** words to drop, from whichever list holds them */
-    remove?: string[]
 }
 
 const sha = (s: string): string => createHash('sha256').update(s).digest('hex').slice(0, 16)
@@ -98,11 +76,6 @@ function indentOf(lines: string[]): string {
 
 const isBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit gate')
 const isEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit gate')
-const isWordsBegin = (l: string): boolean => l.trim().startsWith('// >>> shipkit prose words')
-const isWordsEnd = (l: string): boolean => l.trim().startsWith('// <<< shipkit prose words')
-/** the one line the words block can be written under: `prose: {` alone */
-const isProseOpen = (l: string): boolean => /^\s*prose:\s*\{\s*$/.test(l)
-
 /** a single quoted TS string literal, escapes and all */
 const q = (s: string): string => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`
 /** an object key: bare when it is a plain identifier, quoted otherwise */
@@ -138,70 +111,6 @@ export function renderGateBlock(off: Record<string, string>, tests: TestsConfig,
     return out
 }
 
-/** the bytes between the words markers, markers included. Entries sorted by
- *  word, so the block is a function of the lists and a reorder by hand reads
- *  as a hand edit */
-export function renderWordsBlock(words: ProseWords, pad: string, unit = '    '): string[] {
-    const out = [`${pad}${WORDS_BEGIN}`]
-    const allow = [...(words.allow ?? [])].sort((a, b) => normWord(a.word).localeCompare(normWord(b.word)))
-    const ban = [...(words.ban ?? [])].sort((a, b) => normWord(a.word).localeCompare(normWord(b.word)))
-    if (allow.length > 0 || ban.length > 0) {
-        out.push(`${pad}words: {`)
-        const entry = (e: object, keys: string[]): string => {
-            const r = e as Record<string, unknown>
-            return `{ ${keys.filter((f) => typeof r[f] === 'string' && r[f] !== '').map((f) => `${f}: ${q(r[f] as string)}`).join(', ')} },`
-        }
-        const p1 = pad + unit
-        const p2 = p1 + unit
-        if (allow.length > 0) {
-            out.push(`${p1}allow: [`)
-            for (const a of allow) out.push(`${p2}${entry(a, ['word', 'reason'])}`)
-            out.push(`${p1}],`)
-        }
-        if (ban.length > 0) {
-            out.push(`${p1}ban: [`)
-            for (const b of ban) out.push(`${p2}${entry(b, ['word', 'to', 'reason'])}`)
-            out.push(`${p1}],`)
-        }
-        out.push(`${pad}},`)
-    }
-    out.push(`${pad}${WORDS_END}`)
-    return out
-}
-
-/** the words the loader read, in the shape the renderer writes: empty
- *  strings dropped, so a round trip compares content and not spelling */
-const cleanWords = (w: ProseWords | undefined): ProseWords => {
-    const strip = <T extends object>(e: T): T => Object.fromEntries(Object.entries(e).filter(([, v]) => v != null && v !== '')) as T
-    const out: ProseWords = {}
-    if ((w?.allow ?? []).length > 0) out.allow = w!.allow!.map(strip)
-    if ((w?.ban ?? []).length > 0) out.ban = w!.ban!.map(strip)
-    return out
-}
-
-/** the indentation one level inside the line at `at` */
-const innerPad = (lines: string[], at: number): string => {
-    const own = /^([ \t]*)/.exec(lines[at] ?? '')?.[1] ?? ''
-    const unit = indentOf(lines)
-    return own + unit
-}
-
-/** where the words block sits and what state it is in */
-function locateWords(lines: string[], c: RepoConfig): { state: BlockState | 'no-prose'; b: number; e: number; open: number; pad: string; outside: boolean } {
-    const b = lines.findIndex(isWordsBegin)
-    const e = lines.findIndex(isWordsEnd)
-    const open = lines.findIndex(isProseOpen)
-    const words = cleanWords(c.prose?.words)
-    if (b !== -1 && e !== -1 && e > b) {
-        const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
-        const current = lines.slice(b, e + 1).join('\n')
-        const expected = renderWordsBlock(words, pad, indentOf(lines)).join('\n')
-        return { state: current === expected ? 'current' : 'stale', b, e, open, pad, outside: false }
-    }
-    if (open === -1) return { state: 'no-prose', b: -1, e: -1, open, pad: '', outside: c.prose?.words != null }
-    return { state: 'missing-block', b: -1, e: -1, open, pad: innerPad(lines, open), outside: c.prose?.words != null }
-}
-
 /** is repo.config.ts edited and not yet committed? The switch leaves it
  *  DIRTY on purpose: a toggle is a change its owner reviews in a git client,
  *  never a commit an agent makes for them. So the page has to say so. */
@@ -219,7 +128,7 @@ export function configDirty(root: string): boolean {
 /** what the block holds today, and whether it still describes the config */
 export async function readGateBlock(root: string): Promise<GateBlock> {
     const path = configPath(root)
-    if (!existsSync(path)) return { path, hash: '', state: 'missing-file', off: {}, tests: {}, declaredOutside: false, words: {}, wordsState: 'no-prose', wordsOutside: false }
+    if (!existsSync(path)) return { path, hash: '', state: 'missing-file', off: {}, tests: {}, declaredOutside: false }
     const text = readFileSync(path, 'utf8')
     const lines = text.split('\n')
     const b = lines.findIndex(isBegin)
@@ -228,13 +137,11 @@ export async function readGateBlock(root: string): Promise<GateBlock> {
     const off = c.off ?? {}
     const tests = c.tests ?? {}
     const hash = sha(text)
-    const w = locateWords(lines, c)
-    const wordsPart = { words: cleanWords(c.prose?.words), wordsState: w.state, wordsOutside: w.outside }
     if (b === -1 || e === -1 || e < b) {
         // no block: the keys it owns must be unclaimed, or a write would be a
         // second declaration of the same key rather than an edit of the first
         const declaredOutside = OWNED.some((key) => c[key] != null)
-        return { path, hash, state: 'missing-block', off, tests, declaredOutside, ...wordsPart }
+        return { path, hash, state: 'missing-block', off, tests, declaredOutside }
     }
     // the block DESCRIBES the config when re-rendering the loaded values
     // reproduces it byte for byte. Anything else (a hand edit, a second
@@ -243,7 +150,7 @@ export async function readGateBlock(root: string): Promise<GateBlock> {
     const pad = indentOf(lines.slice(b + 1, e))
     const current = lines.slice(b, e + 1).join('\n')
     const expected = renderGateBlock(off, tests, pad === '' ? indentOf(lines) : pad).join('\n')
-    return { path, hash, state: current === expected ? 'current' : 'stale', off, tests, declaredOutside: false, ...wordsPart }
+    return { path, hash, state: current === expected ? 'current' : 'stale', off, tests, declaredOutside: false }
 }
 
 /** does what the loader read back say what was written? BOTH keys the block
@@ -252,7 +159,7 @@ export async function readGateBlock(root: string): Promise<GateBlock> {
  *  what reading the result back exists to catch, and comparing half of the
  *  block would let that half through. Key and array ORDER are the renderer's,
  *  so the comparison is by content. */
-export function roundTripProblem(wrote: { off: Record<string, string>; tests: TestsConfig; words?: ProseWords }, loaded: RepoConfig): string | null {
+export function roundTripProblem(wrote: { off: Record<string, string>; tests: TestsConfig }, loaded: RepoConfig): string | null {
     const normOff = (m: Record<string, string> | undefined): string => JSON.stringify(Object.entries(m ?? {}).sort())
     const normTests = (t: TestsConfig | undefined): string =>
         JSON.stringify({
@@ -262,72 +169,20 @@ export function roundTripProblem(wrote: { off: Record<string, string>; tests: Te
         })
     if (normOff(loaded.off) !== normOff(wrote.off)) return `the loader read off ${JSON.stringify(loaded.off ?? {})}`
     if (normTests(loaded.tests) !== normTests(wrote.tests)) return `the loader read tests ${JSON.stringify(loaded.tests ?? {})}`
-    if (wrote.words != null) {
-        const normWords = (x: ProseWords | undefined): string => {
-            const c = cleanWords(x)
-            const by = (a: { word: string }, b: { word: string }) => normWord(a.word).localeCompare(normWord(b.word))
-            return JSON.stringify({ allow: [...(c.allow ?? [])].sort(by), ban: [...(c.ban ?? [])].sort(by) })
-        }
-        if (normWords(loaded.prose?.words) !== normWords(wrote.words)) return `the loader read prose.words ${JSON.stringify(loaded.prose?.words ?? {})}`
-    }
     return null
 }
 
-/** the next word lists: an entry replaces the one with the same word in
- *  EITHER list (moving a word from allow to ban is one edit), then `remove`
- *  drops words. Judged the way defineRepo judges them */
-export function nextWords(before: ProseWords, edit: WordsEdit): ProseWords {
-    const allow = [...(before.allow ?? [])]
-    const ban = [...(before.ban ?? [])]
-    const drop = (w: string): void => {
-        const n = normWord(w)
-        for (const list of [allow, ban] as { word: string }[][]) {
-            const at = list.findIndex((x) => normWord(x.word) === n)
-            if (at !== -1) list.splice(at, 1)
-        }
-    }
-    const trimmed = <T extends { word: string }>(e: T): T =>
-        Object.fromEntries(Object.entries(e).filter(([, v]) => typeof v === 'string' && v.trim() !== '').map(([key, v]) => [key, (v as string).trim()])) as T
-    for (const a of edit.allow ?? []) {
-        if (typeof a?.word !== 'string' || normWord(a.word) === '') throw new Error(`prose.words.allow needs a word`)
-        drop(a.word)
-        allow.push(trimmed({ word: a.word, reason: a.reason }))
-    }
-    for (const b of edit.ban ?? []) {
-        if (typeof b?.word !== 'string' || normWord(b.word) === '') throw new Error(`prose.words.ban needs a word`)
-        drop(b.word)
-        ban.push(trimmed({ word: b.word, to: b.to, reason: b.reason }))
-    }
-    for (const w of edit.remove ?? []) drop(w)
-    const out: ProseWords = {}
-    if (allow.length > 0) out.allow = allow
-    if (ban.length > 0) out.ban = ban
-    const problems = proseWordsProblems(out)
-    if (problems.length > 0) throw new Error(problems[0])
-    return out
-}
-
-/** the ONE write path, for the switch, the slow suite form and the prose word
- *  lists alike. Each block is rewritten only when the edit touches it, so a
- *  word edit never inserts an empty gate block, and the reverse */
+/** the ONE write path, for the switch and the slow suite form alike */
 export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?: string } = {}): Promise<GateBlock> {
     const before = await readGateBlock(root)
     if (before.state === 'missing-file') throw new Error(`no repo.config.ts in ${root} — run: shipkit init`)
     if (o.expect != null && o.expect !== before.hash)
         throw new Error(`repo.config.ts changed since you read it, reload the page and set it again, so this edit cannot overwrite one made elsewhere`)
-    const touchGate = edit.off != null || edit.slow != null || edit.slowRemove != null
-    const touchWords = edit.words != null
-    if (!touchGate && !touchWords) throw new Error(`nothing to write: the edit names no off, no slow suite and no prose word`)
-    if (touchGate && before.state === 'stale')
+    if (edit.off == null && edit.slow == null && edit.slowRemove == null) throw new Error(`nothing to write: the edit names no off and no slow suite`)
+    if (before.state === 'stale')
         throw new Error(`the shipkit gate block in repo.config.ts no longer matches what the config loads, so it was hand edited or something else declares these keys — reconcile it by hand, then use the switch again`)
-    if (touchGate && before.state === 'missing-block' && before.declaredOutside)
+    if (before.state === 'missing-block' && before.declaredOutside)
         throw new Error(`repo.config.ts declares \`off\` or \`tests\` outside the managed block — move that declaration between the markers first, or the switch would write a duplicate key`)
-    if (touchWords && before.wordsState === 'no-prose')
-        throw new Error(`repo.config.ts has no \`prose: {\` line to write the word lists under — declare \`prose: { include: [...] }\` first, the lists only matter to a repo rule SK014 checks`)
-    if (touchWords && before.wordsState === 'stale')
-        throw new Error(`the shipkit prose words block in repo.config.ts no longer matches what the config loads, so it was hand edited — reconcile it by hand, then edit the lists again`)
-    if (touchWords && before.wordsState === 'missing-block' && before.wordsOutside)
-        throw new Error(`repo.config.ts declares \`prose.words\` outside the managed block — move it between the markers first, or the page would write a duplicate key`)
 
     // the next values, validated the way defineRepo validates them, BEFORE
     // anything reaches the file
@@ -350,47 +205,32 @@ export async function writeGateBlock(root: string, edit: GateEdit, o: { expect?:
     }
     const dropped = new Set(edit.slowRemove ?? [])
     const tests: TestsConfig = { ...before.tests, slow: slow.filter((s) => !dropped.has(s.file)) }
-    const words = touchWords ? nextWords(before.words, edit.words!) : undefined
 
     const text = readFileSync(before.path, 'utf8')
-    let out = text.split('\n')
-    if (touchGate) {
-        const lines = out
-        const b = lines.findIndex(isBegin)
-        const e = lines.findIndex(isEnd)
-        const pad = b === -1 ? indentOf(lines) : indentOf(lines.slice(b + 1, e)) || indentOf(lines)
-        const block = renderGateBlock(off, tests, pad)
-        if (b !== -1 && e !== -1) out = [...lines.slice(0, b), ...block, ...lines.slice(e + 1)]
-        else {
-            // the anchor is the object literal `defineRepo({` opens. Without it
-            // there is nothing to write into, so the block is PRINTED for a
-            // human to paste rather than guessed at
-            const anchor = lines.findIndex((l) => /defineRepo\(\s*\{\s*$/.test(l))
-            if (anchor === -1)
-                throw new Error(`repo.config.ts has no \`defineRepo({\` line to write into — paste this block inside the config object by hand:\n${block.join('\n')}`)
-            out = [...lines.slice(0, anchor + 1), ...block, ...lines.slice(anchor + 1)]
-        }
-    }
-    if (words != null) {
-        const lines = out
-        const b = lines.findIndex(isWordsBegin)
-        const e = lines.findIndex(isWordsEnd)
-        const unit = indentOf(lines)
-        if (b !== -1 && e > b) {
-            const pad = /^([ \t]*)/.exec(lines[b]!)?.[1] ?? ''
-            out = [...lines.slice(0, b), ...renderWordsBlock(words, pad, unit), ...lines.slice(e + 1)]
-        } else {
-            const open = lines.findIndex(isProseOpen)
-            out = [...lines.slice(0, open + 1), ...renderWordsBlock(words, innerPad(lines, open), unit), ...lines.slice(open + 1)]
-        }
+    let out: string[]
+    const lines = text.split('\n')
+    const b = lines.findIndex(isBegin)
+    const e = lines.findIndex(isEnd)
+    const pad = b === -1 ? indentOf(lines) : indentOf(lines.slice(b + 1, e)) || indentOf(lines)
+    const block = renderGateBlock(off, tests, pad)
+    if (b !== -1 && e !== -1) out = [...lines.slice(0, b), ...block, ...lines.slice(e + 1)]
+    else {
+        // the anchor is the object literal `defineRepo({` opens. Without it
+        // there is nothing to write into, so the block is PRINTED for a
+        // human to paste rather than guessed at
+        const anchor = lines.findIndex((l) => /defineRepo\(\s*\{\s*$/.test(l))
+        if (anchor === -1)
+            throw new Error(`repo.config.ts has no \`defineRepo({\` line to write into — paste this block inside the config object by hand:\n${block.join('\n')}`)
+        out = [...lines.slice(0, anchor + 1), ...block, ...lines.slice(anchor + 1)]
     }
+
     atomicWrite(before.path, out.join('\n'))
 
     // read it back through the loader the cli uses. A block that does not
     // round trip is a broken config, so the previous bytes go back
     try {
         const after = await loadRepoConfig(root, { fresh: true })
-        const problem = roundTripProblem({ off, tests, words }, after)
+        const problem = roundTripProblem({ off, tests }, after)
         if (problem != null) throw new Error(`the block did not round trip: ${problem}`)
     } catch (err) {
         atomicWrite(before.path, text)

package/src/core/when.ts

@@ -1,26 +1,28 @@
 // THE CHECKS A REPO TURNS OFF: `off: { <id>: '<why>' }` in repo.config.ts,
 // the switch the hub writes inside its managed block. Where a check runs is
-// its own declaration (core/runs.ts); the one thing a repo says about a check
-// it does not own is that it does not run here, and why. An off row runs in
+// its own declaration (core/runs.ts); a repo says of a whole check it does
+// not own only that it does not run here, and why. An off row runs in
 // no context, and every surface shows it with its reason.
 //
-// Two retired spellings still read as off while SK029 ports them: a `when`
-// entry `'off:<why>'` (defineRepo refuses the other words) and `ruleExempt`.
-// They die once `shipkit fleet` shows no repo carrying them.
+// Four retired spellings still read as off while SK029 ports them: a `when`
+// entry `'off:<why>'` (defineRepo refuses the other words), `ruleExempt`,
+// `hooks.disable` and a floor slot `defaults: { <slot>: false }`. The last two
+// never carried a reason, so they read with one that says so. They die once
+// `shipkit fleet` shows no repo carrying them.
 import type { CheckRow } from '../ledger/gate-checks.ts'
 import type { ResolvedRuns } from './runs.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
 /** the coarse word a resolved row reads as on the check page */
-export type WhenAt = 'always' | 'release' | 'health' | 'off'
+export type WhenAt = 'always' | 'release' | 'health' | 'commit' | 'off'
 
 /** which declaration is answering: the repo's `off`, one of its two retired
  *  spellings, the check file, the `defaults` block, or a derived row */
-export type WhenSource = 'off' | 'when' | 'ruleExempt' | 'check-file' | 'defaults' | 'default'
+export type WhenSource = 'off' | 'when' | 'ruleExempt' | 'hooks.disable' | 'check-file' | 'defaults' | 'default'
 
 export type WhenDecl = { at: WhenAt; reason: string | null; source: WhenSource }
 
-export const WHEN_AT: readonly WhenAt[] = ['always', 'release', 'health', 'off']
+export const WHEN_AT: readonly WhenAt[] = ['always', 'release', 'health', 'commit', 'off']
 
 /** the words a retired `when` value used */
 const WORDS: Record<string, WhenAt> = { always: 'always', release: 'release', health: 'health' }
@@ -41,15 +43,30 @@ export function parseWhen(raw: unknown): WhenDecl | string {
 }
 
 /** the repo turned this check off, with why and where it said so, or null */
-export type RepoOff = { reason: string; source: 'off' | 'when' | 'ruleExempt' }
+export type RepoOff = { reason: string; source: 'off' | 'when' | 'ruleExempt' | 'hooks.disable' | 'defaults' }
 
-export function repoOff(c: RepoConfig, id: string): RepoOff | null {
+/** the reason a spelling that never carried one reads with, and the one the
+ *  SK029 port writes when no comment beside the entry says more. A machine
+ *  cannot invent a reason, so every surface shows the gap */
+export const legacyOffReason = (source: 'hooks.disable' | 'defaults', id: string): string =>
+    source === 'defaults' ? `was defaults: { ${/^[A-Za-z_$][\w$]*$/.test(id) ? id : `'${id}'`}: false }, no reason recorded` : `was hooks.disable: ['${id}'], no reason recorded`
+
+/** the keys `repoOff` reads, so a caller holding part of a config can ask */
+export type OffKeys = Pick<RepoConfig, 'off' | 'when' | 'ruleExempt'> & { hooks?: { disable?: readonly string[] }; defaults?: Record<string, unknown> }
+
+/** THE one answer to "is this id off here", for a check, a floor slot and a
+ *  commit gate alike. A floor slot that is off is off everywhere: no task, no
+ *  routed script, no deny rule */
+export function repoOff(c: OffKeys, id: string): RepoOff | null {
     const own = c.off?.[id]
     if (own != null) return { reason: own, source: 'off' }
     const w = c.when?.[id] == null ? null : parseWhen(c.when[id])
     if (w != null && typeof w !== 'string' && w.at === 'off') return { reason: w.reason ?? '', source: 'when' }
     const exempt = c.ruleExempt?.[id]
-    return exempt == null ? null : { reason: exempt, source: 'ruleExempt' }
+    if (exempt != null) return { reason: exempt, source: 'ruleExempt' }
+    if (c.hooks?.disable?.includes(id) === true) return { reason: legacyOffReason('hooks.disable', id), source: 'hooks.disable' }
+    if (c.defaults?.[id] === false) return { reason: legacyOffReason('defaults', id), source: 'defaults' }
+    return null
 }
 
 /** a resolved row the repo turned off: it runs in no context */
@@ -57,10 +74,10 @@ export const withRepoOff = (base: ResolvedRuns, off: RepoOff | null): ResolvedRu
 
 /** the coarse word a resolved row reads as, for the check page. Derived,
  *  never declared */
-export function whenSummary(r: ResolvedRuns, off: RepoOff | { reason: string; source: 'defaults' } | null, fromFile: boolean): WhenDecl {
+export function whenSummary(r: ResolvedRuns, off: RepoOff | null, fromFile: boolean, o: { hook?: boolean } = {}): WhenDecl {
     const source: WhenSource = off?.source ?? (fromFile ? 'check-file' : 'default')
     if (r.off != null) return { at: 'off', reason: r.off, source }
-    const at: WhenAt = r.onCi ? 'always' : r.onFull || r.onRelease ? 'release' : r.onHealth || r.onSave !== false || r.onClock !== false ? 'health' : 'off'
+    const at: WhenAt = r.onCi ? 'always' : r.onFull || r.onRelease ? 'release' : r.onHealth || r.onSave !== false || r.onClock !== false ? 'health' : o.hook === true || r.onPreCommit !== false ? 'commit' : 'off'
     return { at, reason: at === 'off' ? 'no context runs it' : null, source }
 }
 

package/src/core/wire.ts

@@ -13,7 +13,23 @@ export { spanShort }
  *  as a future expiry long after it passed */
 export type Stamp = { at: number; until: number | null; cached?: boolean; ranMs?: number }
 
-export type Line = { kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'; text: string; stamp?: Stamp }
+/** where a finding sits: a repo-relative file, and its line and column when
+ *  the check knows them. A site is what an in-file directive can waive
+ *  (core/waivers.ts) and what the problems pane opens */
+export type Site = { file: string; line?: number; col?: number }
+
+export type Line = {
+    kind: 'ok' | 'warn' | 'fail' | 'note' | 'fix-warn' | 'fix-fail' | 'skip'
+    text: string
+    stamp?: Stamp
+    at?: Site
+    /** a waiver report: `count` prints with the check, `site` lists one
+     *  waived site and prints only where every line does (--verbose, STATUS.md) */
+    waiver?: 'count' | 'site'
+}
+
+/** `file:line:col`, as far as the site knows */
+export const siteText = (s: Site): string => `${s.file}${s.line == null ? '' : `:${s.line}${s.col == null ? '' : `:${s.col}`}`}`
 
 /** `cached, 3h old, kept 57m more` for a replay, `ran 0.4s, kept 1h more`
  *  for an answer this run measured, `ran 1d ago, expired 1d ago` for one

package/src/git-bootstrap.ts

@@ -323,7 +323,7 @@ export function ensureIgnoreBaseline(root: string): void {
 
 /** never in a first commit, wherever it sits in the tree. `.env.example` and
  *  friends are documentation and belong in the repo */
-function isRisky(f: string): boolean {
+export function isRisky(f: string): boolean {
     if (f.split('/').includes('node_modules')) return true
     const base = basename(f)
     return base.startsWith('.env') && !/^\.env\.(example|sample|template|dist)$/.test(base)

package/src/home/attach.ts

@@ -1,10 +1,8 @@
 // `shipkit serve` while a home runs: the hub itself runs in the home, and
-// this process only streams its lines. So the VS Code folder-open task keeps its
-// problem matcher and its clickable url, with no change to any repo's
-// tasks.json, and closing VS Code no longer stops the hub.
+// this process only streams its lines, so stopping it never stops the hub.
 //
-// the log is what the home prints for that hub, so the frames the matcher
-// reads arrive as the hub prints them. On attach, the last complete frame is replayed first,
+// the log is what the home prints for that hub, so the frames arrive as the
+// hub prints them. On attach, the last complete frame is replayed first,
 // so the problems pane fills at once instead of at the next run.
 import { closeSync, existsSync, openSync, readSync, statSync } from 'fs'
 import { FRAME_BEGIN, FRAME_END_HEAD } from '../problems/problem-line.ts'

package/src/home/insights.ts

@@ -11,6 +11,8 @@ import { homedir } from 'os'
 import { join } from 'path'
 import { gitBin } from '../core/git-bin.ts'
 import { boxesOf, type InsightsAnswer, type Manifest, type Scope } from './insights-shape.ts'
+import { isVendored } from '../core/vendored.ts'
+import { readVendored } from '../core/vendored-read.ts'
 
 export * from './insights-shape.ts'
 
@@ -40,7 +42,10 @@ async function manifestPaths(dir: string): Promise<string[]> {
     const p = Bun.spawn([gitBin(), 'ls-files', '-z', '--', 'package.json', '**/package.json'], { cwd: dir, stdout: 'pipe', stderr: 'ignore', env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } })
     const [out, code] = await Promise.all([new Response(p.stdout).text(), p.exited])
     if (code !== 0) return existsSync(join(dir, 'package.json')) ? ['package.json'] : []
-    return out.split('\0').filter(Boolean)
+    // a vendored library's manifest is its upstream's, not a package this repo uses
+    let vendored: string[] = []
+    try { vendored = readVendored(dir) } catch { /* a config the repo cannot read is its own gate's failure */ }
+    return out.split('\0').filter((f) => f !== '' && !isVendored(f, vendored))
 }
 
 /** one repo's manifests, read; a file that does not parse is an error line */

package/src/home/pm-config.ts

@@ -30,9 +30,9 @@ if (import.meta.main) {
     const out: PmConfig = { index: house.index, processes: [], errors: [], inputs, stamp: stampOf(inputs) }
     if (house.index != null) {
         // a unit file imports the lib by name: this copy, like the daemon's
-        const { useOneLib } = await import('../core/one-lib.ts')
+        const { installOneLib } = await import('../core/one-lib.ts')
         const { scanGlobalUnits } = await import('./global-units.ts')
-        useOneLib()
+        installOneLib()
         const u = await scanGlobalUnits(repos.map((r) => ({ name: r.name, path: r.path })), { files: (r) => files.get(r) ?? [] })
         out.processes = u.processes
         out.errors = u.errors

package/src/home/run-daemon.ts

@@ -7,7 +7,7 @@
 // at once (lib-watch.ts): the new image follows the jobs still running. The
 // machine resources are pm's.
 import { fileURLToPath } from 'url'
-import { useOneLib } from '../core/one-lib.ts'
+import { installOneLib } from '../core/one-lib.ts'
 import { reclaimPreviousImage } from '../core/instance.ts'
 import { reloadOnOwnCode } from './lib-watch.ts'
 import { loadHub } from '../serve/hub-runtime.ts'
@@ -47,7 +47,7 @@ export async function runDaemon(root: string, io: HomeIo, o: { port?: number } =
     }
     // before the first repo config loads: every one of them, and every check
     // file, then imports this copy of the lib
-    useOneLib()
+    installOneLib()
     // a process this one starts runs its gate and its hub in process
     process.env[WORKER_ENV] = '1'
     // a restart in place keeps the pid: the check children its previous

package/src/home/run-unit-action.ts

@@ -12,8 +12,8 @@ if (import.meta.main) {
         console.error('usage: bun run-unit-action.ts <unit file> <action id>')
         process.exit(2)
     }
-    const { useOneLib } = await import('../core/one-lib.ts')
-    useOneLib()
+    const { installOneLib } = await import('../core/one-lib.ts')
+    installOneLib()
     const u = ((await import(file)) as { default?: GlobalProcessUnit }).default
     const run = u?.actions?.[id]?.run
     if (run == null) {