rvlib-shipkit 2.1.1 → 2.3.0

package/src/cli/cmd_Commands.ts

@@ -1,8 +1,11 @@
 // the binary describing itself, in markdown. a hand-copied command list
 // drifts the moment a flag changes, and then teaches commands that do not
-// exist. rendering the live registry makes the doc a build artifact.
+// exist. rendering the live registry makes the doc a build artifact. One
+// renderer for every binary: shipkit's own page and each project CLI's pages
+// (the kit in cli/kit/) come out of these functions.
 import { Command, Option } from 'clipanion'
 import { spliceMarkedBlock } from '../core/doc-block.ts'
+import { type Essential, type Film, marksOf, ROW_OF, runText } from './kit/verb.ts'
 
 export type CommandOption = { definition: string; description: string }
 export type CommandRow = {
@@ -12,6 +15,15 @@ export type CommandRow = {
     usage: string
     options: CommandOption[]
     examples: [string, string][]
+    /** a filmable command (cli/kit/verb.ts): takes --out, a clip also --seconds */
+    film?: Film
+    /** a filmable command's take version and length (build/trailer.md, Film lines) */
+    version?: number | string
+    length?: 'own'
+    /** listed on the essentials page */
+    essential?: Essential
+    /** what a kit row runs */
+    runs?: string
 }
 
 export type Definition = {
@@ -30,68 +42,148 @@ export const DESCRIPTION_MAX = 100
 // clipanion renders a value placeholder as `#0`, which nobody can type
 const clean = (s: string | null | undefined): string => (s ?? '').trim().replace(/\s+/g, ' ').replace(/ #\d+\b/g, ' <value>')
 
+/** the names a binary answers to: shipkit is also `sk` */
+const namesOf = (bin: string): string[] => (bin === 'sk' || bin === 'shipkit' ? ['shipkit', 'sk'] : [bin])
+
+const stripName = (bin: string, path: string): string => {
+    for (const n of namesOf(bin)) if (path.startsWith(`${n} `)) return path.slice(n.length + 1)
+    return path
+}
+
 /** rows from the live registry, builtins dropped, sorted by category then path.
  *  clipanion splits what we need across two calls: the plain form carries the
  *  examples, the detailed form carries the flags. Merge by path, or the page
  *  ends up showing a command with no arguments, which is the state that sends
- *  an agent to `--help` before it can act. */
-export function commandRows(plain: Definition[], detailed: Definition[] = []): CommandRow[] {
+ *  an agent to `--help` before it can act. `classes` (the registered command
+ *  classes) add each command's marks: film, essential, what a row runs */
+export function commandRows(plain: Definition[], detailed: Definition[] = [], bin = 'sk', classes: readonly { paths?: string[][] }[] = []): CommandRow[] {
     const flagsByPath = new Map(detailed.map((d) => [d.path, d.options ?? []]))
+    const classByPath = new Map<string, object>()
+    for (const c of classes) for (const p of c.paths ?? []) classByPath.set(p.join(' '), c)
     return plain
-        .filter((d) => !/^(shipkit|sk) (--help|-h|--version|-v)$/.test(d.path))
-        .map((d) => ({
-            path: d.path.replace(/^(shipkit|sk) /, ''),
-            category: clean(d.category) || 'Other',
-            // verbatim from the CLI so the doc cannot say something it does not
-            description: clean(d.description),
-            usage: clean(d.usage),
-            options: (flagsByPath.get(d.path) ?? [])
-                .map((o) => ({ definition: clean(o.definition), description: clean(o.description) }))
-                .filter((o) => o.definition !== ''),
-            examples: (d.examples ?? []).map(([label, cmd]) => [clean(label), clean(cmd)] as [string, string]),
-        }))
+        .filter((d) => !/^(--help|-h|--version|-v)$/.test(stripName(bin, d.path)))
+        .map((d) => {
+            const path = stripName(bin, d.path)
+            const c = classByPath.get(path)
+            const row: CommandRow = {
+                path,
+                category: clean(d.category) || 'Other',
+                // verbatim from the CLI so the doc cannot say something it does not
+                description: clean(d.description),
+                usage: clean(d.usage),
+                options: (flagsByPath.get(d.path) ?? [])
+                    .map((o) => ({ definition: clean(o.definition), description: clean(o.description) }))
+                    .filter((o) => o.definition !== ''),
+                examples: (d.examples ?? []).map(([label, cmd]) => [clean(label), clean(cmd)] as [string, string]),
+            }
+            if (c != null) {
+                const m = marksOf(c)
+                if (m.film != null) row.film = m.film
+                if (m.version != null) row.version = m.version
+                if (m.length != null) row.length = m.length
+                if (m.essential != null) row.essential = m.essential
+                const v = ROW_OF.get(c)
+                if (v != null) row.runs = runText(v.run)
+            }
+            return row
+        })
         .sort((a, b) => a.category.localeCompare(b.category) || a.path.localeCompare(b.path))
 }
 
-/** the markdown block, loaded into every agent's context at start: per
- *  command its invocation with every flag, one line of description, then its
- *  examples. What a flag does and the long text are `sk <command> --help`. */
-export function renderMarkdown(rows: CommandRow[]): string {
+/** a command's invocation as an agent types it */
+const signature = (r: CommandRow, bin: string): string => r.usage.replace(/^\$0/, bin).trim() || `${bin} ${r.path}`
+
+/** the markdown block: per command its invocation with every flag, one line
+ *  of description, what a row runs, then its examples. What a flag does and
+ *  the long text are `<bin> <command> --help`. */
+export function renderMarkdown(rows: CommandRow[], bin = 'sk'): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
         if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
-        const sig = r.usage.replace(/^\$0/, 'sk').trim() || `sk ${r.path}`
         const flags = r.options.map((o) => `[${o.definition}]`).join(' ')
+        const sig = signature(r, bin)
         // one line per bullet: a description on its own indented line reads as
         // hard-wrapped prose to the house lint
-        out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}`)
+        out.push(`- \`${sig}${flags === '' ? '' : ` ${flags}`}\` — ${r.description}${r.runs != null ? ` → \`${r.runs}\`` : ''}${r.film != null ? ` (films a ${r.film})` : ''}`)
         for (const [label, cmd] of r.examples) out.push(`  - ${label}: \`${cmd}\``)
     }
     return out.join('\n').trim()
 }
 
 /** the eager form: one line per command, its positional arguments and its
- *  description. Flags and examples are `sk <command> --help`, so a page every
+ *  description. Flags and examples are `<bin> <command> --help`, so a page every
  *  session loads costs a line per command, not a screen */
