rvlib-shipkit 0.38.1 → 1.0.0

package/src/prose/ste.ts

@@ -26,6 +26,7 @@ export type ProseClass =
     | 'sentence'
     | 'passive'
     | 'paragraph'
+    | 'ban'
 
 export type ProseHit = {
     line: number // 1-based, true to the file
@@ -36,6 +37,38 @@ export type ProseHit = {
     text: string // the offending span
     fix?: string // the replacement, when the class is mechanical
     why: string // one line, what STE wants instead
+    /** the dictionary entry that fired, lowercased: what a repo `allow` entry
+     *  names and what the hub groups by. Absent on the classes that judge a
+     *  shape (sentence length, paragraph, semicolon) rather than a word */
+    word?: string
+}
+
+/** a word or phrase this repo accepts: every hit on it is dropped */
+export type ProseAllowWord = {
+    /** the word or phrase, case ignored. A dictionary entry (`should`,
+     *  `leverage`) covers its inflected forms too */
+    word: string
+    /** one line: why this repo accepts it */
+    reason?: string
+}
+
+/** a word or phrase this repo refuses on top of the house dictionary */
+export type ProseBanWord = {
+    /** the word or phrase, case ignored, matched on word boundaries */
+    word: string
+    /** what to write instead. Given, `shipkit prose --fix` writes it */
+    to?: string
+    /** one line: why this repo refuses it */
+    reason?: string
+}
+
+/** the per repo word lists. The house dictionary in this file stays the
+ *  default, and these override it for one repo only */
+export type ProseWords = {
+    /** words and phrases this repo accepts */
+    allow?: ProseAllowWord[]
+    /** words and phrases this repo refuses, each with its replacement */
+    ban?: ProseBanWord[]
 }
 
 export type ProseOpts = {
@@ -43,6 +76,8 @@ export type ProseOpts = {
     allow?: ProseClass[]
     /** procedural limit (20) instead of the descriptive one (25) */
     strict?: boolean
+    /** the repo's own allow and ban lists */
+    words?: ProseWords
 }
 
 const TIER: Record<ProseClass, ProseTier> = {
@@ -50,13 +85,16 @@ const TIER: Record<ProseClass, ProseTier> = {
     abbrev: 'fix',
     slop: 'fix',
     modal: 'soft',
-    semicolon: 'hard',
+    // reports, never blocks: the join carries meaning a rewrite can lose
+    semicolon: 'soft',
     'comma-ing': 'soft',
     perfect: 'soft',
     vague: 'hard',
     sentence: 'soft',
     passive: 'soft',
     paragraph: 'soft',
+    // the repo named the word itself, so a hit is never a guess
+    ban: 'hard',
 }
 
 export const PROSE_CLASSES = Object.keys(TIER) as ProseClass[]
@@ -201,8 +239,6 @@ export function maskProse(src: string): string {
     return m
 }
 
-/** a table row is structure: word classes still apply inside a cell, sentence
- *  and paragraph limits do not. Same for a heading. */
 /** `is unmaintained` is a state, not a passive voice: there is no verb `to
  *  unmaintain`, so no actor exists to name. The `un-` prefix catches almost
  *  the whole family; the rest are participles coined off a noun. */
@@ -215,7 +251,20 @@ const isAdjectival = (participle: string): boolean => {
     return (w.startsWith('un') && w.endsWith('ed')) || COINED.has(w) || NOT_PARTICIPLES.has(w)
 }
 
-const isStructureLine = (l: string): boolean => /^\s*\|/.test(l) || /^\s*#{1,6}\s/.test(l) || /^\s*[-|: ]+$/.test(l)
+/** a table row is structure: word classes still apply inside a cell, the
+ *  sentence, paragraph and semicolon rules do not. A cell is not a sentence,
+ *  so "write two sentences" asks for the table to be broken, and its items
+ *  are already comma separated, which leaves the semicolon as the only
+ *  separator the writer has left. */
+const isTableRow = (l: string): boolean => /^\s*\|/.test(l)
+
+/** a list item OPENS a new paragraph: a run of items with no blank line
+ *  between them is a list, never a wall of text, and counting the run as one
+ *  paragraph reported a five item list as 38 sentences. Both numbered forms,
+ *  at any indentation. */
+const isListItem = (l: string): boolean => /^\s*(?:[-*+]|\d+[.)])\s/.test(l)
+
+const isStructureLine = (l: string): boolean => isTableRow(l) || /^\s*#{1,6}\s/.test(l) || /^\s*[-|: ]+$/.test(l)
 
 // --- sentence segmentation ----------------------------------------------
 
@@ -249,8 +298,13 @@ const capitalizeLike = (sample: string, replacement: string): string =>
 
 const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
+/** one spelling for a word or phrase, so `Prior  To` and `prior to` are the
+ *  same entry */
+export const normWord = (w: string): string => w.trim().toLowerCase().replace(/\s+/g, ' ')
+
 export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
     const allow = new Set(opts.allow ?? [])
+    const allowWords = new Set((opts.words?.allow ?? []).map((a) => normWord(a.word)))
     const masked = maskProse(src)
     const hits: ProseHit[] = []
     // line index → offset, once
@@ -267,10 +321,19 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
         return lo + 1
     }
 
-    const push = (cls: ProseClass, start: number, end: number, why: string, fix?: string) => {
+    const push = (cls: ProseClass, start: number, end: number, why: string, fix?: string, word?: string) => {
         if (allow.has(cls)) return
         const text = src.slice(start, end)
-        hits.push({ line: lineOf(start), start, end, cls, tier: TIER[cls], text, fix, why })
+        if (allowWords.size > 0 && (allowWords.has(normWord(text)) || (word != null && allowWords.has(word)))) return
+        hits.push({ line: lineOf(start), start, end, cls, tier: TIER[cls], text, fix, why, ...(word == null ? {} : { word }) })
+    }
+
+    /** the whole masked line an offset sits on, for the classes that need the
+     *  line's SHAPE (a table row, a list item) and not only the span */
+    const lineAt = (off: number): string => {
+        const from = masked.lastIndexOf('\n', off) + 1
+        const to = masked.indexOf('\n', off)
+        return masked.slice(from, to < 0 ? masked.length : to)
     }
 
     const scan = (re: RegExp, run: (m: RegExpExecArray) => void) => {
@@ -285,11 +348,11 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
     // --- fix tier
     scan(new RegExp(`\\b(${Object.keys(CONTRACTIONS).map(escapeRe).join('|')})`, 'gi'), (m) => {
         const full = CONTRACTIONS[m[0].toLowerCase()]
-        if (full != null) push('contraction', m.index, m.index + m[0].length, 'STE keeps the full form', capitalizeLike(m[0], full))
+        if (full != null) push('contraction', m.index, m.index + m[0].length, 'STE keeps the full form', capitalizeLike(m[0], full), m[0].toLowerCase())
     })
     scan(new RegExp(`(?<![\\w.])(${Object.keys(ABBREV).map(escapeRe).join('|')})`, 'gi'), (m) => {
         const full = ABBREV[m[0].toLowerCase()]
-        if (full != null) push('abbrev', m.index, m.index + m[0].length, 'write the words a non-native reader can read', capitalizeLike(m[0], full))
+        if (full != null) push('abbrev', m.index, m.index + m[0].length, 'write the words a non-native reader can read', capitalizeLike(m[0], full), m[0].toLowerCase())
     })
     // a verb entry matches its inflected forms too, and the ending rides onto
     // the replacement
@@ -301,12 +364,12 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
         const stem = e.from.endsWith('e') ? e.from.slice(0, -1) : e.from
         scan(new RegExp(`\\b(?:${escapeRe(e.from)}(es|s|ed|d)?|${escapeRe(stem)}(ing))\\b`, 'gi'), (m) => {
             const to = inflect(e.to, (m[1] ?? m[2] ?? '').toLowerCase())
-            push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], to))
+            push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], to), e.from)
         })
     }
     scan(new RegExp(`\\b(${plain.map((x) => escapeRe(x.from)).join('|')})\\b`, 'gi'), (m) => {
         const e = plain.find((x) => x.from === m[0]!.toLowerCase())
-        if (e != null) push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], e.to))
+        if (e != null) push('slop', m.index, m.index + m[0].length, `STE writes '${e.to}'`, capitalizeLike(m[0], e.to), e.from)
     })
     // a deletion gives back exactly one space, and WHICH one depends on what
     // follows: before punctuation the space in front goes with the word, or
