rvlib-shipkit 1.8.0 → 2.0.0

package/src/cli/cmd_Prose.ts

@@ -1,74 +0,0 @@
-// shipkit prose — the STE checker as a command, so a writer can run it on one
-// file while drafting instead of waiting for the gate. Rule SK014 runs the
-// same module over the repo's declared scope.
-import { Command, Option } from 'clipanion'
-import { loadRepoConfig } from '../repo-config.ts'
-import { classSummary, proseLines, runProseCheck } from '../prose/run-prose.ts'
-import { CheckCtx } from '../core/check-ctx.ts'
-
-export class ProseCommand extends Command {
-    static override paths = [['prose']]
-
-    static override usage = Command.Usage({
-        category: 'Health',
-        description: 'STE prose check (identity/writing-voice.md): mechanical fixes, hard violations, soft warnings',
-        examples: [
-            ['every file this repo declares as prose', 'sk prose'],
-            ['one file while drafting', 'sk prose wiki/build/shipkit.md'],
-            ['apply every mechanical rewrite', 'sk prose --fix'],
-            ['the procedural 20-word limit', 'sk prose --strict'],
-            ['machine-readable', 'sk prose --json'],
-        ],
-    })
-
-    // `targets`, not `paths`: clipanion's Command owns the static `paths`
-    targets = Option.Rest()
-    fix = Option.Boolean('--fix', false, { description: 'apply the mechanical rewrites (contractions, latin, one-to-one substitutions, empty words)' })
-    json = Option.Boolean('--json', false, { description: 'machine-readable { files, byClass, hits }' })
-    strict = Option.Boolean('--strict', false, { description: 'the 20-word procedural sentence limit instead of the 25-word descriptive one' })
-    cap = Option.String('--cap', '25', { description: 'how many hit lines to print before the per-class totals' })
-
-    async execute(): Promise<number> {
-        const root = process.cwd()
-        const config = await loadRepoConfig(root)
-        const cfg = { ...(config?.prose ?? {}) }
-        if (this.strict) cfg.strict = true
-        const explicit = this.targets.length > 0
-        if ((cfg.include ?? []).length === 0 && !explicit) {
-            this.context.stdout.write(
-                `skip: this repo declares no prose scope — add \`prose: { include: ['**/*.md'], exempt: [...] }\` to repo.config.ts (identity/writing-voice.md)\n`,
-            )
-            return 0
-        }
-        const r = runProseCheck({ c: CheckCtx.open({ root, config }), config: cfg, paths: explicit ? this.targets : undefined, fix: this.fix })
-        if (this.json) {
-            // every hit carries its file: a flat list without one cannot be
-            // acted on, and the grouping is already in byFile
-            const hits = r.byFile.flatMap((f) => f.hits.map((h) => ({ file: f.file, ...h })))
-            this.context.stdout.write(`${JSON.stringify({ files: r.files, byTier: r.byTier, byClass: r.byClass, fixed: r.fixed, hits }, null, 2)}\n`)
-            return r.byTier.fix + r.byTier.hard > 0 ? 1 : 0
-        }
-        const w = (l: string) => this.context.stdout.write(`${l}\n`)
-        // a declared scope that resolves to nothing reads as `0 file(s)
-        // STE-clean`, the same green a clean repo gets, over a check that
-        // inspected no file at all (rule SK014 warns on the same fact)
-        if (!explicit && r.files === 0) {
-            w(`WARN prose scope matches no file: ${(cfg.include ?? []).join(', ')} — declared and inspecting nothing`)
-            w('      fix: fix the globs in repo.config.ts prose.include (or its exempt list), or drop the key to opt out')
-            return 0
-        }
-        if (r.fixed.length > 0) w(`ok: rewrote ${r.fixed.length} file(s)`)
-        for (const l of proseLines(r, { cap: Number(this.cap) || 25 })) w(l)
-        const blocking = r.byTier.fix + r.byTier.hard
-        const baseline = cfg.baseline
-        const overBaseline = baseline != null && r.byTier.soft > baseline
-        if (blocking === 0 && !overBaseline) {
-            w(`ok: ${r.files} file(s) STE-clean${r.byTier.soft > 0 ? `, ${r.byTier.soft} soft warning(s)${baseline != null ? ` (baseline ${baseline})` : ''}` : ''}`)
-            return 0
-        }
-        if (blocking > 0)
-            w(`FAIL: ${blocking} STE violation(s) in ${r.byFile.length} file(s) — ${classSummary(r)}${r.fixable > 0 ? `\n      fix: shipkit prose --fix clears ${r.fixable} of them` : ''}`)
-        if (overBaseline) w(`FAIL: ${r.byTier.soft} soft hits, above this repo's baseline of ${baseline} — lower the count, or move the baseline down in repo.config.ts`)
-        return 1
-    }
-}