-export function renderCompact(rows: CommandRow[]): string {
+export function renderCompact(rows: CommandRow[], bin = 'sk'): string {
     const out: string[] = []
     let cat = ''
     for (const r of rows) {
         if (r.category !== cat) { cat = r.category; out.push(`\n### ${cat}\n`) }
-        const sig = r.usage.replace(/^\$0/, 'sk').replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `sk ${r.path}`
+        const sig = r.usage.replace(/^\$0/, bin).replace(/\s+\[(?:-|<\w+>)[^\]]*\]/g, '').trim() || `${bin} ${r.path}`
         out.push(`- \`${sig}\` — ${r.description}`)
     }
     return out.join('\n').trim()
 }
 
-export const BEGIN = '<!-- shipkit:commands -->'
-export const END = '<!-- /shipkit:commands -->'
+/** the page every session loads: per category its everyday commands, a few
+ *  examples, and how to list the rest. Generated whole */
+export function renderEssentials(rows: CommandRow[], bin: string, command: string): string {
+    const out = [`# ${bin}: the everyday commands`, '', `Generated by \`${command}\` from the commands marked \`essential\`. Every command: \`${bin}\`, \`${bin} <family>\`, \`${bin} <command> --help\`. \`${bin} <words>\` runs as \`bun run cli <words>\` from the repo root, and as \`${bin}\` anywhere once \`bun link\` ran there.`]
+    const first = (r: CommandRow): string => r.path.split(' ')[0]!
+    const quiet: string[] = []
+    for (const category of [...new Set(rows.map((r) => r.category))]) {
+        const all = rows.filter((r) => r.category === category)
+        const rest = [...new Set(all.map(first))]
+            .map((w) => [w, all.filter((r) => first(r) === w && r.essential == null).length] as const)
+            .filter(([, n]) => n > 0)
+            .map(([w, n]) => `\`${bin} ${w}${all.some((r) => r.path === w) ? ' --help' : ''}\` (${n} command${n === 1 ? '' : 's'})`)
+        const mine = all.filter((r) => r.essential != null)
+        if (mine.length === 0) { quiet.push(...rest); continue }
+        out.push('', `## ${category}${rest.length > 0 ? ` (more: ${rest.join(', ')})` : ''}`, '')
+        for (const r of mine) {
+            const e = r.essential!
+            out.push(`- \`${bin} ${r.path}${e.args != null ? ` ${e.args}` : ''}\`: ${r.description}`)
+            for (const [label, cmd] of r.examples.slice(0, e.examples ?? 0)) out.push(`  - \`${cmd}\`: ${label}`)
+        }
+    }
+    if (quiet.length > 0) out.push('', `## The other families: ${quiet.join(', ')}`)
+    return `${out.join('\n')}\n`
+}
+
+/** what a project CLI's registry must hold for its pages and its listing to
+ *  teach right: a category, a description under the cap, and an example that
+ *  starts with the command's own words. One line per breach */
+export function shapeProblems(rows: CommandRow[], bin: string): string[] {
+    const out: string[] = []
+    for (const r of rows) {
+        if (r.category === 'Other') out.push(`${bin} ${r.path}: no category`)
+        if (r.description === '') out.push(`${bin} ${r.path}: no description`)
+        else if (r.description.length > DESCRIPTION_MAX) out.push(`${bin} ${r.path}: description over ${DESCRIPTION_MAX} characters (the rest goes in details)`)
+        if (!r.examples.some(([, cmd]) => cmd === `${bin} ${r.path}` || cmd.startsWith(`${bin} ${r.path} `))) out.push(`${bin} ${r.path}: no example starting with \`${bin} ${r.path}\``)
+    }
+    return out
+}
+
+/** the markers a page carries around the generated block: shipkit keeps its
+ *  historical name, a project CLI uses its own */
+export const markersFor = (bin: string): [string, string] => {
+    const n = namesOf(bin).includes('shipkit') ? 'shipkit' : bin
+    return [`<!-- ${n}:commands -->`, `<!-- /${n}:commands -->`]
+}
+
+export const [BEGIN, END] = markersFor('sk')
 
 /** replace the marked block in a host file. Returns null when the markers are
  *  missing, so a renamed or hand-mangled host fails loud instead of silently
  *  writing nothing. */