@@ -323,16 +386,19 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
         if (before === ',' && after === ',') end += 1
         const punctuationFollows = /[.,:;!?)\]]/.test(after)
         const fix = lead === '' ? undefined : punctuationFollows ? '' : lead
-        push('slop', m.index, end, 'the word carries no fact', fix)
+        push('slop', m.index, end, 'the word carries no fact', fix, normWord(m[2]!))
     })
     for (const p of PHRASE_SUBSTITUTIONS)
-        scan(new RegExp(p.re.source, 'gi'), (m) => push('slop', m.index, m.index + m[0].length, p.why, capitalizeLike(m[0], p.to)))
+        scan(new RegExp(p.re.source, 'gi'), (m) => push('slop', m.index, m.index + m[0].length, p.why, capitalizeLike(m[0], p.to), normWord(m[0].replace(/,\s*$/, ''))))
 
     // --- hard tier
     scan(new RegExp(`\\b(${MODALS.join('|')})\\b`, 'gi'), (m) =>
-        push('modal', m.index, m.index + m[0].length, "a requirement is 'must', a possibility is 'can', a recommendation is a fact or it is deleted"),
+        push('modal', m.index, m.index + m[0].length, "a requirement is 'must', a possibility is 'can', a recommendation is a fact or it is deleted", undefined, m[0].toLowerCase()),
     )
