rvlib-shipkit 1.8.0 → 2.0.0

package/src/core/vendored.ts

@@ -0,0 +1,82 @@
+// `vendored` in repo.config.ts: repo-relative dirs of THIRD PARTY code (a git
+// subtree, a copied library) that no shipkit tool lints, formats, rewrites or
+// analyses as the repo's own source. Read as TEXT, never by loading the
+// config: the source-graph cli, the md scan and the file listings run where
+// the config is never loaded, and a prefix test per path is the whole cost.
+// loadRepoConfig refuses a config whose loaded value and text disagree.
+// Pure, so a check's closure can import it: the disk half is vendored-read.ts.
+//
+// the one constraint a reader breaks first: cache keys and watchers still
+// read vendored files. Vendored code is still an INPUT to builds and tests;
+// only the tools that treat the tree as the repo's own source omit it.
+import { configDepths } from './identity-color.ts'
+
+const CONFIG_FILE = 'repo.config.ts'
+
+const KEY_RE = /(?:^|[{,])\s*(['"]?)vendored\1\s*:\s*/gm
+
+/** an entry as every tool compares it: posix, no `./`, no trailing `/` */
+export const normalizeVendored = (d: string): string => d.replace(/\\/g, '/').replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+
+/** why an entry cannot be a vendored dir, null when it can */
+export function vendoredProblem(entry: unknown): string | null {
+    if (typeof entry !== 'string' || entry.trim() === '') return 'is not a repo-relative dir path'
+    const d = normalizeVendored(entry)
+    if (d === '' || d === '.') return 'is the repo root: it would omit the whole repo from every tool'
+    if (entry.startsWith('/') || d.split('/').includes('..')) return 'leaves the repo: name a dir inside it'
+    if (/[*?[\]{}!]/.test(d)) return 'is a glob: name the dir itself, every path under it is omitted'
+    return null
+}
+
+/** the `vendored` entries the config text declares, normalized. Empty when
+ *  the key is absent. Throws when the value is anything but a literal array
+ *  of string literals, which a reader of the text cannot evaluate */
+export function vendoredOfText(text: string): string[] {
+    const depth = configDepths(text)
+    const found: string[][] = []
+    for (const m of text.matchAll(KEY_RE)) {
+        const sep = /^[{,]/.test(m[0]) ? m.index : m.index - 1
+        const colon = m.index + m[0].lastIndexOf(':')
+        if (sep < 0 || depth[sep] !== 1 || depth[colon] !== 1) continue
+        const open = m.index + m[0].length
+        if (text[open] !== '[') throw new Error(`${CONFIG_FILE}: \`vendored\` must be a literal array of strings, the tools that never load the config read it as text`)
+        let close = open + 1
+        while (close < text.length && !(text[close] === ']' && depth[close] === 1)) close++
+        if (close >= text.length) throw new Error(`${CONFIG_FILE}: \`vendored\` has no closing \`]\``)
+        const body = text.slice(open + 1, close).replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '')
+        const items: string[] = []
+        const rest = body.replace(/(['"])((?:\\.|(?!\1).)*)\1/g, (_, _q: string, s: string) => { items.push(s); return '' })
+        if (!/^[\s,]*$/.test(rest)) throw new Error(`${CONFIG_FILE}: \`vendored\` must list string literals only, the tools that never load the config read it as text`)
+        found.push(items.map(normalizeVendored))
+    }
+    if (found.length > 1) throw new Error(`${CONFIG_FILE} declares \`vendored\` more than once`)
+    return found[0] ?? []
+}
+
+/** is this repo-relative path a vendored dir or inside one */
+export function isVendored(rel: string, dirs: readonly string[]): boolean {
+    if (dirs.length === 0) return false
+    const n = rel.replace(/\\/g, '/').replace(/^(\.\/)+/, '')
+    return dirs.some((d) => n === d || n.startsWith(`${d}/`))
+}
+
+/** the glob's fixed leading dirs, before its first wildcard */
+const globBase = (glob: string): string => {
+    const segs = glob.replace(/^(\.\/)+/, '').split('/')
+    const fixed: string[] = []
+    for (const s of segs.slice(0, -1)) {
+        if (/[*?[\]{}!]/.test(s)) break
+        fixed.push(s)
+    }
+    return fixed.join('/')
+}
+
+/** a listing with the vendored files left out, unless the glob itself names a
+ *  path inside a vendored dir: a check that asks for `vendor/lib/src/**`
+ *  wants exactly those files */
+export function listingWithoutVendored(files: readonly string[], glob: string, dirs: readonly string[]): string[] {
+    if (dirs.length === 0) return [...files]
+    const base = globBase(glob)
+    if (base !== '' && isVendored(base, dirs)) return [...files]
+    return files.filter((f) => !isVendored(f, dirs))
+}

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)