-export const spliceBlock = (host: string, block: string): string | null => spliceMarkedBlock(host, block, BEGIN, END)
+export const spliceBlock = (host: string, block: string, bin = 'sk'): string | null => spliceMarkedBlock(host, block, ...markersFor(bin))
+
+/** the page a project CLI's `--out` creates when it is missing: a title, how
+ *  it is made, and the markers the block goes between */
+export const newCommandsPage = (bin: string, path: string): string => {
+    const [begin, end] = markersFor(bin)
+    return `# ${bin}: every command\n\nGenerated between the markers by \`${bin} commands --out ${path}\` from the registry. \`${bin}\` lists every command, \`${bin} <command> --help\` prints one.\n\n${begin}\n${end}\n`
+}
 
 export class CommandsCommand extends Command {
     static override paths = [['commands']]
@@ -109,33 +201,61 @@ export class CommandsCommand extends Command {
         ],
     })
 
-    json = Option.Boolean('--json', false, { description: 'machine-readable [{path, category, description}]' })
-    out = Option.String('--out', { description: 'host file carrying the shipkit:commands markers. The block between them is rewritten' })
-    check = Option.Boolean('--check', false, { description: 'with --out: exit 1 if the block is stale, write nothing' })
-    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `sk <command> --help`)' })
+    /** a project CLI holds its rows to shapeProblems (--out and --check fail on
+     *  a breach), and its --out creates a missing page */
+    static shapeRule = false
+
+    json = Option.Boolean('--json', false, { description: 'machine-readable rows, with film and essential where a command carries them' })
+    out = Option.String('--out', { description: 'host file carrying the <bin>:commands markers. The block between them is rewritten' })
+    check = Option.Boolean('--check', false, { description: 'with --out or --essentials: exit 1 if a page is stale, write nothing' })
+    compact = Option.Boolean('--compact', false, { description: 'one line per command: no flags, no examples (they are `<bin> <command> --help`)' })
+    essentials = Option.String('--essentials', { description: 'the everyday commands page, rewritten whole from the commands marked essential' })
 
     async execute(): Promise<number> {
+        const bin = this.cli.binaryName
+        const classes = (this.context as { classes?: { paths?: string[][] }[] }).classes ?? []
         const rows = commandRows(
             this.cli.definitions() as Definition[],
             (this.cli.definitions as (o?: { detailed?: boolean }) => Definition[])({ detailed: true }),
+            bin,
+            classes,
         )
-        if (this.out == null) {
-            this.context.stdout.write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows)}\n`)
+        const write = (s: string): void => void this.context.stdout.write(s)
+        if (this.out == null && this.essentials == null) {
+            write(this.json ? `${JSON.stringify(rows)}\n` : `${(this.compact ? renderCompact : renderMarkdown)(rows, bin)}\n`)
             return 0
         }
-        const { existsSync, readFileSync, writeFileSync } = await import('fs')
-        if (!existsSync(this.out)) { this.context.stdout.write(`FAIL: ${this.out} does not exist\n`); return 1 }
-        const host = readFileSync(this.out, 'utf8')
-        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows))
-        if (next == null) { this.context.stdout.write(`FAIL: ${this.out} has no ${BEGIN} / ${END} markers\n`); return 1 }
-        if (next === host) { this.context.stdout.write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return 0 }
+        if ((this.constructor as typeof CommandsCommand).shapeRule) {
+            const bad = shapeProblems(rows, bin)
+            for (const b of bad) write(`FAIL: ${b}\n`)
+            if (bad.length > 0) { write('      fix: give the row a category, a short description and an example that starts with its words\n'); return 1 }
+        }
+        const { existsSync, mkdirSync, readFileSync, writeFileSync: writeRaw } = await import('fs')
+        const { dirname } = await import('path')
+        const writeFileSync = (path: string, text: string): void => { mkdirSync(dirname(path), { recursive: true }); writeRaw(path, text) }
+        let code = 0
+        if (this.essentials != null) {
+            const cmd = `${bin} commands${this.out != null ? ` --out ${this.out}` : ''} --essentials ${this.essentials}`
+            const text = renderEssentials(rows, bin, cmd)
+            if (existsSync(this.essentials) && readFileSync(this.essentials, 'utf8') === text) write(`ok: ${this.essentials} current\n`)
+            else if (this.check) { write(`FAIL: ${this.essentials} is STALE — the essential commands moved\n      fix: ${cmd}\n`); code = 1 }
+            else { writeFileSync(this.essentials, text); write(`ok: ${this.essentials} rewritten\n`) }
+        }
+        if (this.out == null) return code
+        const [begin, end] = markersFor(bin)
+        const project = (this.constructor as typeof CommandsCommand).shapeRule
+        if (!existsSync(this.out) && (!project || this.check)) { write(`FAIL: ${this.out} does not exist\n`); return 1 }
+        const host = existsSync(this.out) ? readFileSync(this.out, 'utf8') : newCommandsPage(bin, this.out)
+        const next = spliceBlock(host, (this.compact ? renderCompact : renderMarkdown)(rows, bin), bin)
+        if (next == null) { write(`FAIL: ${this.out} has no ${begin} / ${end} markers\n`); return 1 }
+        if (next === host) { write(`ok: ${this.out} command index current (${rows.length} commands)\n`); return code }
         if (this.check) {
-            this.context.stdout.write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
-            this.context.stdout.write(`      fix: shipkit commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
+            write(`FAIL: ${this.out} command index is STALE — the binary registers commands the page does not list\n`)
+            write(`      fix: ${bin === 'sk' ? 'shipkit' : bin} commands${this.compact ? ' --compact' : ''} --out ${this.out}\n`)
             return 1
         }
         writeFileSync(this.out, next)
-        this.context.stdout.write(`ok: ${this.out} command index rewritten (${rows.length} commands)\n`)
-        return 0
+        write(`ok: ${this.out} command index rewritten (${rows.length} commands)\n`)
+        return code
     }
 }