-    scan(/;/g, (m) => push('semicolon', m.index, m.index + 1, 'write two sentences'))
+    scan(/;/g, (m) => {
+        if (isTableRow(lineAt(m.index))) return
+        push('semicolon', m.index, m.index + 1, 'write two sentences')
+    })
     scan(/,\s+(\w+ing)\b/g, (m) => {
         if (/^(nothing|something|anything|everything|during|string|thing)$/i.test(m[1]!)) return
         // an `-ing` word used as an ADJECTIVE (`, missing path`) is not the
@@ -345,17 +411,31 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
         // `Renaming a file, moving a responsibility, or changing any contract`
         // is a coordinated list of gerund NOUNS, not the participial clause
         // the rule bans. The tell is a second gerund behind `and` or `or`.
-        const line = masked.slice(masked.lastIndexOf('\n', m.index) + 1, (masked.indexOf('\n', m.index) + 1 || masked.length + 1) - 1)
-        if (/\b(and|or)\s+\w+ing\b/.test(line)) return
+        if (/\b(and|or)\s+\w+ing\b/.test(lineAt(m.index))) return
         push('comma-ing', m.index, m.index + m[0].length, "STE bans an '-ing' verb after a comma: start a new sentence, or write the relative clause")
     })
     scan(new RegExp(`\\b(has|have|had)\\s+(been|\\w+ed|${PARTICIPLES})\\b`, 'gi'), (m) =>
-        push('perfect', m.index, m.index + m[0].length, 'STE uses simple tenses only'),
+        push('perfect', m.index, m.index + m[0].length, 'STE uses simple tenses only', undefined, normWord(m[0])),
     )
     scan(new RegExp(`\\b(${Object.keys(VAGUE).map(escapeRe).join('|')})\\b`, 'gi'), (m) => {
         const why = VAGUE[m[0].toLowerCase()]
-        if (why != null) push('vague', m.index, m.index + m[0].length, why)
+        if (why != null) push('vague', m.index, m.index + m[0].length, why, undefined, m[0].toLowerCase())
     })
+    // the repo's own ban list: hard, because the repo named the word itself.
+    // A house hit on the same span gives way, so one word reports once and
+    // with the repo's own replacement
+    const banned: [number, number][] = []
+    for (const b of opts.words?.ban ?? []) {
+        const w = normWord(b.word)
+        if (w === '') continue
+        const body = w.split(' ').map(escapeRe).join('\\s+')
+        scan(new RegExp(`(?<![\\w'-])${body}(?![\\w'-])`, 'gi'), (m) => {
+            if (allow.has('ban')) return
+            banned.push([m.index, m.index + m[0].length])
+            const why = `this repo refuses '${w}'${b.to != null && b.to !== '' ? `, write '${b.to}'` : ''}${b.reason != null && b.reason !== '' ? `: ${b.reason}` : ''}`
+            push('ban', m.index, m.index + m[0].length, why, b.to != null && b.to !== '' ? capitalizeLike(m[0], b.to) : undefined, w)
+        })
+    }
 
     // --- soft tier, line by line
     const limit = opts.strict === true ? 20 : 25