package/src/prose/prose-view.ts

@@ -1,90 +0,0 @@
-// The SK014 page's data: every hit of the prose check, grouped by the word
-// (or the rule, for the classes that judge a shape), noisiest first, each hit
-// with its file, its line and the sentence around it. It runs the SAME
-// module the rule runs, over the same config, so the page and the gate can
-// never count differently.
-import type { CheckCtx } from '../core/check-ctx.ts'
-import type { RepoConfig } from '../repo-config.ts'
-import { runProseCheck } from './run-prose.ts'
-import type { ProseClass, ProseHit, ProseTier, ProseWords } from './ste.ts'
-
-export type ProseViewHit = {
-    file: string
-    line: number
-    /** the source line around the hit, clipped to a readable width */
-    excerpt: string
-    /** where the hit sits inside `excerpt`, [from, to) */
-    mark: [number, number]
-    why: string
-    fix?: string
-}
-
-export type ProseGroup = {
-    /** `<class>:<word>` for a word hit, `<class>` for a shape */
-    key: string
-    cls: ProseClass
-    tier: ProseTier
-    /** the dictionary word or phrase an allow entry names; null on a shape */
-    word: string | null
-    count: number
-    hits: ProseViewHit[]
-}
-
-export type ProseView = {
-    /** false when the repo declares no prose scope: the rule skips it */
-    scoped: boolean
-    files: number
-    total: number
-    byTier: Record<ProseTier, number>
-    groups: ProseGroup[]
-    /** the repo's own lists as the config loads them */
-    words: ProseWords
-}
-
-/** how much of a long line the page shows on each side of the hit */
-const SIDE = 70
-
-/** the source line a hit sits on, clipped around it, with the hit's span
- *  inside the clip. A hit that runs past its line (a long sentence, a
- *  paragraph) marks to the end of the line */
-export function excerptOf(text: string, h: Pick<ProseHit, 'start' | 'end'>): { excerpt: string; mark: [number, number] } {
-    const from = text.lastIndexOf('\n', h.start - 1) + 1
-    const nl = text.indexOf('\n', h.start)
-    const to = nl < 0 ? text.length : nl
-    const line = text.slice(from, to)
-    let a = h.start - from
-    let b = Math.min(h.end, to) - from
-    let lo = Math.max(0, a - SIDE)
-    const hi = Math.min(line.length, Math.max(b, a) + SIDE)
-    // a leading indent is noise in a one line quote
-    while (lo < a && /\s/.test(line[lo]!)) lo++
-    const head = lo > 0 ? '…' : ''
-    const tail = hi < line.length ? '…' : ''
-    const excerpt = head + line.slice(lo, hi).trimEnd() + tail
-    a = a - lo + head.length
-    b = Math.min(b - lo + head.length, excerpt.length - tail.length)
-    return { excerpt, mark: [a, Math.max(a, b)] }
-}
-
-export function proseView(c: Pick<CheckCtx, 'root' | 'read' | 'list' | 'write'>, config: RepoConfig): ProseView {
-    const cfg = config.prose
-    const empty: ProseView = { scoped: false, files: 0, total: 0, byTier: { fix: 0, hard: 0, soft: 0 }, groups: [], words: cfg?.words ?? {} }
-    if (cfg == null || (cfg.include ?? []).length === 0) return empty
-    const r = runProseCheck({ c, config: cfg, keepText: true })
-    const groups = new Map<string, ProseGroup>()
-    for (const f of r.byFile)
-        for (const h of f.hits) {
-            const key = h.word == null ? h.cls : `${h.cls}:${h.word}`
-            let g = groups.get(key)
-            if (g == null) {
-                g = { key, cls: h.cls, tier: h.tier, word: h.word ?? null, count: 0, hits: [] }
-                groups.set(key, g)
-            }
-            g.count++
-            const ex = excerptOf(f.text ?? '', h)
-            g.hits.push({ file: f.file, line: h.line, ...ex, why: h.why, ...(h.fix == null ? {} : { fix: h.fix }) })
-        }
-    // the noisiest first: one allow entry on the top word clears the most
-    const sorted = [...groups.values()].sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
-    return { scoped: true, files: r.files, total: r.hits.length, byTier: r.byTier, groups: sorted, words: cfg.words ?? {} }
-}

