rvlib-shipkit 2.1.1 → 2.3.0

package/src/trailer/look.ts

@@ -0,0 +1,124 @@
+// the look every trailer wears, drawn from the repo's brand (`.shipkit/identity/brand.ts`): the card's ground, the
+// title colours, the face and the logo. A repo changes its look in that data, never in code; a value it leaves out is
+// derived from its palette, and a repo with no brand gets the house default. Pure
+export interface TrailerLookInput {
+    /** the card's ground, middle then edge (default: the palette's bg, then a darker bg) */
+    ground?: [string, string]
+    /** words over footage (default: the palette's ink when it is light, else white) */
+    light?: string
+    /** the dark edge under words over footage (default: the ground's edge) */
+    edge?: string
+    /** the key colour: the caption's dot, a `line` title's `*word*`, the corner chip (default: the palette's accent) */
+    accent?: string
+    /** the caption's plate (default: the palette's bg, an accent outline, the palette's ink) */
+    plate?: { fill?: string; line?: string; ink?: string }
+    /** the corner chip (default: the accent, ink of the palette's bg) */
+    chip?: { fill?: string; ink?: string }
+    /** the face: a font file (repo relative, .ttf .otf .woff2) or a family the machine has, and its heavy weight */
+    font?: { file?: string; family?: string; weight?: number }
+    /** the logo the `logo` title draws over its words, repo relative (default: logo.png at the web root, when present) */
+    logo?: string
+    /** the words of a short: the `short` and `progress` titles and the vertical's words, each value the look's when left out */
+    short?: { font?: { file?: string; family?: string; weight?: number }; light?: string; edge?: string; accent?: string }
+    /** the vertical short's look (a `vertical` cut), each part `false` to leave it out (vertical.ts) */
+    vertical?: VerticalLookInput
+}
+
+/** what a vertical short wears, image paths repo relative; its colours and face are the look's */
+export interface VerticalLookInput {
+    /** over every frame of the short, under the platforms' top tabs: a wordmark image, else the logo and the name; a
+     *  tag pill under it */
+    lockup?: { image?: string; name?: string; tag?: string } | false
+    /** a bottom corner of the short and its outro: an image (default: the logo) and a word beside it (default: the
+     *  name, when there is no image) */
+    watermark?: { image?: string; text?: string; corner?: 'left' | 'right' } | false
+    /** the card the short ends on: an image that hops in (default: the logo), the name, lines with `*word*` in the
+     *  accent (default: the tagline), its length in seconds */
+    end?: { image?: string; name?: string; lines?: string[]; seconds?: number } | false
+}
+
+export interface TrailerLook {
+    ground: [string, string]
+    light: string
+    edge: string
+    accent: string
+    plate: { fill: string; line: string; ink: string }
+    chip: { fill: string; ink: string }
+    font: { file: string | null; family: string; weight: number }
+    logo: string | null
+    /** the short's words: their face and colours */
+    short: { font: { file: string | null; family: string; weight: number }; light: string; edge: string; accent: string }
+}
+
+export interface BrandLike {
+    name: string
+    tagline?: string
+    palette: { bg: string; accent: string; ink: string }
+    trailer?: TrailerLookInput
+}
+
+/** named faces first: a generic sans-serif can resolve to one with no Latin-1 accents (the og card uses it too) */
+export const HOUSE_FAMILIES = 'Helvetica, Arial, "DejaVu Sans", "Liberation Sans", "Noto Sans", sans-serif'
+
+/** the palette a repo with no brand wears: a deep ink ground, warm accent, cream words */
+export const HOUSE_PALETTE = { bg: '#1d1b2e', accent: '#ffb547', ink: '#fbf5ea' } as const
+
+/** `#rgb` or `#rrggbb` as [r, g, b], 0 to 255; null for any other colour text */
+export function rgbOf(c: string): [number, number, number] | null {
+    const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim())
+    if (!m) return null
+    const h = m[1]!.length === 3 ? [...m[1]!].map((x) => x + x).join('') : m[1]!
+    return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16)) as [number, number, number]
+}
+
+const hex = (rgb: readonly number[]): string => `#${rgb.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')).join('')}`
+
+/** the colour mixed toward black by `k`, 0 to 1; a colour that is not hex stays as it is */
+export function darker(c: string, k: number): string {
+    const rgb = rgbOf(c)
+    return rgb ? hex(rgb.map((v) => v * (1 - k))) : c
+}
+
+/** relative luminance, 0 dark to 1 light; 0.5 for a colour that is not hex */
+export function luminance(c: string): number {
+    const rgb = rgbOf(c)
+    if (!rgb) return 0.5
+    const [r, g, b] = rgb.map((v) => {
+        const s = v / 255
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4
+    }) as [number, number, number]
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+
+/** the colour with an alpha, as canvas reads it; a colour that is not hex stays as it is */
+export function alpha(c: string, a: number): string {
+    const rgb = rgbOf(c)
+    return rgb ? `rgba(${rgb.join(',')},${a})` : c
+}
+
+/** the look of a brand, every value its own or derived from its palette; `webLogo` the web root's logo.png when present */
+export function lookOf(brand: BrandLike | null, webLogo: string | null = null): TrailerLook {
+    const p = brand?.palette ?? HOUSE_PALETTE
+    const i = brand?.trailer ?? {}
+    const ground: [string, string] = i.ground ?? [p.bg, darker(p.bg, luminance(p.bg) > 0.5 ? 0.25 : 0.45)]
+    const font = { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 }
+    const light = i.light ?? (luminance(p.ink) > 0.45 ? p.ink : '#ffffff')
+    const edge = i.edge ?? (luminance(ground[1]) < 0.2 ? ground[1] : darker(p.bg, 0.8))
+    const accent = i.accent ?? p.accent
+    const sh = i.short ?? {}
+    const shortFont = sh.font ? { file: sh.font.file ?? null, family: sh.font.family ?? (sh.font.file ? 'TrailerShortFace' : font.family), weight: sh.font.weight ?? font.weight } : font
+    return {
+        ground,
+        light,
+        edge,
+        accent,
+        plate: { fill: i.plate?.fill ?? alpha(p.bg, 0.94), line: i.plate?.line ?? p.accent, ink: i.plate?.ink ?? p.ink },
+        chip: { fill: i.chip?.fill ?? p.accent, ink: i.chip?.ink ?? (luminance(p.accent) > 0.4 ? darker(p.bg, luminance(p.bg) > 0.5 ? 0.85 : 0.2) : '#ffffff') },
+        font: { file: i.font?.file ?? null, family: i.font?.family ?? (i.font?.file ? 'TrailerFace' : HOUSE_FAMILIES), weight: i.font?.weight ?? 800 },
+        logo: i.logo ?? webLogo,
+        short: { font: shortFont, light: sh.light ?? light, edge: sh.edge ?? edge, accent: sh.accent ?? accent },
+    }
+}
+
+/** the look a short's words wear: the look with the short's face and colours in place */
+export const shortLook = (look: TrailerLook): TrailerLook => ({ ...look, font: look.short.font, light: look.short.light, edge: look.short.edge, accent: look.short.accent })

package/src/trailer/passage.ts

@@ -0,0 +1,129 @@
+// the verbs over a built cut (wiki build/trailer.md, The verbs and Versions): each section's levels, a passage clipped
+// with its sound (and the same passage of a kept version), a version kept, the take file of a shot
+import { constants, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import { type Loaded, load, Refused, type Say, takesOfLoaded } from './build.ts'
+import { ffmpeg } from './ffmpeg.ts'
+import { starts, type Trailer } from './grammar.ts'
+
+const outOf = (l: Pick<Loaded, 'dir'>): string => join(l.dir, 'out')
+
+/** the built video of a cut, refused when the build never ran */
+function builtOf(l: Pick<Loaded, 'dir' | 'file' | 't'>, cwd: string): string {
+    const f = join(outOf(l), `${l.t.name}.mp4`)
+    if (!existsSync(f)) throw new Refused(`no ${relative(cwd, f)}: sk trailer ${relative(cwd, l.file)} first`)
+    return f
+}
+
+/** a moment of the cut on the video clock: a section or a mark, a shot, or seconds; `end` takes its end */
+export function momentOf(t: Pick<Trailer, 'sections' | 'timelineAt' | 'shots'>, name: string, end: boolean): number {
+    if (/^\d+(\.\d+)?$/.test(name)) return Number(name)
+    if (t.timelineAt !== null) {
+        const sec = t.sections.find((s) => s.name === name)
+        if (sec) return t.timelineAt + sec.at + (end ? sec.seconds : 0)
+        for (const s of t.sections) {
+            const m = s.marks.find((x) => x.name === name)
+            if (m) return t.timelineAt + s.at + m.at
+        }
+    }
+    const i = t.shots.findIndex((s) => s.name === name)
+    if (i >= 0) return starts(t)[i]! + (end ? t.shots[i]!.length : 0)
+    throw new Refused(`${name}: no section, mark or shot of that name (or write seconds)`)
+}
+
+/** each section's loudness in the built cut, and its step from the section before */
+export async function levels(l: Loaded, say: Say, cwd: string): Promise<void> {
+    const video = builtOf(l, cwd)
+    const at0 = l.t.timelineAt
+    if (l.t.sections.length === 0 || at0 === null) throw new Refused('levels: this cut has no section')
+    const rows = await Promise.all(
+        l.t.sections.map(async (s) => {
+            const err = await ffmpeg(['-loglevel', 'info', '-ss', String(at0 + s.at), '-t', String(s.seconds), '-i', video, '-vn', '-af', 'volumedetect', '-f', 'null', '-'])
+            const mean = Number(/mean_volume: (-?[\d.]+)/.exec(err)?.[1] ?? Number.NaN)
+            const max = Number(/max_volume: (-?[\d.]+)/.exec(err)?.[1] ?? Number.NaN)
+            return { s, mean, max }
+        }),
+    )
+    say(`${relative(cwd, video)}: each section's mean and peak, dB (video clock)`)
+    rows.forEach((r, i) => {
+        const prev = rows[i - 1]
+        const step = prev ? `${r.mean - prev.mean >= 0 ? '+' : ''}${(r.mean - prev.mean).toFixed(1)}` : ''
+        say(`  ${r.s.name.padEnd(12)} ${(at0 + r.s.at).toFixed(1).padStart(6)} s ${r.s.seconds.toFixed(1).padStart(5)} s   mean ${r.mean.toFixed(1).padStart(6)}  peak ${r.max.toFixed(1).padStart(5)}  ${step.padStart(5)}`)
+    })
+}
+
+/** a kept version's video: the one mp4 of `versions/<v>/` */
+export function versionVideo(dir: string, v: string): string | null {
+    const d = join(dir, 'versions', v)
+    if (!existsSync(d)) return null
+    const f = readdirSync(d).find((x) => x.endsWith('.mp4'))
+    return f ? join(d, f) : null
+}
+
+/** a version's cut text read as today's tool reads it, with the cut's own recipes, and its video */
+async function versionCut(l: Loaded, v: string, cwd: string): Promise<{ t: Trailer; video: string }> {
+    const text = join(l.dir, 'versions', `${v}.trailer`)
+    if (!existsSync(text)) throw new Refused(`no ${relative(cwd, text)}`)
+    const kept = await load(text, l.root, { dir: l.dir, check: false })
+    if (kept.errors.length > 0) throw new Refused(`${v} does not read with today's tool (an older version builds only in a worktree at its tag): ${kept.errors[0]!.message}`)
+    const video = versionVideo(l.dir, v) ?? join(l.dir, 'versions', v, `${basename(l.dir)}-${v}.mp4`)
+    if (!existsSync(video)) throw new Refused(`no ${relative(cwd, video)}`)
+    return { t: kept.t, video }
+}
+
+/** the passage from `from` to the end of `to` as its own mp4, sound included; with a version, the same passage of it too */
+export async function clip(l: Loaded, from: string, to: string, pad: number, version: string | undefined, say: Say, cwd: string): Promise<void> {
+    const cut = async (t: Trailer, video: string, out: string): Promise<void> => {
+        const a = Math.max(0, momentOf(t, from, false) - pad)
+        const b = momentOf(t, to, true) + pad
+        if (b <= a) throw new Refused(`clip: ${to} ends before ${from} starts`)
+        await ffmpeg(['-ss', String(a), '-to', String(b), '-i', video, '-c:v', 'libx264', '-crf', '18', '-preset', 'veryfast', '-pix_fmt', 'yuv420p', '-c:a', 'aac', out], { nice: 10 })
+        say(`ok: ${relative(cwd, out)} (${a.toFixed(2)} to ${b.toFixed(2)} s)`)
+    }
+    const tag = from === to ? from : `${from}-${to}`
+    await cut(l.t, builtOf(l, cwd), join(outOf(l), `clip-${tag}.mp4`))
+    if (version) {
+        const v = await versionCut(l, version, cwd)
+        await cut(v.t, v.video, join(outOf(l), `clip-${tag}-${version}.mp4`))
+    }
+}
+
+/** keep the built cut as a version: its text, its video, its strip and each shot's take, cloned so they cost nothing */
+export function keep(l: Loaded, v: string, say: Say, cwd: string): void {
+    if (!/^v\d+$/.test(v)) throw new Refused(`keep: a version is v<n>, not ${v}`)
+    const text = join(l.dir, 'versions', `${v}.trailer`)
+    const dir = join(l.dir, 'versions', v)
+    if (existsSync(text) || existsSync(dir)) throw new Refused(`${v} is kept already: versions are never overwritten`)
+    const video = builtOf(l, cwd)
+    mkdirSync(join(dir, 'shots'), { recursive: true })
+    writeFileSync(text, readFileSync(l.file, 'utf8'))
+    // a build rewrites its files in place: a link would turn the version into the next build, a clone costs nothing on APFS
+    const clone = (a: string, b: string): void => copyFileSync(a, b, constants.COPYFILE_FICLONE)
+    clone(video, join(dir, `${basename(l.dir)}-${v}.mp4`))
+    const strip = join(outOf(l), `${l.t.name}.strip.png`)
+    if (existsSync(strip)) clone(strip, join(dir, `${l.t.name}.strip.png`))
+    const shots = join(outOf(l), `${l.t.name}-shots`)
+    const files = existsSync(shots) ? readdirSync(shots) : []
+    for (const f of files) clone(join(shots, f), join(dir, 'shots', f))
+    // the clones are the machine's: git keeps the text and the index, never a version's folder
+    const ignored = Bun.spawnSync(['git', 'check-ignore', '-q', dir], { cwd: l.root }).exitCode === 0
+    const ignore = join(l.dir, 'versions', '.gitignore')
+    if (!ignored && !existsSync(ignore)) writeFileSync(ignore, '*/\n')
+    say(`ok: kept ${v}: ${relative(cwd, text)}, ${relative(cwd, dir)}/ (the video, the strip, ${files.length} shots)`)
+    say(`then: its row in ${relative(cwd, join(l.dir, 'versions', 'index.md'))}, commit ${relative(cwd, text)} and that index, git tag trailer-${basename(l.dir)}-${v}, push the commit and the tag`)
+}
+
+/** the take file of each named shot or footage block */
+export function footage(l: Loaded, names: string[], say: Say, cwd: string): void {
+    const takes = takesOfLoaded(l)
+    for (const name of names) {
+        const s = [...l.t.shots, ...l.t.footage].find((x) => x.name === name)
+        if (!s) throw new Refused(`${name}: no shot or footage block of that name`)
+        const tk = takes.find((x) => x.shot === s)
+        if (!tk) {
+            say(`${name}  no take: its film is ${s.film?.kind ?? 'nothing'}`)
+            continue
+        }
+        say(`${name}  ${relative(cwd, tk.file)}${existsSync(tk.file) ? '' : '  (not filmed)'}`)
+    }
+}

package/src/trailer/plan.ts

@@ -0,0 +1,192 @@
+// what a build does, as data: each shot's take and its key, which takes film, the pieces the stitch renders. Pure: the
+// io (stamps on disk, the world's git stamp, ffmpeg) lives in footage.ts and stitch.ts, which read these answers
+import type { Film, Shot, TakeLength, Trailer } from './grammar.ts'
+import { starts } from './grammar.ts'
+
+/** bump when the core films differently from the same line: every take films again */
+export const FILM_VERSION = 2
+
+/** the key of a take: what films (its version, its recipe, the frame, the rate, its seconds), never how the cut uses it */
+export function footageKey(version: unknown, recipe: unknown, size: readonly [number, number], fps: number, seconds: number | null): string {
+    return new Bun.CryptoHasher('sha1').update(JSON.stringify([version, recipe, size, fps, seconds])).digest('hex').slice(0, 12)
+}
+
+/** a film that writes a take of its own: the others are read where they lie (a clip, an image) or drawn (a card) */
+export type TakeFilm = Extract<Film, { kind: 'run' | 'cli' | 'url' }>
+export const isTake = (f: Film | null): f is TakeFilm => f?.kind === 'run' || f?.kind === 'cli' || f?.kind === 'url'
+
+/** the take is one picture, held for the shot */
+export const takeIsStill = (f: TakeFilm): boolean => (f.kind === 'cli' ? f.output === 'still' : f.still === true)
+
+/** the seconds a clip take films: what the shot shows rounded up to 2 s (so a small edit never films again), exactly
+ *  that, or none when it films as long as it plays; a still: none */
+export function takeSeconds(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, length: TakeLength = defaultLength(f)): number | null {
+    if (takeIsStill(f) || length === 'own') return null
+    return length === 'exact' ? +(s.from + s.length).toFixed(3) : Math.ceil((s.from + s.length) / 2) * 2
+}
+
+const defaultLength = (f: TakeFilm): TakeLength => (f.kind === 'cli' && f.length === 'own' ? 'own' : 'steps')
+
+/** the film line as its key reads it: the line it sits on is never part of what films, nor its row's marks (the
+ *  spec's version and length key them) */
+export function recipeOf(f: TakeFilm): unknown {
+    if (f.kind === 'cli') {
+        const { line: _l, version: _v, length: _n, ...recipe } = f
+        return recipe
+    }
+    const { line: _line, ...recipe } = f
+    return recipe
+}
+
+/** what one take is, past its words: its version, how long it films, a world of its own, what its key reads. A row
+ *  gives the defaults, the repo's trailer unit refines one line (adapter.ts `take`) */
+export interface TakeSpec {
+    version: number | string | null
+    length: TakeLength
+    /** a fixed world (`rev:<commit>`): the take is never stale */
+    world: string | null
+    /** the paths its world is, when its row names them (over the unit's `stamp`) */
+    stamp?: string[]
+    recipe: unknown
+}
+
+/** a recipe file's text as its key reads it: comment lines (`#` first), trailing comments (a space, `#`, then a space or
+ *  the line's end, outside double quotes) and blank lines left out; a `#` inside a value (`#ff0000`) is content */
+export function recipeText(text: string): string {
+    return text
+        .split('\n')
+        .map((l) => {
+            if (l.trimStart().startsWith('#')) return ''
+            let q = false
+            for (let i = 0; i < l.length; i++) {
+                if (l[i] === '"') q = !q
+                else if (l[i] === '#' && !q && /\s/.test(l[i - 1] ?? '') && /^(\s|$)/.test(l.slice(i + 1, i + 2))) return l.slice(0, i).trim()
+            }
+            return l.trim()
+        })
+        .filter(Boolean)
+        .join('\n')
+}
+
+/** the `@<file>` words of a film line */
+export const recipeWords = (argv: readonly string[]): string[] => argv.filter((a) => /^@\S/.test(a))
+
+/** a take's spec from its row alone; `files` the text of each `@<file>` word, as recipeText reads it */
+export function specOf(f: TakeFilm, files: Readonly<Record<string, string>> = {}): TakeSpec {
+    const read = Object.keys(files).length > 0 ? { files: Object.fromEntries(Object.entries(files).map(([k, v]) => [k, new Bun.CryptoHasher('sha1').update(v).digest('hex').slice(0, 12)])) } : {}
+    return { version: f.kind === 'cli' ? (f.version ?? null) : null, length: defaultLength(f), world: null, recipe: { ...(recipeOf(f) as object), ...read }, ...(f.kind === 'cli' && f.stamp ? { stamp: f.stamp } : {}) }
+}
+
+/** the take's file name, by its key alone: shots on one film line, in one cut or in several, share one file */
+export function takeName(s: Pick<Shot, 'from' | 'length'>, f: TakeFilm, t: Pick<Trailer, 'size' | 'fps'>, spec: TakeSpec = specOf(f)): string {
+    // a fixed world is what films: two past commits are two takes, whatever the recipe keeps of their words
+    const recipe = spec.world === null ? spec.recipe : { world: spec.world, recipe: spec.recipe }
+    return `${footageKey([FILM_VERSION, spec.version ?? 0], recipe, t.size, t.fps, takeSeconds(s, f, spec.length))}.${takeIsStill(f) ? 'png' : 'mp4'}`
+}
+
+/** the world a take was filmed on, beside it */
+export interface Stamp {
+    /** the repo's state when it filmed (footage.ts worldStamp) */
+    world: string
+    filmedAt: string
+    /** the take's own length, seconds; 0 for a still */
+    seconds: number
+    /** what the film said of it, its first line */
+    note: string
+    /** each frame's state, run length encoded (states.ts), when the film said it */
+    states?: string
+    /** its world was fixed by its spec (a film of a past commit): never stale */
+    fixed?: true
+}
+
+export const fresh = (stamp: Stamp, world: string): boolean => stamp.fixed === true || stamp.world === world
+
+/** a take as a build sees it: its shot, its file, its stamp when it was filmed */
+export interface Take {
+    shot: Shot
+    film: TakeFilm
+    file: string
+    stamp: Stamp | null
+    spec: TakeSpec
+    /** the words the film runs: each `@<file>` as its repo relative path */
+    argv?: string[]
+}
+
+/** `--refilm`: every stale take, or the takes of the named shots */
+export type Refilm = 'stale' | ReadonlySet<string> | null
+
+/** the takes to film, each group sharing one file and filmed once by its first shot: a missing take, a stale one under
+ *  `--refilm`, or one whose shot `--refilm` names */
+/** the world a take is measured against: one for the cut, or one a take (a row that names its own paths) */
+export type World = string | ((tk: Take) => string)
+export const worldFor = (w: World, tk: Take): string => (typeof w === 'string' ? w : w(tk))
+
+export function takesToFilm(takes: readonly Take[], world: World, refilm: Refilm, only?: ReadonlySet<string>): Take[][] {
+    const groups = new Map<string, Take[]>()
+    for (const tk of takes) {
+        if (only !== undefined && !only.has(tk.shot.name)) continue
+        const g = groups.get(tk.file)
+        if (g) g.push(tk)
+        else groups.set(tk.file, [tk])
+    }
+    return [...groups.values()].filter((g) => {
+        const first = g[0]!
+        if (first.stamp === null) return true
+        if (refilm === 'stale') return !fresh(first.stamp, worldFor(world, first))
+        return refilm instanceof Set && g.some((tk) => refilm.has(tk.shot.name))
+    })
+}
+
+/** the argv a project CLI film runs: its words (`argv`, the recipe files resolved), then the file and, for a clip, its
+ *  seconds */
+export function cliArgv(cli: readonly string[], f: Extract<Film, { kind: 'cli' }>, out: string, seconds: number | null, argv: readonly string[] = f.argv): string[] {
+    return [...cli, ...argv, '--out', out, ...(seconds === null ? [] : ['--seconds', String(seconds)])]
+}
+
+/** a `film run` command with its marks filled: `{out}`, `{seconds}`, `{w}`, `{h}`, `{fps}` */
+export function runCommand(f: Extract<Film, { kind: 'run' }>, o: { out: string; seconds: number | null; size: readonly [number, number]; fps: number }): string {
+    const q = (s: string): string => `'${s.replaceAll("'", "'\\''")}'`
+    return f.cmd
+        .replaceAll('{out}', q(o.out))
+        .replaceAll('{seconds}', String(o.seconds ?? 0))
+        .replaceAll('{w}', String(o.size[0]))
+        .replaceAll('{h}', String(o.size[1]))
+        .replaceAll('{fps}', String(o.fps))
+}
+
+/** the first frame at or after a time: a shot, a cut or a title starts on it */
+export const frameAt = (seconds: number, fps: number): number => Math.ceil(seconds * fps - 1e-6) || 0
+
+/** each shot's frames on the cut, [a, b): a cut's frames are those both shots hold; a hard cut's shots share none */
+export function frameSpans(t: Pick<Trailer, 'shots' | 'fps'>): { a: number; b: number }[] {
+    const st = starts(t)
+    return t.shots.map((s, i) => ({ a: frameAt(st[i]!, t.fps), b: frameAt(st[i]! + s.length, t.fps) }))
+}
+
+/** a piece of the cut rendered alone: a section, or the shots before the first section (`start`) */
+export interface Piece {
+    name: string
+    /** its shots, [first, end) */
+    first: number
+    end: number
+    /** the first shot its graph draws: the shot before `first` when the cut into the section overlaps it */
+    chain: number
+    /** its frames on the cut, [from, to) */
+    from: number
+    to: number
+}
+
+export const START_PIECE = 'start'
+
+/** the cut split at its sections; the pieces' frames tile the cut */
+export function pieces(t: Pick<Trailer, 'shots' | 'fps'>): Piece[] {
+    const spans = frameSpans(t)
+    const opens = t.shots.flatMap((s, i) => (i > 0 && s.section ? [i] : []))
+    const firsts = [0, ...opens]
+    return firsts.map((first, k) => {
+        const end = firsts[k + 1] ?? t.shots.length
+        const from = spans[first]!.a
+        const chain = first > 0 && spans[first - 1]!.b > from ? first - 1 : first
+        return { name: k === 0 ? (t.shots[0]?.section?.name ?? START_PIECE) : t.shots[first]!.section!.name, first, end, chain, from, to: end < t.shots.length ? spans[end]!.a : spans.at(-1)!.b }
+    })
+}

package/src/trailer/prune.ts

@@ -0,0 +1,193 @@
+// the trailer's cache kept small (wiki build/trailer.md, The cache): what the cuts of every trailer folder still use
+// stays, the rest goes. Runs after every stitch and by hand (`sk trailer prune [--dry]`). What a cut uses is named by the
+// build's own key functions; a file younger than an hour is never deleted: another build may be writing or reading it
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+import { cutFiles, load } from './build.ts'
+import { SCORE, musicCues } from './grammar.ts'
+import { pieces } from './plan.ts'
+
+/** the renders kept per section: the one the cut plays and the one before it, so undoing an edit renders nothing */
+const KEEP_PER_SECTION = 2
+/** a file younger than this is never deleted */
+export const RENDER_GRACE_MS = 60 * 60_000
+/** the folders the trailer's code writes; any other folder of the cache is dead and goes whole */
+const FOLDERS = ['footage', 'pieces', 'sound', 'score', 'titles']
+
+/** what the cuts use, by file name in each folder; `broken` names the cuts that do not read */
+export interface Live {
+    footage: Set<string>
+    /** the render stems of pieces/, pieces/mix/ and pieces/vertical/ */
+    stems: Set<string>
+    sound: Set<string>
+    score: Set<string>
+    titles: Set<string>
+    broken: string[]
+}
+
+/** the live set: each cut read, the name of every cache file its build reads, by the build's own key functions */
+export async function liveSet(root: string): Promise<Live> {
+    const live: Live = { footage: new Set(), stems: new Set(), sound: new Set(), score: new Set(), titles: new Set(), broken: [] }
+    const [{ takesOfLoaded }, { trailerCache }, { scoreWavFile }, { scoreModuleFile, scoreModule }, titles, { lookOf }, { loadBrand, identityLogo }] = await Promise.all([
+        import('./build.ts'),
+        import('./footage.ts'),
+        import('./score/sound.ts'),
+        import('./score/score.ts'),
+        import('./titles.ts'),
+        import('./look.ts'),
+        import('../assets/run-assets.ts'),
+    ])
+    const brand = await loadBrand(root)
+    const look = typeof brand === 'string' ? null : lookOf(brand, await identityLogo(root))
+    for (const file of cutFiles(root)) {
+        // whatever a cut throws (its parse, the unit's take, its score), it is named and the keyed folders stay
+        try {
+            const l = await load(file, root, { check: false })
+            const why = l.errors[0]
+            if (why) {
+                live.broken.push(`${relative(root, file)}:${why.line}: ${why.message}`)
+                continue
+            }
+            const t = l.t
+            const names = { footage: takesOfLoaded(l).map((tk) => basename(tk.file)), stems: [] as string[], titles: [] as string[], score: [] as string[], sound: [] as string[] }
+            for (const p of pieces(t)) names.stems.push(`${t.name}-${p.name}`)
+            names.stems.push(`mix-${t.name}`, `${t.name}-vertical`)
+            if (look) {
+                const dir = trailerCache(root, 'titles')
+                names.titles.push(basename(titles.cardFile(dir, t.size, look)))
+                for (const s of t.shots) for (const ti of s.titles) names.titles.push(basename(titles.titleFile(dir, root, ti.text, ti.style, t.size, titles.placeOf(ti), look, ti.step)))
+            }
+            if (t.score && l.score) {
+                names.score.push(basename(scoreModuleFile(scoreModule(t.score, t.sections).text, trailerCache(root, 'score'))))
+                const sound = trailerCache(root, 'sound')
+                names.sound.push(basename(scoreWavFile(l.score, l.score.seconds, sound)))
+                for (const { cue, at, end } of musicCues(t)) if (cue.song === SCORE) names.sound.push(basename(scoreWavFile(l.score, cue.from + end - at, sound)))
+            }
+            for (const k of ['footage', 'stems', 'titles', 'score', 'sound'] as const) for (const n of names[k]) live[k].add(n)
+        } catch (e) {
+            live.broken.push(`${relative(root, file)}: ${(e as Error).message}`)
+        }
+    }
+    return live
+}
+
+/** a file the prune deletes: its bytes, and whether another hard link keeps them on disk */
+interface Doomed {
+    file: string
+    bytes: number
+    linked: boolean
+}
+
+const doomed = (file: string): Doomed => {
+    const s = statSync(file)
+    return { file, bytes: s.size, linked: s.nlink > 1 }
+}
+
+/** the files of `dir` that `keep` refuses, past the grace */
+export function unlisted(dir: string, keep: (name: string) => boolean, now = Date.now()): Doomed[] {
+    if (!existsSync(dir)) return []
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isFile() && !keep(e.name))
+        .map((e) => join(dir, e.name))
+        .filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS)
+        .map(doomed)
+}
+
+/** a file stays when a cut names it, and every file named after it (its stamp `<file>.json`, its box, its levels) */
+export const keepListed =
+    (names: ReadonlySet<string>) =>
+    (name: string): boolean =>
+        names.has(name) || [...names].some((n) => name.startsWith(`${n}.`))
+
+const RENDER_RE = /^(.+)-([0-9a-f]{16})(?:\.part)?(?:\.\w+)+$/
+
+/** the renders of `dir` that go: every render of a stem no cut has (a renamed section, a shot's preview), and past the
+ *  newest `keep` of each live stem (a cache hit touches it). `stems` null: no stem is dropped */
+export function oldRenders(dir: string, stems: ReadonlySet<string> | null, keep = KEEP_PER_SECTION, now = Date.now()): Doomed[] {
+    if (!existsSync(dir)) return []
+    const byStem = new Map<string, Map<string, number>>()
+    for (const e of readdirSync(dir, { withFileTypes: true }).filter((x) => x.isFile())) {
+        const m = RENDER_RE.exec(e.name)
+        if (!m) continue
+        const keys = byStem.get(m[1]!) ?? new Map<string, number>()
+        keys.set(m[2]!, Math.max(keys.get(m[2]!) ?? 0, statSync(join(dir, e.name)).mtimeMs))
+        byStem.set(m[1]!, keys)
+    }
+    const kept = new Set<string>()
+    for (const [stem, keys] of byStem) {
+        if (stems !== null && !stems.has(stem)) continue
+        for (const [k] of [...keys].sort((x, y) => y[1] - x[1]).slice(0, keep)) kept.add(`${stem}-${k}`)
+    }
+    return unlisted(
+        dir,
+        (name) => {
+            const m = RENDER_RE.exec(name)
+            return m === null ? stems === null : kept.has(`${m[1]}-${m[2]}`)
+        },
+        now,
+    )
+}
+
+/** what one folder frees */
+export interface Freed {
+    folder: string
+    files: number
+    /** bytes the disk gets back */
+    bytes: number
+    /** bytes another hard link keeps */
+    linked: number
+}
+
+export interface Pruned {
+    freed: Freed[]
+    /** the cuts that do not read: the folders keyed on what the cuts use were left alone */
+    broken: string[]
+}
+
+function filesUnder(dir: string): string[] {
+    return readdirSync(dir, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? filesUnder(join(dir, e.name)) : [join(dir, e.name)]))
+}
+
+/** plans every folder's prune, then deletes unless `dry` */
+export async function prune(root: string, o: { dry: boolean; now?: number }): Promise<Pruned> {
+    const now = o.now ?? Date.now()
+    const [{ trailerCache }, { viewsToDrop }] = await Promise.all([import('./footage.ts'), import('../review/trailer-desk.ts')])
+    const cache = join(trailerCache(root, 'footage'), '..')
+    const live = await liveSet(root)
+    const whole = live.broken.length === 0
+    // titles/ holds the vertical's drawings too: only a title's and a card's files are the prune's
+    const ownTitle = (n: string): boolean => /^(title|card)-[0-9a-f]{16}\./.test(n)
+    const plan: [string, Doomed[]][] = [
+        ['footage/', whole ? unlisted(join(cache, 'footage'), keepListed(live.footage), now) : []],
+        ['pieces/', ['', 'mix', 'vertical'].flatMap((d) => oldRenders(join(cache, 'pieces', d), whole ? live.stems : null, KEEP_PER_SECTION, now))],
+        ['sound/', whole ? unlisted(join(cache, 'sound'), keepListed(live.sound), now) : []],
+        ['score/', whole ? unlisted(join(cache, 'score'), keepListed(live.score), now) : []],
+        ['titles/', whole ? unlisted(join(cache, 'titles'), (n) => !ownTitle(n) || keepListed(live.titles)(n), now) : []],
+    ]
+    const dead = existsSync(cache) ? readdirSync(cache, { withFileTypes: true }).filter((e) => e.isDirectory() && !FOLDERS.includes(e.name)) : []
+    for (const d of dead) plan.push([`${d.name}/ (dead)`, filesUnder(join(cache, d.name)).map(doomed)])
+    plan.push(['trailer-view/', viewsToDrop(root).filter((f) => now - statSync(f).mtimeMs > RENDER_GRACE_MS).map(doomed)])
+    if (!o.dry) {
+        for (const [, ds] of plan) for (const d of ds) rmSync(d.file, { force: true })
+        for (const d of dead) rmSync(join(cache, d.name), { recursive: true, force: true })
+    }
+    return {
+        freed: plan.map(([folder, ds]) => ({ folder, files: ds.length, bytes: ds.reduce((n, d) => n + (d.linked ? 0 : d.bytes), 0), linked: ds.reduce((n, d) => n + (d.linked ? d.bytes : 0), 0) })),
+        broken: live.broken,
+    }
+}
+
+const gb = (n: number): string => (n >= 1e9 ? `${(n / 1e9).toFixed(2)} GB` : `${(n / 1e6).toFixed(1)} MB`)
+
+/** the report, a line a folder; `short` folds it into one line for the end of a build */
+export function sayPruned(p: Pruned, dry: boolean, short = false): string[] {
+    const total = p.freed.reduce((n, f) => n + f.bytes, 0)
+    const files = p.freed.reduce((n, f) => n + f.files, 0)
+    if (short) return [`cache pruned: ${files} files, ${gb(total)} freed${p.broken.length > 0 ? ` (a cut does not read, the keyed folders left alone: ${p.broken[0]})` : ''}`]
+    return [
+        dry ? 'trailer cache, a dry run: nothing deleted' : 'trailer cache pruned',
+        ...p.freed.map((f) => `  ${f.folder.padEnd(20)} ${String(f.files).padStart(5)} files  ${gb(f.bytes).padStart(9)}${f.linked > 0 ? `  (and ${gb(f.linked)} a hard link keeps)` : ''}`),
+        `  ${'total'.padEnd(20)} ${String(files).padStart(5)} files  ${gb(total).padStart(9)}${dry ? ' would be freed' : ' freed'}`,
+        ...(p.broken.length > 0 ? [`  footage, sound, score, titles and unknown sections left alone: a cut does not read (${p.broken.join('; ')})`] : []),
+    ]
+}