@@ -385,21 +465,24 @@ export function checkProse(src: string, opts: ProseOpts = {}): ProseHit[] {
         let pm: RegExpExecArray | null
         while ((pm = passRe.exec(line)) != null) {
             if (isAdjectival(pm[2]!)) continue
-            push('passive', off + pm.index, off + pm.index + pm[0].length, 'STE wants the active voice: name the actor')
-        }
-        const isBullet = /^\s*(?:[-*+]|\d+\.)\s/.test(line)
-        if (!isBullet) {
-            if (paraStart < 0) paraStart = i
+            push('passive', off + pm.index, off + pm.index + pm[0].length, 'STE wants the active voice: name the actor', undefined, normWord(pm[0]))
         }
+        const item = isListItem(line)
+        if (item) flushParagraph(i)
+        else if (paraStart < 0) paraStart = i
         for (const s of splitSentences(line)) {
             const w = wordCount(s.text)
-            if (!isBullet && paraStart >= 0 && w > 0) paraSentences++
+            if (!item && paraStart >= 0 && w > 0) paraSentences++
             if (w > limit)
                 push('sentence', off + s.at, off + s.at + s.text.length, `${w} words: the limit is ${limit}`)
         }
     }
     flushParagraph(lines.length)
 
+    if (banned.length > 0) {
+        const underBan = (h: ProseHit): boolean => h.cls !== 'ban' && h.word != null && banned.some(([a, b]) => h.start < b && a < h.end)
+        for (let i = hits.length - 1; i >= 0; i--) if (underBan(hits[i]!)) hits.splice(i, 1)
+    }
     return hits.sort((a, b) => a.start - b.start)
 }
 
@@ -434,3 +517,36 @@ export function fixProse(src: string, opts: ProseOpts = {}): { text: string; app
     return { text, applied }
 }
 
+/** what is wrong with a repo's word lists, judged the same way by the config
+ *  loader and by the hub's writer: an empty word, a word listed twice, or a
+ *  word both allowed and banned, which leaves the repo's intent undecidable */
+export function proseWordsProblems(w: ProseWords | undefined): string[] {
+    if (w == null) return []
+    if (typeof w !== 'object' || Array.isArray(w)) return ['prose.words is an object: { allow?: [...], ban?: [...] }']
+    const out: string[] = []
+    for (const k of Object.keys(w)) if (k !== 'allow' && k !== 'ban') out.push(`prose.words.${k} is not a key (keys: allow, ban)`)
+    const seen = new Map<string, 'allow' | 'ban'>()
+    for (const list of ['allow', 'ban'] as const) {
+        const entries: unknown = w[list] ?? []
+        if (!Array.isArray(entries)) {
+            out.push(`prose.words.${list} is a list`)
+            continue
+        }
+        for (const e of entries as { word?: unknown; to?: unknown; reason?: unknown }[]) {
+            if (e == null || typeof e.word !== 'string' || normWord(e.word) === '') {
+                out.push(`prose.words.${list} has an entry with no word`)
+                continue
+            }
+            const fields = list === 'ban' ? ['word', 'to', 'reason'] : ['word', 'reason']
+            for (const f of Object.keys(e)) if (!fields.includes(f)) out.push(`prose.words.${list} '${e.word}' has an unknown field '${f}' (fields: ${fields.join(', ')})`)
+            for (const f of ['to', 'reason'] as const) if (e[f] != null && typeof e[f] !== 'string') out.push(`prose.words.${list} '${e.word}' ${f} is a string`)
+            const n = normWord(e.word)
+            const was = seen.get(n)
+            if (was === list) out.push(`prose.words.${list} lists '${n}' twice`)
+            else if (was != null) out.push(`prose.words lists '${n}' in both allow and ban, pick one`)
+            seen.set(n, list)
+        }
+    }
+    return out
+}
+

package/src/reflections/reflections-queue.ts

