rvlib-shipkit 1.9.0 → 2.0.0

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(', ')