package/src/prose/run-prose.ts

@@ -1,187 +0,0 @@
-// `shipkit prose` — the file-walking half of the STE checker. The judgement
-// lives in ste.ts; this module resolves WHICH files a repo puts in scope,
-// prints the wire lines, and applies the mechanical fixes.
-//
-// Scope is repo knowledge, never a hardcoded path list: a repo declares
-// `prose: { include, exempt }` in repo.config.ts. A repo that declares
-// nothing is not checked, and the rule says so instead of failing a repo
-// that never opted in.
-//
-// It reads and writes ONLY through the check context it is handed, so rule
-// SK014 is cached on the scope's listings and the files in it.
-import { isAbsolute, relative, resolve } from 'path'
-import type { CheckCtx } from '../core/check-ctx.ts'
-import { checkProse, fixProse, tierOf, type ProseClass, type ProseHit, type ProseTier, type ProseWords } from './ste.ts'
-
-/** what the walker reads and writes through: a check context */
-export type ProseDisk = Pick<CheckCtx, 'root' | 'read' | 'list' | 'write'>
-
-export type ProseConfig = {
-    /** globs (repo-relative) that ARE house prose. Absent = the repo is not checked. */
-    include?: string[]
-    /** globs never checked: journals, archives, upstream snapshots, generated files */
-    exempt?: string[]
-    /** classes this repo does not check, with the reason living in repo.config.ts */
-    allow?: ProseClass[]
-    /** the 20-word procedural limit instead of the 25-word descriptive one */
-    strict?: boolean
-    /** this repo's own word lists over the house dictionary: `allow` drops
-     *  every hit on a word or phrase, `ban` refuses an extra one (a hard hit,
-     *  with its replacement). They bind this repo only, and the hub's SK014
-     *  page writes them through a managed block inside this object */
-    words?: ProseWords
-    /** soft-tier ratchet: the count this repo is allowed to carry. The gate
-     *  fails ABOVE it, so the number can only go down. Absent is the default,
-     *  and it means soft hits warn in `shipkit prose` and never reach a gate
-     *  or an attention surface. A four-digit count nobody can act on is worse
-     *  than no number at all. */
-    baseline?: number
-}
-
-export type FileReport = {
-    file: string
-    hits: ProseHit[]
-    /** the file as it was judged, kept only when the caller asked, so a page
-     *  can quote the line around each hit without reading the file twice */
-    text?: string
-}
-
-export type ProseReport = {
-    files: number
-    hits: ProseHit[]
-    byFile: FileReport[]
-    byTier: Record<ProseTier, number>
-    byClass: Record<string, number>
-    fixable: number
-    /** files rewritten by a --fix run */
-    fixed: string[]
-    scoped: boolean // did this repo declare any include globs?
-}
-
-const DEFAULT_EXEMPT = ['**/node_modules/**', '**/CHANGELOG.md', '**/dist/**', '**/.git/**']
-
-/** a generated file is not house prose, and rewriting it loses the change on
- *  the next render */
-const isGenerated = (text: string): boolean => text.slice(0, 400).includes('<!-- generated')
-
-/** an explicitly named path, resolved against the repo and REFUSED when it
- *  lands outside: `--fix` writes, and a checker that rewrites files outside
- *  the repo it was pointed at is a much worse tool than one that says no. */
-export function explicitPath(root: string, p: string): string {
-    const abs = isAbsolute(p) ? p : resolve(root, p)
-    const rel = relative(root, abs)
-    if (rel === '' || rel.startsWith('..')) throw new Error(`FAIL ${p} is outside ${root} — shipkit prose only reads and writes inside the repo`)
-    return rel
-}
-
-/** does `path` match `pattern` under the dot rule: a hidden segment (one
- *  starting with a dot) only where the pattern names a hidden segment itself,
- *  never inside a `**` or under a wildcard segment */
-export function hiddenAllowed(pattern: string, path: string): boolean {
-    const pat = pattern.split('/')
-    const segs = path.split('/')
-    const hidden = (s: string): boolean => s.startsWith('.') && s !== '.' && s !== '..'
-    const star = pat.indexOf('**')
-    const head = star === -1 ? pat : pat.slice(0, star)
-    const tail = star === -1 ? [] : pat.slice(pat.lastIndexOf('**') + 1)
-    for (let i = 0; i < segs.length; i++) {
-        if (!hidden(segs[i]!)) continue
-        const fromEnd = segs.length - 1 - i
-        const p = i < head.length ? head[i] : fromEnd < tail.length ? tail[tail.length - 1 - fromEnd] : undefined
-        if (p == null || !p.startsWith('.')) return false
-    }
-    return true
-}
-
-/** the files in scope: what git sees (tracked, or untracked and not ignored)
- *  matching an include glob, the dot rule applied, minus every exempt glob */
-export function proseFiles(d: Pick<ProseDisk, 'list'>, cfg: ProseConfig): string[] {
-    const include = cfg.include ?? []
-    if (include.length === 0) return []
-    const exempt = [...DEFAULT_EXEMPT, ...(cfg.exempt ?? [])].map((g) => new Bun.Glob(g))
-    const seen = new Set<string>()
-    for (const pattern of include)
-        for (const rel of d.list(pattern)) {
-            if (!hiddenAllowed(pattern, rel)) continue
-            if (exempt.some((g) => g.match(rel))) continue
-            seen.add(rel)
-        }
-    return [...seen].sort()
-}
-
-export function runProseCheck(o: { c: ProseDisk; config: ProseConfig; paths?: string[]; fix?: boolean; keepText?: boolean }): ProseReport {
-    const cfg = o.config
-    const d = o.c
-    const files = o.paths != null && o.paths.length > 0 ? o.paths.map((p) => explicitPath(d.root, p)) : proseFiles(d, cfg)
-    const explicit = o.paths != null && o.paths.length > 0
-    const opts = { allow: cfg.allow, strict: cfg.strict, words: cfg.words }
-    const byFile: FileReport[] = []
-    const hits: ProseHit[] = []
-    const fixed: string[] = []
-    for (const rel of files) {
-        let text: string | null
-        try {
-            text = d.read(rel)
-        } catch (e) {
-            text = null
-            if (explicit) throw new Error(`FAIL cannot read ${rel} — ${String(e)}`)
-        }
-        if (text == null) {
-            // a path a HUMAN typed that cannot be read is a loud failure. A
-            // path the listing produced can vanish between the scan and the
-            // read, and skipping that one is right.
-            if (explicit) throw new Error(`FAIL cannot read ${rel} — no such file`)
-            continue
-        }
-        if (isGenerated(text)) continue
-        if (o.fix === true) {
-            const out = fixProse(text, opts)
-            if (out.applied > 0) {
-                d.write(rel, out.text)
-                fixed.push(rel)
-                text = out.text
-            }
-        }
-        const fh = checkProse(text, opts)
-        if (fh.length > 0) byFile.push({ file: rel, hits: fh, ...(o.keepText === true ? { text } : {}) })
-        hits.push(...fh)
-    }
-    const byTier: Record<ProseTier, number> = { fix: 0, hard: 0, soft: 0 }
-    const byClass: Record<string, number> = {}
-    for (const h of hits) {
-        byTier[h.tier]++
-        byClass[h.cls] = (byClass[h.cls] ?? 0) + 1
-    }
-    return {
-        files: files.length,
-        hits,
-        byFile,
-        byTier,
-        byClass,
-        fixable: hits.filter((h) => h.fix != null).length,
-        fixed,
-        scoped: (cfg.include ?? []).length > 0,
-    }
-}
-
-/** one line per hit, capped: a first STE pass on a real repo finds hundreds,
- *  and a wall of them hides the mechanical ones that `--fix` clears in a
- *  second. The per-class totals below the cap keep the report complete. */
-export function proseLines(r: ProseReport, o: { cap?: number; tiers?: ProseTier[] } = {}): string[] {
-    const cap = o.cap ?? 25
-    const tiers = new Set(o.tiers ?? (['fix', 'hard', 'soft'] as ProseTier[]))
-    const shown = r.hits.filter((h) => tiers.has(h.tier))
-    const out: string[] = []
-    const fileOf = new Map<ProseHit, string>()
-    for (const f of r.byFile) for (const h of f.hits) fileOf.set(h, f.file)
-    for (const h of shown.slice(0, cap))
-        out.push(`${fileOf.get(h) ?? '?'}:${h.line} [${h.cls}] ${JSON.stringify(h.text.trim())} — ${h.why}${h.fix != null ? ` (--fix writes ${JSON.stringify(h.fix.trim())})` : ''}`)
-    if (shown.length > cap) out.push(`… and ${shown.length - cap} more`)
-    return out
-}
-
-export const classSummary = (r: ProseReport): string =>
-    Object.entries(r.byClass)
-        .sort((a, b) => b[1] - a[1])
-        .map(([c, n]) => `${c} ${n}${tierOf(c as ProseClass) === 'soft' ? '' : '!'}`)
-        .join(', ')