@@ -0,0 +1,81 @@
+// The `.shipkit/reflections/` queue: friction a repo logged against the wiki it
+// follows, waiting for a fresh agent to fold each file into the owning page
+// and DELETE it. Deletion is the ack, so a file that is still here is still
+// pending. Contract: meta/wiki-doctrine in the docs wiki this lib ships
+// beside.
+//
+// Two kinds. A file asking for a wiki RULE change carries six sections; a
+// plain friction NOTE carries no shape at all. Sections match on HEADING-ish
+// lines only: a substring scan of the whole file called any note mentioning
+// "proposed change" a malformed request, and satisfied `scope claimed` from
+// ordinary prose.
+import { existsSync, readdirSync, readFileSync } from 'fs'
+import { join } from 'path'
+import { LAYOUT } from '../core/layout.ts'
+import { LEGACY_CONTRACT_PREFIX } from '../core/migrate-layout.ts'
+
+export const REFLECTIONS_DIR = LAYOUT.reflections
+
+/** where a repo's queue sits. A harvest across repos reads some that have not
+ *  run the new shipkit yet, whose queue is still in the old folder. This read
+ *  dies once `shipkit fleet` shows no repo on the old layout */
+const queueDir = (root: string): string => {
+    const legacy = join(root, `${LEGACY_CONTRACT_PREFIX}reflections`)
+    return !existsSync(join(root, REFLECTIONS_DIR)) && existsSync(legacy) ? legacy : join(root, REFLECTIONS_DIR)
+}
+
+export const REQUEST_SECTIONS = [
+    'what i was doing',
+    'what the wiki said',
+    'what actually happened',
+    'owns it',
+    'proposed change',
+    'scope claimed',
+] as const
+
+export type ReflectionKind = { isRequest: boolean; missing: string[] }
+
+/** heading lines: markdown headings, or a line leading with **bold** (the
+ *  shape as wiki-doctrine writes it) */
+const headingLines = (text: string): string[] =>
+    text
+        .split('\n')
+        .filter((l) => /^\s*(#{1,6}\s+|\*\*|[-*]\s+\*\*)/.test(l))
+        .map((l) => l.toLowerCase())
+
+export function classifyReflection(text: string): ReflectionKind {
+    const heads = headingLines(text)
+    const has = (section: string): boolean => heads.some((h) => h.includes(section))
+    // it announces itself by PROPOSING something, in a heading
+    if (!has('proposed change')) return { isRequest: false, missing: [] }
+    return { isRequest: true, missing: REQUEST_SECTIONS.filter((s) => !has(s)) }
+}
+
+export type Reflection = ReflectionKind & { file: string; title: string; unreadable: boolean }
+
+/** the first heading, which is the line whoever logged it wrote to name it */
+const firstHeading = (text: string): string | null =>
+    text.split('\n').find((l) => /^\s*#{1,6}\s+\S/.test(l))?.replace(/^\s*#{1,6}\s+/, '').trim() ?? null
+
+/** every file still pending. README.md is the scaffold's own seed, written
+ *  into every started repo, so counting it makes every fresh repo a
+ *  permanent false row */
+export function listReflections(root: string): Reflection[] {
+    let files: string[] = []
+    try {
+        files = readdirSync(queueDir(root)).filter((f) => f.endsWith('.md') && f !== 'README.md')
+    } catch {
+        return []
+    }
+    return files.sort().map((file): Reflection => {
+        let text: string | null = null
+        try {
+            text = readFileSync(join(queueDir(root), file), 'utf8')
+        } catch {
+            // reported as unreadable rather than dropped: a file nobody can
+            // read is still a file nobody harvested
+        }
+        if (text == null) return { file, title: file, isRequest: false, missing: [], unreadable: true }
+        return { file, title: firstHeading(text) ?? file, unreadable: false, ...classifyReflection(text) }
+    })
+}

package/src/release/git-facts.ts

@@ -3,9 +3,11 @@
 // Deliberately dependency-free (no config load, no ci) so a check script can
 // import it without dragging the gate in.
 import type { RepoConfig } from '../repo-config.ts'
+import { gitBin } from '../core/git-bin.ts'
+import { CI_LOG_DIR, LAYOUT } from '../core/layout.ts'
 
 export function git(root: string, args: string[]): { code: number; out: string } {
-    const p = Bun.spawnSync(['git', ...args], { cwd: root })
+    const p = Bun.spawnSync([gitBin(), ...args], { cwd: root })
     return { code: p.exitCode, out: `${p.stdout.toString()}${p.stderr.toString()}`.trim() }
 }
 
@@ -27,16 +29,20 @@ export function deriveRemote(root: string): { remote: string } | { error: string
     return { error: `branch '${branch === '' ? '(detached)' : branch}' has no upstream and ${remotes.length} remotes exist (${remotes.join(', ')}) — set one with git push -u <remote> <branch>` }
 }
 
-/** the worktree's dirty paths, minus the runner's own log dir. running the
- *  gate creates that dir, so counting it would make every gated release refuse
- *  in any repo that does not gitignore it. */
+/** the worktree's dirty paths, minus the runner's own scratch (`.shipkit/tmp/`,
+ *  and a `logDir` set elsewhere). running the gate writes its logs, leases and job records there, so counting them would
+ *  make every gated release refuse in any repo that does not gitignore it.
+ *  `-uall` lists every untracked file, so a folder git would fold into one
+ *  row never hides real dirt beside the scratch */
 export function dirtyPaths(root: string, config: RepoConfig, pathspec?: string | string[]): string {
-    const logRoot = (config.logDir ?? 'tmp/shipkit-ci').replace(/^\.\//, '').split('/')[0]!
+    const logDir = (config.logDir ?? CI_LOG_DIR).replace(/^\.\//, '').replace(/\/+$/, '')
+    const scratch = [LAYOUT.tmp, ...(logDir.startsWith(`${LAYOUT.tmp}/`) ? [] : [logDir.split('/')[0]!])]
+    const own = (p: string): boolean => scratch.some((d) => p.startsWith(`${d}/`) || p === d)
     const specs = (typeof pathspec === 'string' ? [pathspec] : (pathspec ?? [])).filter((p) => p !== '')
-    const args = specs.length > 0 ? ['status', '--porcelain', '--', ...specs] : ['status', '--porcelain']
+    const args = specs.length > 0 ? ['status', '--porcelain', '-uall', '--', ...specs] : ['status', '--porcelain', '-uall']
     return git(root, args).out
         .split('\n')
-        .filter((l) => l.trim() !== '' && !l.slice(3).trim().replace(/^"|"$/g, '').startsWith(`${logRoot}/`) && l.slice(3).trim() !== `${logRoot}/`)
+        .filter((l) => l.trim() !== '' && !own(l.slice(3).trim().replace(/^"|"$/g, '')))
         .join('\n')
 }
 
@@ -66,7 +72,7 @@ export type RemoteTagRefs = { refs: Map<string, string> } | { error: string }
  *  because `ls-remote <pattern>` drops the peeled `^{}` line and leaves only
  *  the tag OBJECT id, which differs between two tags of the same commit. */
 export function remoteTagRefs(root: string, remote: string): RemoteTagRefs {
-    const p = Bun.spawnSync(['git', 'ls-remote', '--tags', remote], { cwd: root, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
+    const p = Bun.spawnSync([gitBin(), 'ls-remote', '--tags', remote], { cwd: root, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } })
     if (p.exitCode !== 0) return { error: `${p.stderr.toString()}${p.stdout.toString()}`.trim().split('\n').at(-1) ?? 'ls-remote failed' }
     const refs = new Map<string, string>()
     for (const line of p.stdout.toString().split('\n')) {
@@ -134,7 +140,7 @@ export function mergeProbe(root: string, tip: string, from: string): MergeProbe
     return { state: 'unknown', reason: `${reason} (needs git 2.38+)` }
 }
 
-/** local tags matching any of the release units' tag shapes that the remote
+/** local tags matching any of the releasing units' tag shapes that the remote
  *  does not have. A stranded tag is invisible where he looks (GitHub), so it
  *  is a failure, not a note. */
 export function strandedTags(p: { root: string; globs: string[]; remote: string }): { stranded: string[]; local: string[] } | { error: string } {

package/src/release/run-bump.ts

@@ -33,10 +33,11 @@ import { declaredKind, hasUnreleasedNotes, promoteUnreleased } from './changelog
 import { deriveRemote, dirtyPathList, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
 import { unitBlockers } from './unit-gate.ts'
 import { releaseScope } from './release-scope.ts'
-import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
+import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, unknownUnit, type ReleaseUnit } from './units.ts'
 import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { nestedIn, nestedRefusal } from '../core/nesting.ts'
+import { LAYOUT } from '../core/layout.ts'
 
 export type BumpKind = 'major' | 'minor' | 'patch'
 
@@ -234,7 +235,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     if (o.all !== true) {
         const id = o.unit ?? 'root'
         if (unitById(onDisk.units, id) == null) {
-            print(`FAIL: no release unit '${id}' — known units: ${onDisk.units.map((x) => x.id).join(', ')}`)
+            print(`FAIL: ${unknownUnit(onDisk, id)}`)
             print('      fix: shipkit releases')
             return 1
         }
@@ -249,7 +250,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
 
     // surfaces the toolkit itself rewrites on gate runs, safe to auto-commit
     const machineWrittenPaths = (r: string, c: RepoConfig): Set<string> => {
-        const s = new Set(['STATUS.md'])
+        const s = new Set<string>([LAYOUT.status])
         if (c.docsBase != null) {
             const base = c.docsBase.startsWith('~/') ? join(homedir(), c.docsBase.slice(2)) : c.docsBase
             const page = join(base, 'build/shipkit/local-projects.md')
@@ -372,7 +373,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     } else {
         const id = o.unit ?? 'root'
         const u = unitById(all, id)
-        if (u == null) return fail(`no release unit '${id}' after the merge — known units: ${all.map((x) => x.id).join(', ')}`, 'shipkit releases')
+        if (u == null) return fail(`${unknownUnit(resolved, id)} (after the merge)`, 'shipkit releases')
         picked = [u]
     }
 
@@ -430,7 +431,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind |
     // gates cost N times as much and prove the same thing. Frozen, and fatal
     // on non-blocking failures when the repo declared requireHealthy.
     // releaseUnit then skips it, because bump already proved this exact tree.
-    if ((await runReleaseGate(root, config, print, { fix: true })) !== 0) return fail('ci gate is red on the merged result — fix it, then bump')
+    if ((await runReleaseGate(root, config, print, { fix: true, units: picked })) !== 0) return fail('ci gate is red on the merged result — fix it, then bump')
     // the gate's fix pass can rewrite files. writing a version on top of that
     // produces a version commit that excludes the rewrite and a release that
     // then refuses on a dirty tree, which is a half-released repo.

package/src/release/run-release.ts

@@ -13,9 +13,10 @@ import { extractChangelogSection } from './changelog.ts'
 import { deriveRemote, dirtyPaths, git, remoteTagState, tagExistsLocally, type RemoteTagState } from './git-facts.ts'
 import { releaseScope } from './release-scope.ts'
 import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
-import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
+import { formatUnitError, resolveUnits, unitById, unknownUnit, type ReleaseUnit } from './units.ts'
 import type { RepoConfig } from '../repo-config.ts'
 import { nestedIn, nestedRefusal } from '../core/nesting.ts'
+import { declaredTestUnits, testCheckId } from '../suite/test-units.ts'
 
 // adding a FOURTH knob here is the signal that this shape wants rethinking
 // rather than another key (meta/gaps.md, release-path config keys accreting)
@@ -29,7 +30,7 @@ export type ReleaseConfig = {
     /** publish the ROOT unit to npm. Default: its package.json is not private.
      *  A private package NEVER publishes, whatever this says. */
     npm?: boolean
-    /** argv printing an npm auth token on stdout (e.g. a secret-manager read).
+    /** argv printing an npm auth token on stdout, as in a secret-manager read.
      *  Absent = rely on ambient npm auth. Never put a token in config.
      *  Repo-wide: one account publishes every unit. */
     npmTokenCommand?: string[]
@@ -43,10 +44,9 @@ export type ReleaseConfig = {
     /** repo-relative tsconfig for the ROOT unit's own typecheck (default
      *  '<root>/tsconfig.json' when it exists) */
     tsconfig?: string
-    /** task ids the release gate skips. A monorepo's repo-wide task (every
-     *  package's suite, a full matrix build) re-proves for six units what the
-     *  released unit's own gate already proved for one. Naming them here is
-     *  the repo saying which tasks are about the REPO rather than the release. */
+    /** check ids the release gate skips: a repo-wide task (a full matrix
+     *  build) that is about the REPO rather than the release. Which unit test
+     *  checks a release runs is not this key's: → build/shipkit/units.md */
     skipTasks?: string[]
     /** `shipkit bump` run from a feature branch merges it into the release
      *  branch first, with a merge commit. Default true. A branch is a GATE, so
@@ -106,7 +106,7 @@ export type ReleaseOpts = {
  *  while the rules ran from another downgrades a blocking failure to a warning.
  *
  *  it also runs the FULL test tier, which `shipkit ci` skips while you work. */
-export async function runReleaseGate(root: string, config: RepoConfig, print: (l: string) => void, o: { fix?: boolean } = {}): Promise<number> {
+export async function runReleaseGate(root: string, config: RepoConfig, print: (l: string) => void, o: { fix?: boolean; units?: ReleaseUnit[] } = {}): Promise<number> {
     return await runCi(root, {
         fix: o.fix ?? false,
         frozen: true,
@@ -127,18 +127,32 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         // a DNS provider answers, and asking spends an API call per publish.
         // requireHealthy is the repo saying it wants them fatal, so then they run.
         onlyBlockingChecks: config.release?.requireHealthy !== true,
-        skipTaskIds: config.release?.skipTasks ?? [],
+        // a sibling unit's suite proves nothing about a sub-unit's tarball: each
+        // unit's test check runs when THAT unit ships, or when the root does
+        skipTaskIds: [...(config.release?.skipTasks ?? []), ...otherUnitTests(config, o.units)],
         failOnAdvisory: config.release?.requireHealthy === true,
         print: (l) => print(`      ${l}`),
     })
 }
 
+/** the test checks of every sub-unit this release does not ship. No list
+ *  given means the caller did not say, and every unit's suite runs. The root
+ *  depends on what it contains, so a release that ships it runs them all. A
+ *  `release: false` unit is never skipped: it ships nothing of its own, so its
+ *  suites exist to prove something that does, and nothing says which */
+export function otherUnitTests(config: RepoConfig, shipping: ReleaseUnit[] | undefined): string[] {
+    if (shipping == null || shipping.some((u) => u.id === 'root')) return []
+    const ids = new Set(shipping.map((u) => u.id))
+    return declaredTestUnits(config.units).filter((u) => u.releases && !ids.has(u.id)).map((u) => testCheckId(u.id))
+}
+
 /** `shipkit release [unit]` — resolve the unit, then ship it. */
 export async function runRelease(root: string, config: RepoConfig, o: ReleaseOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
     const nested = nestedIn(root)
     if (nested != null) { print(`FAIL: ${nestedRefusal(nested)}`); return 1 }
-    const { units, errors } = resolveUnits(root, config)
+    const resolution = resolveUnits(root, config)
+    const { units, errors } = resolution
     const id = o.unit ?? 'root'
     // only THIS unit's own resolution has to hold: a broken sibling is not a
     // reason to refuse a release of something that resolves fine
@@ -146,7 +160,7 @@ export async function runRelease(root: string, config: RepoConfig, o: ReleaseOpt
     if (mine.length > 0) { for (const e of mine) print(`FAIL: ${formatUnitError(e)}`); return 1 }
     const unit = unitById(units, id)
     if (unit == null) {
-        print(`FAIL: no release unit '${id}' — known units: ${units.map((u) => u.id).join(', ')}`)
+        print(`FAIL: ${unknownUnit(resolution, id)}`)
         print('      fix: shipkit releases')
         return 1
     }
@@ -254,7 +268,7 @@ export async function releaseUnit(root: string, config: RepoConfig, unit: Releas
     if (o.skipGate === true)
         print(o.skipGateReason != null ? `ok: ci gate ${o.skipGateReason}` : 'WARN ci gate SKIPPED by --skip-gate — publishing unverified')
     else {
-        if ((await runReleaseGate(root, config, print)) !== 0) { print('FAIL: ci gate is red — fix it, commit, then release'); return 1 }
+        if ((await runReleaseGate(root, config, print, { units: [unit] })) !== 0) { print('FAIL: ci gate is red — fix it, commit, then release'); return 1 }
         // frozen is a declaration, not a guarantee: any check may still write.
         // npm packs the DIRECTORY, so a rewrite here would publish a tarball
         // that exists in no commit while the tag describes another tree.

package/src/release/run-releases.ts

@@ -1,4 +1,4 @@
-// `shipkit releases` — where every release unit actually stands. Report only:
+// `shipkit releases` — where every releasing unit actually stands. Report only:
 // it never gates, never writes, and exits 0 even when everything is drifted,
 // because it exists to end the "what is published and what is not" question,
 // not to add another red light.
@@ -249,6 +249,6 @@ export function renderReports(reports: UnitReport[], o: { remoteError?: string |
     // once rather than once per cell
     if (o.offline === true) lines.push('note: --offline, so npm, the remote and gh were not read (the ? cells)')
     const subs = reports.length - 1
-    lines.push(`note: ${reports.length} release unit(s) — the repo root${subs > 0 ? ` + ${subs} declared` : ' only, nothing else declared'}`)
+    lines.push(`note: ${reports.length} releasing unit(s) — the repo root${subs > 0 ? ` + ${subs} declared` : ' only, nothing else declared'}`)
     return lines
 }