@hajimism/dek 0.3.3 → 0.5.0

package/src/cli/commands.ts

@@ -1,4 +1,6 @@
 import { hasErrors } from "../core/diagnostic.ts";
+import { shellQuote } from "../core/escape.ts";
+import type { HiddenText } from "../core/foreign-text.ts";
 import { isRefName } from "../core/ref-name.ts";
 import { mergeSarif, toSarif } from "../core/sarif.ts";
 import type { CheckCliResult } from "./check.ts";
@@ -14,6 +16,7 @@ import {
   formatBuild,
   formatCheck,
   formatCues,
+  formatHidden,
   formatInit,
   formatKept,
   formatKeptTheme,
@@ -24,6 +27,7 @@ import {
   formatNew,
   formatPack,
   formatPdf,
+  formatPptx,
   formatRef,
   formatReport,
   formatShot,
@@ -63,14 +67,17 @@ type AnyCtx = Omit<Ctx<[], DeckScope | undefined>, "args"> & {
 /** How a command's result is printed. Only `text` is required. */
 export type Output<D> = {
   text(data: D, color: boolean): string;
-  /** What did not happen, for stderr next to the text: the result on stdout stays the result. */
+  /**
+   * What did not happen, or what is worth a look, such as what a ref hides, for stderr next to the
+   * text: the result on stdout stays the result.
+   */
   notes?(data: D, color: boolean): string | undefined;
   /** The `--json` fields next to `ok`; the data as-is when absent. */
   json?(data: D): object;
   /** The data with every path into the source tree as `display` shows it. */
   paths?(data: D, display: (path: string) => string): D;
-  /** The error of a run that did its job and found one. */
-  failure?(data: D): FormattedError | undefined;
+  /** The error of a run that did its job and found one; `flags` are the run's, for its rerun. */
+  failure?(data: D, flags: FlagValues): FormattedError | undefined;
   /** `--format sarif`. */
   sarif?(data: D): object;
 };
@@ -192,6 +199,20 @@ function withDisplayDiagnostics<D extends { diagnostics: CheckCliResult["diagnos
   return { ...data, diagnostics: displayDiagnostics(data.diagnostics, display) };
 }
 
+/** What to do about the characters a person cannot see that a ref's theme brought into a new deck. */
+const COPIED_HIDDEN_HELP =
+  "they came in with the ref's theme, and a person reading the deck sees none of them; remove them from theme.css unless you mean them";
+
+/** The data with each hidden-character report's path as `display` shows it. */
+function withDisplayHidden<D extends { hidden?: HiddenText[] }>(
+  data: D,
+  display: (path: string) => string,
+): D {
+  return data.hidden === undefined
+    ? data
+    : { ...data, hidden: data.hidden.map((entry) => ({ ...entry, path: display(entry.path) })) };
+}
+
 /**
  * Every command, in the order `dekc help` lists them: the words and flags it takes, its help,
  * what it works on, how it runs, and how its result prints. Each module loads only when its
@@ -287,11 +308,12 @@ export const COMMANDS = {
     },
     output: {
       text: formatNew,
-      paths: (data, display) => ({
-        ...data,
-        created: data.created.map(display),
-        updated: data.updated.map(display),
-      }),
+      notes: (data, color) => formatHidden(data.hidden, color, COPIED_HIDDEN_HELP) || undefined,
+      paths: (data, display) =>
+        withDisplayHidden(
+          { ...data, created: data.created.map(display), updated: data.updated.map(display) },
+          display,
+        ),
     },
   }),
   ls: result({
@@ -310,10 +332,12 @@ export const COMMANDS = {
     },
     output: {
       text: formatLs,
+      notes: (data, color) =>
+        (data.kind === "deck" && formatHidden(data.hidden, color)) || undefined,
       json: ({ kind: _kind, ...data }) => data,
       paths: (data, display) =>
         data.kind === "deck"
-          ? withDisplayDiagnostics(data, display)
+          ? withDisplayHidden(withDisplayDiagnostics(data, display), display)
           : {
               ...withDisplayDiagnostics(data, display),
               decks: data.decks.map((deck) => withDisplayDiagnostics(deck, display)),
@@ -397,7 +421,11 @@ export const COMMANDS = {
       const { showCommand } = await import("./show.ts");
       return showCommand(target, args.slug);
     },
-    output: { text: formatShow },
+    output: {
+      text: formatShow,
+      notes: (data, color) => formatHidden(data.hidden, color) || undefined,
+      paths: withDisplayHidden,
+    },
   }),
   theme: result({
     scope: "deck",
@@ -422,7 +450,8 @@ export const COMMANDS = {
     },
     output: {
       text: formatTheme,
-      paths: (data, display) => ({ ...data, path: display(data.path) }),
+      notes: (data, color) => formatHidden(data.hidden, color) || undefined,
+      paths: (data, display) => withDisplayHidden({ ...data, path: display(data.path) }, display),
     },
   }),
   check: result({
@@ -444,7 +473,7 @@ export const COMMANDS = {
       text: formatCheck,
       notes: (data, color) => formatSkipped(data.skipped, color) || undefined,
       paths: withDisplayDiagnostics,
-      failure: (data) => diagnosticFailure("check", data, `dekc check ${data.slug}`),
+      failure: (data) => diagnosticFailure("check", data, `dekc check ${shellQuote(data.slug)}`),
     },
   }),
   shot: result({
@@ -484,7 +513,11 @@ export const COMMANDS = {
         motion: flags.motion,
       });
     },
-    output: { text: formatShot },
+    output: {
+      text: formatShot,
+      notes: (data, color) => formatHidden(data.hidden, color) || undefined,
+      paths: withDisplayHidden,
+    },
   }),
   mv: result({
     scope: "deck",
@@ -659,7 +692,7 @@ export const COMMANDS = {
     group: "Output",
     overview: [
       ["dekc lint [--fix]", "check script.md against slides; --fix syncs first"],
-      ["dekc lint --visual", "add overflow and contrast rules"],
+      ["dekc lint --visual", "add overflow, contrast, line-break, and alignment rules"],
       ["dekc lint --format sarif", "print diagnostics as SARIF, for code scanning"],
     ],
     agent: ["dekc lint [--fix] [--visual] [--format sarif]"],
@@ -672,7 +705,9 @@ export const COMMANDS = {
       notes: (data, color) => formatSkipped(data.skipped, color) || undefined,
       json: ({ rumdlSarif: _rumdlSarif, ...data }) => data,
       paths: withDisplayDiagnostics,
-      failure: (data) => diagnosticFailure("lint", data, "dekc lint"),
+      // The rerun measures what this run did: without --visual, the errors it found may not show.
+      failure: (data, flags) =>
+        diagnosticFailure("lint", data, flags.visual ? "dekc lint --visual" : "dekc lint"),
       sarif: (data) => {
         const dek = data.diagnostics.filter((diagnostic) => diagnostic.id.startsWith("DEK"));
         return mergeSarif(toSarif(dek, { skipped: data.skipped ?? [] }), data.rumdlSarif);
@@ -827,19 +862,22 @@ export const COMMANDS = {
     flags: ["root-dist", "public"],
     usage: ["dekc pptx [deck] [--root-dist] [--public]"],
     summary:
-      "Write dist/<deck>.pptx, one slide per slide at its last beat: a picture of it with its text\nin text boxes to edit, and its script in the notes. Needs Playwright.",
+      "Write dist/<deck>.pptx, one slide per slide at its last beat: its plain boxes, pictures, and\ntext as PowerPoint's own over a picture of the rest, in the deck's theme, and its script in\nthe notes. Needs Playwright.",
     group: "Output",
     overview: [
-      ["dekc pptx [--root-dist] [--public]", "write a PowerPoint file with editable text"],
+      [
+        "dekc pptx [--root-dist] [--public]",
+        "write a PowerPoint file with editable shapes and text",
+      ],
     ],
     agent: [
-      "dekc pptx [--root-dist] [--public]   text editable over a picture of each slide; script in notes",
+      "dekc pptx [--root-dist] [--public]   boxes, pictures, and text editable over a picture of the rest; script in notes",
     ],
     run: async ({ target, flags }) => {
       const { pptxCommand } = await import("./pptx.ts");
       return pptxCommand(target, { rootDist: flags["root-dist"], public: flags.public });
     },
-    output: { text: formatPdf },
+    output: { text: formatPptx, json: ({ lifted: _lifted, ...data }) => data },
   }),
   help: {
     kind: "help",

package/src/cli/contract.ts

@@ -50,6 +50,19 @@ const SkippedCheck = z
     description: "A check that did not run, so an empty list of findings is no pass for it.",
   });
 
+const Unsandboxed = z
+  .strictObject({
+    reason: z.string().describe("What Chromium said when it did not start with its sandbox."),
+    hint: z
+      .string()
+      .describe("What lets the sandbox start, and, unless already set, DEK_ALLOW_UNSANDBOXED=1."),
+  })
+  .meta({
+    id: "Unsandboxed",
+    description:
+      "Chromium drew without its sandbox, which did not start here, as in a container running as root. A ref is never drawn so unless DEK_ALLOW_UNSANDBOXED=1.",
+  });
+
 const Failure = z
   .strictObject({
     message: z.string(),
@@ -68,6 +81,27 @@ const RefInfo = z
   })
   .meta({ id: "RefInfo", description: "Set when the deck read is a ref." });
 
+const HiddenText = z
+  .strictObject({
+    path: z.string(),
+    line: z.number().int(),
+    column: z
+      .number()
+      .int()
+      .describe("1-based, in UTF-16 units as editors count: where the first of them is."),
+    codePoints: z.array(z.string()).describe("Each of them on the line, in order, as U+XXXX."),
+  })
+  .meta({
+    id: "HiddenText",
+    description:
+      "A line of a ref's file that holds characters a person cannot see: those Unicode marks default-ignorable, such as tag characters, zero-width characters, the byte order mark, bidi controls, and Hangul fillers, but not variation selectors; the line and paragraph separators; and the interlinear annotation marks. Text output shows each as ⟨U+XXXX⟩.",
+  });
+
+const hidden = z
+  .array(HiddenText)
+  .optional()
+  .describe("A ref's lines that hold characters a person cannot see; absent when none does.");
+
 const Position = z
   .strictObject({ slideIndex: z.number().int(), beatIndex: z.number().int() })
   .meta({ id: "Position" });
@@ -75,6 +109,9 @@ const Position = z
 const paths = z.array(z.string());
 const diagnostics = z.array(Diagnostic);
 const skipped = z.array(SkippedCheck).optional().describe("Absent when every check ran.");
+const unsandboxed = Unsandboxed.optional().describe(
+  "Absent when every page drawn was drawn in Chromium's sandbox, or none was.",
+);
 
 const nav = z.strictObject({
   slug: z.string(),
@@ -112,6 +149,7 @@ export const RESULT_FIELDS = {
     updated: paths,
     next: z.array(z.string()),
     warnings: z.array(z.string()).describe("Set when the theme came from a ref with no license."),
+    hidden,
   }),
   ls: z.union([
     z.strictObject({
@@ -149,6 +187,7 @@ export const RESULT_FIELDS = {
       diagnostics,
       skipped,
       ref: RefInfo.optional(),
+      hidden,
     }),
   ]),
   ref: z.union([
@@ -202,6 +241,7 @@ export const RESULT_FIELDS = {
       ),
     assets: paths,
     ref: RefInfo.optional(),
+    hidden,
   }),
   theme: z.strictObject({
     path: z.string(),
@@ -214,14 +254,24 @@ export const RESULT_FIELDS = {
         "State classes the theme selects that the player sets at runtime (is-current, is-shown); never written in markup.",
       ),
     tokens: z.array(z.strictObject({ name: z.string(), value: z.string() })),
-    layouts: z.array(z.strictObject({ name: z.string(), example: z.string().optional() })),
+    layouts: z
+      .array(z.strictObject({ name: z.string(), example: z.string().optional() }))
+      .describe("The layouts whose names are plain words, which dek prints."),
+    unprintedLayouts: z
+      .number()
+      .optional()
+      .describe(
+        "How many layouts the theme has whose names are no plain word, left out of layouts; absent when none.",
+      ),
     layout: z.strictObject({ name: z.string(), example: z.string() }).optional(),
     ref: RefInfo.optional(),
+    hidden,
   }),
   check: z.strictObject({
     slug: z.string(),
     diagnostics,
     skipped,
+    unsandboxed,
     shot: z.string().optional(),
     fill: z
       .strictObject({
@@ -281,6 +331,8 @@ export const RESULT_FIELDS = {
       )
       .optional()
       .describe("With --motion, each beat in order with its frames, the settled end last."),
+    unsandboxed,
+    hidden,
   }),
   mv: z.strictObject({
     from: z.string(),
@@ -370,7 +422,7 @@ export const RESULT_FIELDS = {
     z.strictObject({ action: z.literal("clear"), cleared: z.number().int() }),
   ]),
   sync: z.strictObject({ created: paths, updated: paths, removed: paths, kept: paths }),
-  lint: z.strictObject({ diagnostics, skipped }),
+  lint: z.strictObject({ diagnostics, skipped, unsandboxed }),
   cues: z.strictObject({
     name: z.string(),
     cues: z.array(
@@ -409,15 +461,17 @@ export const RESULT_FIELDS = {
     images: paths.describe("dist/<deck>.png for each deck that got a link preview image."),
     diagnostics,
     skipped,
+    unsandboxed,
   }),
   video: z.strictObject({
     out: z.string(),
     vtt: z.string().optional(),
     chapters: z.string().optional(),
     credits: z.string().optional(),
+    unsandboxed,
   }),
-  pdf: z.strictObject({ outs: paths }),
-  pptx: z.strictObject({ outs: paths }),
+  pdf: z.strictObject({ outs: paths, unsandboxed }),
+  pptx: z.strictObject({ outs: paths, unsandboxed }),
   pack: z.strictObject({
     outs: paths,
     warnings: z.array(z.string()).describe("Once per project: the packs carry no license."),

package/src/cli/files.ts

@@ -1,9 +1,11 @@
+// biome-ignore lint/style/noRestrictedImports: mkdirSync and writeFileSync, for init and new, which create a file only where none is (wx); safe-fs replaces one.
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { bundledTheme } from "../core/bundled-theme.ts";
 import type { DekConfig } from "../core/config.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { walkUp } from "../core/optional.ts";
 import { PLAYWRIGHT_INSTALL } from "../core/playwright.ts";
 import { readSourceIfExists, writeInside } from "../core/safe-fs.ts";
@@ -316,8 +318,3 @@ function inNodeModules(root: string, ...path: string[]): boolean {
     walkUp(root, (dir) => existsSync(join(dir, "node_modules", ...path)) || undefined) === true
   );
 }
-
-/** `word` as one shell word: as it is when that is safe, else single-quoted. */
-export function shellQuote(word: string): string {
-  return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`;
-}

package/src/cli/flags.ts

@@ -41,7 +41,7 @@ export const FLAGS = {
   fix: { type: "boolean", text: "create missing skeleton slides before linting" },
   visual: {
     type: "boolean",
-    text: "add the rendered rules: overflow and contrast (needs Playwright)",
+    text: "add the rendered rules: overflow, contrast, line breaks, and alignment (needs Playwright)",
   },
   shot: { type: "boolean", text: "also write a screenshot and return its path" },
   voice: { type: "boolean", text: "also return each sentence's reading and duration" },

package/src/cli/format.ts

@@ -2,7 +2,7 @@ import { isAbsolute, relative } from "node:path";
 import type { Diagnostic } from "../core/diagnostic.ts";
 import { type ErrorFields, errorFields } from "../core/error.ts";
 import type { LiveEvent } from "../core/live-protocol.ts";
-import { ansi, displayWidth, padEndWidth, padStartWidth } from "./tty.ts";
+import { ansi, displayWidth, padEndWidth, padStartWidth, plainText } from "./tty.ts";
 
 function formatLocation(location: { path?: string; line?: number; column?: number }): string {
   if (location.path !== undefined && location.line !== undefined) {
@@ -56,17 +56,18 @@ export function formatError(error: unknown, opts?: { cwd?: string }): FormattedE
     : { ...fields, path: displayPath(fields.path, opts?.cwd) };
 }
 
+/** An error as the terminal shows it: its own text plain, and dek's colors around it. */
 export function formatErrorText(error: unknown, opts?: { color?: boolean; cwd?: string }): string {
   const formatted = formatError(error, opts);
   const c = ansi(opts?.color === true);
-  const parts = [`${c.bold(c.red("error:"))} ${formatted.message}`];
+  const parts = [`${c.bold(c.red("error:"))} ${plainText(formatted.message)}`];
   if (formatted.path) {
     const loc =
       formatted.line !== undefined ? `${formatted.path}:${formatted.line}` : formatted.path;
-    parts.push(` ${c.cyan("-->")} ${loc}`);
+    parts.push(` ${c.cyan("-->")} ${plainText(loc)}`);
   }
   if (formatted.hint) {
-    parts.push(`  ${c.yellow("help:")} ${formatted.hint}`);
+    parts.push(`  ${c.yellow("help:")} ${plainText(formatted.hint)}`);
   }
   return parts.join("\n");
 }

package/src/cli/goto.ts

@@ -1,6 +1,8 @@
 import { DekError } from "../core/error.ts";
 import { deckRoutePath } from "../runtime/routes.ts";
 import { isPidAlive, readDevServerLock } from "../server/lock.ts";
+import { deckFlag, deckWord } from "./address.ts";
+import { isTypedCommand } from "./commands.ts";
 import { type DeckTarget, requireSection } from "./scope.ts";
 
 export type NavResult = {
@@ -11,22 +13,42 @@ export type NavResult = {
   viewers: number;
 };
 
-export async function gotoCommand(target: DeckTarget, slug: string): Promise<NavResult> {
+type NavOptions = {
+  /** Covers the whole request, from connecting to the last byte of the answer. */
+  timeoutMs?: number;
+};
+
+/** The dev server answers a nav request at once; a stall this long is a server that is stuck. */
+const NAV_TIMEOUT_MS = 10 * 1000;
+
+export async function gotoCommand(
+  target: DeckTarget,
+  slug: string,
+  options: NavOptions = {},
+): Promise<NavResult> {
   requireSection(target.deck, slug);
-  return requestDevServer(target, {
-    method: "POST",
-    path: "goto",
-    body: { slug },
-  });
+  return requestDevServer(
+    target,
+    { method: "POST", path: "goto", body: { slug } },
+    options.timeoutMs ?? NAV_TIMEOUT_MS,
+  );
 }
 
-export async function currentCommand(target: DeckTarget): Promise<NavResult> {
-  return requestDevServer(target, { method: "GET", path: "current" });
+export async function currentCommand(
+  target: DeckTarget,
+  options: NavOptions = {},
+): Promise<NavResult> {
+  return requestDevServer(
+    target,
+    { method: "GET", path: "current" },
+    options.timeoutMs ?? NAV_TIMEOUT_MS,
+  );
 }
 
 async function requestDevServer(
   { project, deck }: DeckTarget,
   request: { method: "GET" | "POST"; path: "goto" | "current"; body?: { slug: string } },
+  timeoutMs: number,
 ): Promise<NavResult> {
   const deckName = deck.name;
   const lock = readDevServerLock(project.root);
@@ -43,16 +65,27 @@ async function requestDevServer(
   if (lock.password) {
     headers.authorization = `Basic ${btoa(`:${lock.password}`)}`;
   }
+  // A server that takes the connection but never answers is stuck; say so instead of waiting.
+  const signal = AbortSignal.timeout(timeoutMs);
+  const unlessStuck = (error: unknown): never => {
+    throw signal.aborted
+      ? new DekError(`the dev server at ${lock.url} did not answer within ${timeoutMs / 1000}s`, {
+          hint: "restart it: stop `dekc` and run it again",
+        })
+      : error;
+  };
+  // biome-ignore lint/style/noRestrictedGlobals: signal, an AbortSignal.timeout, bounds the request and the read of its answer.
   const response = await fetch(url, {
     method: request.method,
     headers: Object.keys(headers).length > 0 ? headers : undefined,
     body: request.body ? JSON.stringify(request.body) : undefined,
-  });
+    signal,
+  }).catch(unlessStuck);
   // Only the nav routes answer JSON; a 404, 401, or 405 from the server itself is plain text.
   if (!response.headers.get("content-type")?.includes("application/json")) {
     throw refusal(response.status, lock, deckName, request.path);
   }
-  const json = (await response.json()) as {
+  const json = (await response.json().catch(unlessStuck)) as {
     ok?: boolean;
     slug?: string;
     slideIndex?: number;
@@ -82,7 +115,7 @@ function refusal(
 ): DekError {
   if (status === 404 && lock.deck !== undefined && lock.deck !== deckName) {
     return new DekError(`the running dev server serves deck "${lock.deck}", not "${deckName}"`, {
-      hint: `pass --deck ${lock.deck}, or stop the server at ${lock.url} and run \`dekc ${deckName}\``,
+      hint: `pass ${deckFlag(lock.deck)}, or stop the server at ${lock.url} and run \`dekc ${isTypedCommand(deckName) ? deckFlag(deckName) : deckWord(deckName)}\``,
     });
   }
   if (status === 401) {

package/src/cli/init.ts

@@ -3,10 +3,12 @@ import { basename, join, resolve } from "node:path";
 import { parseCss, publishedTokens } from "../core/css.ts";
 import { deckPaths } from "../core/deck-paths.ts";
 import { DekError } from "../core/error.ts";
+import { shellQuote } from "../core/escape.ts";
 import { REQUIRED_TOKENS } from "../core/lint/tokens.ts";
 import { walkUp } from "../core/optional.ts";
 import { DECK_NAME_HINT, isDeckName } from "../core/path.ts";
-import { readTextIfExists } from "../core/resolve.ts";
+import { refuseInsideRef } from "../core/ref.ts";
+import { readSourceIfExists } from "../core/safe-fs.ts";
 import {
   defaultTsconfig,
   dekFilePaths,
@@ -25,7 +27,6 @@ import {
   nextSteps,
   type PlannedPath,
   playwrightStep,
-  shellQuote,
 } from "./files.ts";
 
 export type InitResult = {
@@ -84,7 +85,7 @@ export function initCommand(options: { cwd: string; dir?: string; deck?: string
 /** The tokens every deck needs that the project's theme.css does not publish on `.slide`. */
 function missingThemeTokens(root: string): string[] {
   const published = new Set(
-    publishedTokens(parseCss(readTextIfExists(join(root, "theme.css")) ?? "")).map(
+    publishedTokens(parseCss(readSourceIfExists(join(root, "theme.css"), root) ?? "")).map(
       (token) => token.name,
     ),
   );
@@ -100,8 +101,10 @@ function syncDeckFiles(deckDir: string, created: string[]): FileChanges {
 /** Everything init writes but `.dek/` and AGENTS.md, in the order a reader meets it. */
 function projectPlan(root: string, deck: string | undefined): PlannedPath[] {
   const themePath = join(root, "theme.css");
-  // A first deck is drawn in the theme that will be there: the one kept, or dek's.
-  const theme = readTextIfExists(themePath) ?? defaultTheme();
+  // A first deck is drawn in the theme that will be there: the one kept, or dek's. A folder that
+  // is not there yet holds no theme.
+  const theme =
+    (existsSync(root) ? readSourceIfExists(themePath, root) : undefined) ?? defaultTheme();
   return [
     { path: join(root, "dek.toml"), contents: defaultToml() },
     { path: themePath, contents: defaultTheme() },
@@ -123,6 +126,8 @@ function checkTarget(root: string): void {
   if (existsSync(root) && !statSync(root).isDirectory()) {
     throw new DekError("not a directory", { path: root, hint: "pass a directory to init" });
   }
+  // A ref is someone else's project, read where it is: init would write its files into it.
+  refuseInsideRef(root);
   const outer = walkUp(root, (dir) => {
     const config = join(dir, "dek.toml");
     return existsSync(config) && statSync(config).isFile() ? dir : undefined;

package/src/cli/lint.ts

@@ -1,13 +1,14 @@
 import { existsSync } from "node:fs";
 import { relative } from "node:path";
 import type { Diagnostic } from "../core/diagnostic.ts";
+import { shellQuote } from "../core/escape.ts";
 import { lintDeck, lintProject, unreadableScriptDiagnostics } from "../core/lint.ts";
 import { playwrightMissingError } from "../core/playwright.ts";
-import { resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
+import { type RumdlRunner, type RumdlSkip, resolveRumdlBin, runRumdl } from "../core/rumdl.ts";
 import { mergeSarif, type SarifLog } from "../core/sarif.ts";
 import { syncDeck } from "../core/sync.ts";
 import { lintVisualDeck } from "../core/visual.ts";
-import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
+import { RENDERED_RULES, type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
 import type { DecksTarget } from "./scope.ts";
 
 export type LintCliResult = {
@@ -17,10 +18,10 @@ export type LintCliResult = {
   rumdlSarif?: SarifLog;
 };
 
-/** `cwd` is where a skipped rumdl's hint says to run it from. */
+/** `cwd` is where a skipped rumdl's hint says to run it from; `rumdl` runs it, dek's by default. */
 export async function lintCommand(
   { project, decks, failed = [] }: DecksTarget,
-  options: { cwd: string; fix?: boolean; visual?: boolean },
+  options: { cwd: string; fix?: boolean; visual?: boolean; rumdl?: RumdlRunner },
 ): Promise<LintCliResult> {
   // dek.toml's findings once, then each deck's.
   const diagnostics: Diagnostic[] = [
@@ -29,19 +30,25 @@ export async function lintCommand(
   ];
   let rumdlSkip: SkippedCheck | undefined;
   let rumdlSarif: SarifLog | undefined;
+  // A rumdl that hung on one deck would hang on each, half a minute apiece.
+  let rumdlHung = false;
 
   for (const deck of decks) {
     if (options.fix) {
       syncDeck({ project, deck });
     }
     diagnostics.push(...lintDeck({ project, deck }));
-    const markdown = await runRumdl(deck.scriptPath);
-    diagnostics.push(...markdown.diagnostics);
-    if (markdown.skipped) {
-      rumdlSkip ??= rumdlSkipped(deck.scriptPath, options.cwd);
-    }
-    if (markdown.sarif) {
-      rumdlSarif = rumdlSarif ? mergeSarif(rumdlSarif, markdown.sarif) : markdown.sarif;
+    if (!rumdlHung) {
+      const markdown = await runRumdl(deck.scriptPath, options.rumdl);
+      diagnostics.push(...markdown.diagnostics);
+      // One entry for the run: the first reason, unless rumdl hung, which covers every deck after.
+      if (markdown.skipped && (!rumdlSkip || markdown.skipped.hung)) {
+        rumdlSkip = rumdlSkipped(deck.scriptPath, options.cwd, markdown.skipped);
+      }
+      rumdlHung = markdown.skipped?.hung === true;
+      if (markdown.sarif) {
+        rumdlSarif = rumdlSarif ? mergeSarif(rumdlSarif, markdown.sarif) : markdown.sarif;
+      }
     }
     if (options.visual) {
       const visual = await lintVisualDeck({ project, deck });
@@ -60,7 +67,7 @@ export async function lintCommand(
         ? []
         : [
             visualSkipped("dekc lint --visual", {
-              reason: "overflow and contrast are measured only with --visual",
+              reason: `${RENDERED_RULES} are measured only with --visual`,
             }),
           ]),
     ]),
@@ -70,15 +77,28 @@ export async function lintCommand(
 
 const RUMDL_INSTALL = "bun add -d rumdl; or put rumdl on PATH, or set DEK_RUMDL to its path";
 
-/** Why rumdl gave no result: dek looks for it on PATH, in node_modules/.bin, and at DEK_RUMDL. */
-function rumdlSkipped(scriptPath: string, cwd: string): SkippedCheck {
+const RUMDL_HUNG =
+  "update or reinstall rumdl (`bun add -d rumdl@latest`), or set DEK_RUMDL to a rumdl that finishes; lint skips it for every deck after one it hangs on";
+
+/**
+ * Why rumdl gave no result: whether dek found it, on PATH, in node_modules/.bin, or at DEK_RUMDL,
+ * and the reason when dek knows it. One that hung would hang again, so its hint is not to rerun.
+ */
+function rumdlSkipped(scriptPath: string, cwd: string, skip: RumdlSkip): SkippedCheck {
   const bin = resolveRumdlBin();
   if (bin === undefined || !existsSync(bin)) {
     return { check: "rumdl", reason: "rumdl is not installed", hint: RUMDL_INSTALL };
   }
+  if (skip.hung) {
+    return {
+      check: "rumdl",
+      reason: skip.reason ?? "rumdl hung and was stopped",
+      hint: RUMDL_HUNG,
+    };
+  }
   return {
     check: "rumdl",
-    reason: "rumdl ran but gave no result",
-    hint: `run \`${bin} check ${relative(cwd, scriptPath) || scriptPath}\` to see why`,
+    reason: skip.reason ?? "rumdl ran but gave no result",
+    hint: `run \`${shellQuote(bin)} check ${shellQuote(relative(cwd, scriptPath) || scriptPath)}\` to see why`,
   };
 }