@hajimism/dek 0.5.0 → 0.6.0

package/src/core/plugin.ts

@@ -0,0 +1,436 @@
+import { z } from "zod";
+import { formatZodIssues } from "./zod.ts";
+
+/**
+ * A plugin is an executable `dek-<name>` the user installed. It prints a manifest of what it promises,
+ * which dek checks and the project pins in `plugins/<name>/plugin.json`, and it checks a deck in a
+ * process of its own, answering in SARIF. This file is the part with no I/O: what a manifest may
+ * say, the lock it is pinned in, and the words dek writes about it. See ADR 32.
+ */
+
+/** The manifest schema and check protocol this dek reads; a plugin that needs a newer one is skipped. */
+const MANIFEST_SCHEMA = 1;
+export const CHECK_PROTOCOL = 1;
+/** The page API this dek gives a plugin's page (ADR 33). */
+const PAGE_API = 1;
+
+/** The letters the player binds, which no plugin's page may take; a test reads them from the runtime. */
+export const DEK_KEYS: readonly string[] = ["a", "f", "l", "m", "p", "s"];
+
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+const NAME_MAX = 40;
+
+/** Names whose rule ids would read as another tool's: dek's own, and rumdl's MD rules. */
+const RESERVED_NAMES: Record<string, string> = {
+  dek: "DEK is the prefix of dek's own rules",
+  md: "MD is the prefix of rumdl's rules",
+};
+
+/** What is wrong with `name` as a plugin's, or undefined when it is one. */
+export function pluginNameProblem(name: string): string | undefined {
+  if (!NAME_RE.test(name) || name.length > NAME_MAX) {
+    return `a plugin's name is a lowercase letter, then lowercase letters, digits, and hyphens, at most ${NAME_MAX}`;
+  }
+  const reserved = RESERVED_NAMES[name];
+  return reserved === undefined ? undefined : `\`${name}\` is not a plugin's name: ${reserved}`;
+}
+
+/** The prefix of a plugin's rule ids: `acme-talks` checks ACME_TALKS001 and on. */
+export function rulePrefix(name: string): string {
+  return name.toUpperCase().replaceAll("-", "_");
+}
+
+/** A rule's summary: one line of fact, which dek shows only where a tool lists rules, as SARIF. */
+const SUMMARY_MAX = 120;
+const VERSION_RE = /^[0-9A-Za-z][0-9A-Za-z.+-]{0,63}$/;
+
+/** The first folders of a deck that are dek's, and the files at its top, in lowercase. */
+const DEK_DECK_ENTRIES = new Set(["script.md", "theme.css", "slides", "assets", "voice", "dist"]);
+
+const Rule = z.object({
+  severity: z.enum(["error", "warning"]),
+  summary: z
+    .string()
+    .min(1)
+    .max(SUMMARY_MAX)
+    // Control characters, and the line and paragraph separators, would end the line.
+    .refine((text) => !/[\p{Cc}\p{Zl}\p{Zp}]/u.test(text), "summary: one line"),
+});
+
+const Check = z.object({
+  protocol: z.literal(CHECK_PROTOCOL),
+  rules: z.record(z.string(), Rule),
+});
+
+/**
+ * A data file: a path in the deck, or, with `in: "project"`, in the plugin's own `plugins/<name>/`
+ * in the project (ADR 35).
+ */
+const Data = z.object({ path: z.string(), in: z.literal("project").optional() });
+
+/** A page in the player and the build. Its script is the plugin's to ship; this dek reads only these. */
+const Page = z.object({
+  api: z.literal(PAGE_API),
+  keys: z.array(z.string()).optional(),
+});
+
+/** A manifest as this dek reads it. Fields it does not know are dropped, never passed on. */
+const Manifest = z.object({
+  schema: z.literal(MANIFEST_SCHEMA),
+  name: z.string(),
+  version: z.string().regex(VERSION_RE, "version: one token of letters, digits, and . + -"),
+  check: Check.optional(),
+  page: Page.optional(),
+  data: z.array(Data).optional(),
+});
+
+export type PluginManifest = z.output<typeof Manifest>;
+type PluginRule = z.output<typeof Rule>;
+
+/** A manifest dek can use, or why not; `unsupported` when it asks for a newer dek. */
+export type ManifestReading =
+  | { ok: true; manifest: PluginManifest }
+  | { ok: false; reason: string; unsupported?: true };
+
+/**
+ * What `dek-<name> manifest` printed, checked: its shape and versions, that it names the plugin
+ * dek ran, that every rule id has the plugin's prefix, and that each data file is the deck's own
+ * and not dek's. Only what this dek knows is kept, so the lock pins what it can act on.
+ */
+export function readManifest(value: unknown, name: string): ManifestReading {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, reason: "the manifest is not a JSON object" };
+  }
+  const fields = value as Record<string, unknown>;
+  if (above(fields.schema, MANIFEST_SCHEMA)) {
+    return newer(`manifest schema ${fields.schema}`);
+  }
+  const check = fields.check as Record<string, unknown> | undefined;
+  if (typeof check === "object" && check !== null && above(check.protocol, CHECK_PROTOCOL)) {
+    return newer(`check protocol ${check.protocol}`);
+  }
+  const page = fields.page as Record<string, unknown> | undefined;
+  if (typeof page === "object" && page !== null && above(page.api, PAGE_API)) {
+    return newer(`page API ${page.api}`);
+  }
+  const parsed = Manifest.safeParse(value);
+  if (!parsed.success) {
+    return { ok: false, reason: formatZodIssues(parsed.error) };
+  }
+  const manifest = parsed.data;
+  const problem =
+    (manifest.name === name
+      ? undefined
+      : `it names itself \`${manifest.name}\`, not \`${name}\``) ??
+    ruleProblem(manifest, name) ??
+    keyProblem(manifest) ??
+    dataProblem(manifest);
+  return problem === undefined
+    ? { ok: true, manifest: canonical(manifest) }
+    : { ok: false, reason: problem };
+}
+
+/** A version a later dek may read: a whole number past this dek's. Any other is malformed. */
+function above(version: unknown, supported: number): version is number {
+  return Number.isInteger(version) && (version as number) > supported;
+}
+
+function newer(what: string): ManifestReading {
+  return {
+    ok: false,
+    unsupported: true,
+    reason: `it needs ${what}; this dek reads manifest schema ${MANIFEST_SCHEMA}, check protocol ${CHECK_PROTOCOL}, and page API ${PAGE_API}`,
+  };
+}
+
+/** A page's keys are single lowercase letters, each once, none of them the player's. */
+function keyProblem(manifest: PluginManifest): string | undefined {
+  const keys = manifest.page?.keys ?? [];
+  const wrong = keys.find((key) => !/^[a-z]$/.test(key));
+  if (wrong !== undefined) {
+    return "page.keys: a key is one lowercase letter, a to z";
+  }
+  const taken = keys.find((key) => DEK_KEYS.includes(key));
+  if (taken !== undefined) {
+    return `page.keys: \`${taken}\` is a key of dek's player; take a letter other than ${DEK_KEYS.join(" ")}`;
+  }
+  const twice = keys.find((key, index) => keys.indexOf(key) !== index);
+  return twice === undefined ? undefined : `page.keys: \`${twice}\` is named twice`;
+}
+
+function ruleProblem(manifest: PluginManifest, name: string): string | undefined {
+  const prefix = rulePrefix(name);
+  const id = new RegExp(`^${prefix}\\d{3}$`);
+  const wrong = Object.keys(manifest.check?.rules ?? {}).find((rule) => !id.test(rule));
+  return wrong === undefined
+    ? undefined
+    : `check.rules: \`${wrong}\` is no rule id of this plugin's; write ${prefix} and three digits, like ${prefix}001`;
+}
+
+function dataProblem(manifest: PluginManifest): string | undefined {
+  const seen = new Set<string>();
+  for (const entry of manifest.data ?? []) {
+    const shown = dataPath(manifest.name, entry);
+    const problem = dataPathProblem(entry);
+    if (problem) {
+      return `data: \`${entry.path}\` ${problem}`;
+    }
+    if (seen.has(shown)) {
+      return `data: \`${shown}\` is named twice`;
+    }
+    seen.add(shown);
+  }
+  return undefined;
+}
+
+type DataEntry = NonNullable<PluginManifest["data"]>[number];
+
+/** A data file as an agent finds it: in the deck, or in the project when it is the project's. */
+function dataPath(name: string, entry: DataEntry): string {
+  return entry.in === "project" ? `plugins/${name}/${entry.path}` : entry.path;
+}
+
+/**
+ * A data file is a path inside its folder, `/`-separated, through no hidden folder. In a deck it
+ * is none of the files and folders dek reads or writes there; in `plugins/<name>/` it is not the
+ * lock.
+ */
+function dataPathProblem({ path, in: level }: DataEntry): string | undefined {
+  const folder = level === "project" ? "plugins/<name>/" : "the deck";
+  if (path === "" || path.startsWith("/") || path.includes("\\")) {
+    return `is not a path relative to ${folder}`;
+  }
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return `is not a path inside ${folder}`;
+  }
+  if (segments.some((segment) => segment.startsWith("."))) {
+    return "is hidden, and dek reads no hidden file of a plugin's";
+  }
+  // A Mac's disk and Windows' take `Slides` for `slides`.
+  const first = (segments[0] ?? "").normalize("NFC").toLowerCase();
+  if (level === "project") {
+    return segments.length === 1 && first === "plugin.json" ? "is the plugin's lock" : undefined;
+  }
+  if (DEK_DECK_ENTRIES.has(first)) {
+    return "is dek's";
+  }
+  return undefined;
+}
+
+/** The manifest with its keys in one order, so the same promise is always the same lock. */
+function canonical(manifest: PluginManifest): PluginManifest {
+  const rules = manifest.check?.rules;
+  return {
+    schema: manifest.schema,
+    name: manifest.name,
+    version: manifest.version,
+    ...(manifest.check && rules
+      ? {
+          check: {
+            protocol: manifest.check.protocol,
+            rules: Object.fromEntries(
+              Object.keys(rules)
+                .sort()
+                .map((id) => {
+                  const rule = rules[id] as PluginRule;
+                  return [id, { severity: rule.severity, summary: rule.summary }];
+                }),
+            ),
+          },
+        }
+      : {}),
+    ...(manifest.page
+      ? { page: { api: manifest.page.api, keys: [...(manifest.page.keys ?? [])].sort() } }
+      : {}),
+    ...(manifest.data
+      ? {
+          data: manifest.data.map((entry) =>
+            entry.in === "project" ? { path: entry.path, in: entry.in } : { path: entry.path },
+          ),
+        }
+      : {}),
+  };
+}
+
+/** `plugins/<name>/plugin.json`: the manifest the project accepted, which is its lock. */
+export function lockText(manifest: PluginManifest): string {
+  return `${JSON.stringify({ accepted: canonical(manifest) }, null, 2)}\n`;
+}
+
+/** The manifest a lock pins, read as `manifest`'s output is, so a newer dek's fields are left out. */
+export function readLock(text: string, name: string): ManifestReading {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: "it is not JSON" };
+  }
+  const accepted =
+    typeof parsed === "object" && parsed !== null
+      ? (parsed as { accepted?: unknown }).accepted
+      : undefined;
+  if (accepted === undefined) {
+    return { ok: false, reason: "it has no `accepted` manifest" };
+  }
+  return readManifest(accepted, name);
+}
+
+/**
+ * What changed from the manifest the project accepted to the one installed, one line per change
+ * in dek's words: the version, each rule added, removed, or changed, and each data file.
+ */
+export function manifestChanges(accepted: PluginManifest, installed: PluginManifest): string[] {
+  const changes: string[] = [];
+  if (accepted.version !== installed.version) {
+    changes.push(`version ${accepted.version} → ${installed.version}`);
+  }
+  changes.push(...checkChanges(accepted.check, installed.check));
+  changes.push(...pageChanges(accepted.page, installed.page));
+  const paths = (manifest: PluginManifest) =>
+    new Set((manifest.data ?? []).map((entry) => dataPath(manifest.name, entry)));
+  const before = paths(accepted);
+  const after = paths(installed);
+  for (const path of before) {
+    if (!after.has(path)) {
+      changes.push(`data ${path} removed`);
+    }
+  }
+  for (const path of after) {
+    if (!before.has(path)) {
+      changes.push(`data ${path} added`);
+    }
+  }
+  return changes;
+}
+
+function pageChanges(
+  accepted: PluginManifest["page"],
+  installed: PluginManifest["page"],
+): string[] {
+  const keys = (page: PluginManifest["page"]) => (page?.keys ?? []).join(", ") || "none";
+  if (!accepted && !installed) {
+    return [];
+  }
+  if (!installed) {
+    return ["page removed"];
+  }
+  if (!accepted) {
+    return [`page added (keys ${keys(installed)})`];
+  }
+  return keys(accepted) === keys(installed)
+    ? []
+    : [`page keys ${keys(accepted)} → ${keys(installed)}`];
+}
+
+function checkChanges(
+  accepted: PluginManifest["check"],
+  installed: PluginManifest["check"],
+): string[] {
+  if (!accepted && !installed) {
+    return [];
+  }
+  if (!installed) {
+    return ["check removed"];
+  }
+  if (!accepted) {
+    const rules = Object.entries(installed.rules)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([id, rule]) => `${id} (${rule.severity})`);
+    return [`check added: ${rules.join(", ")}`];
+  }
+  const changes: string[] = [];
+  const ids = [
+    ...new Set([...Object.keys(accepted.rules), ...Object.keys(installed.rules)]),
+  ].sort();
+  for (const id of ids) {
+    const before = accepted.rules[id];
+    const after = installed.rules[id];
+    if (!after) {
+      changes.push(`${id} removed`);
+    } else if (!before) {
+      changes.push(`${id} added (${after.severity})`);
+    } else if (before.severity !== after.severity) {
+      changes.push(`${id} ${before.severity} → ${after.severity}`);
+    } else if (before.summary !== after.summary) {
+      changes.push(`${id} summary changed`);
+    }
+  }
+  return changes;
+}
+
+/** A plugin dek.toml names, with the manifest its lock pins when it has one. */
+export type PinnedPlugin = { name: string; manifest: PluginManifest | undefined };
+
+/**
+ * The plugins in AGENTS.md: one line each, made from the lock and never from the executable, so
+ * every sync writes the same block, the dev server's included. Each line is dek's words about
+ * checked fields; the plugin's own summaries stay out. Empty when dek.toml names no plugin.
+ */
+export function pluginsSection(plugins: PinnedPlugin[]): string {
+  if (plugins.length === 0) {
+    return "";
+  }
+  const lines = plugins.map(({ name, manifest }) => {
+    if (!manifest) {
+      return `- \`${name}\`: not pinned yet; \`dekc sync\` pins it.`;
+    }
+    const facts = [
+      ...(manifest.check
+        ? [`\`dekc lint\` checks ${ruleList(Object.keys(manifest.check.rules))}.`]
+        : []),
+      ...(manifest.data && manifest.data.length > 0
+        ? [
+            `Its data: ${projectFirst(manifest.data)
+              .map((entry) => `\`${dataPath(name, entry)}\``)
+              .join(", ")}.`,
+          ]
+        : []),
+      ...(manifest.page?.keys && manifest.page.keys.length > 0
+        ? [
+            `Its page takes the ${manifest.page.keys.length === 1 ? "key" : "keys"} ${manifest.page.keys.map((key) => `\`${key}\``).join(", ")}.`,
+          ]
+        : []),
+    ];
+    return `- \`${name}\` ${manifest.version}${facts.length > 0 ? `: ${facts.join(" ")}` : ""}`;
+  });
+  return `
+## Plugins
+
+Checks installed beside dek, named in \`dek.toml\` \`[plugins]\` and pinned in \`plugins/<name>/plugin.json\`. \`dekc lint\` runs them with dek's own rules; their findings carry the plugin's rule ids.
+
+${lines.join("\n")}
+`;
+}
+
+/** The project's data files, then the deck's, each in the order the manifest gave them. */
+function projectFirst(data: DataEntry[]): DataEntry[] {
+  return [...data.filter((entry) => entry.in === "project"), ...data.filter((e) => !e.in)];
+}
+
+function ruleList(ids: string[]): string {
+  const sorted = [...ids].sort();
+  if (sorted.length === 0) {
+    return "no rules";
+  }
+  if (sorted.length === 1) {
+    return sorted[0] as string;
+  }
+  if (sorted.length === 2) {
+    return `${sorted[0]} and ${sorted[1]}`;
+  }
+  const numbers = sorted.map((id) => Number(id.slice(-3)));
+  const contiguous = numbers.every((n, i) => i === 0 || n === (numbers[i - 1] as number) + 1);
+  return contiguous ? `${sorted[0]} to ${sorted.at(-1)}` : sorted.join(", ");
+}
+
+/**
+ * A plugin's page as the player and the build carry it: its script, the keys its manifest
+ * declares, and each declared data file the deck has, with a version that changes with the text.
+ */
+export type PluginPage = {
+  name: string;
+  keys: string[];
+  script: string;
+  data: Record<string, { text: string; version: string }>;
+};

package/src/core/sandbox.ts

@@ -46,7 +46,7 @@ const CHROMIUM_SAYS = /\[err\]|FATAL/;
 const REASON_CHARS = 280;
 
 /** A sentence: up to a `.`, `!`, or `?` that ends a word, outside parentheses, as `(0 vs. 1)` is. */
-const SENTENCE = /(?:\([^)]*\)|\((?!\)|$)|[^()!?\.]|[.!?](?!\s|$))+(?:[.!?]+|$)/g;
+const SENTENCE = /(?:\([^)]*\)|\((?!\)|$)|[^()!?.]|[.!?](?!\s|$))+(?:[.!?]+|$)/g;
 
 /**
  * What Chromium said when it failed: its words for a sandbox that cannot start, else its first

package/src/core/sarif.ts

@@ -1,6 +1,13 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { type Diagnostic, type DiagnosticValue, RULES, type SkippedCheck } from "./diagnostic.ts";
+import {
+  type Diagnostic,
+  type DiagnosticValue,
+  RULES,
+  type SkippedCheck,
+  skippedLabel,
+} from "./diagnostic.ts";
+import type { PluginManifest } from "./plugin.ts";
 
 type SarifLevel = "error" | "warning" | "note" | "none";
 
@@ -11,8 +18,14 @@ export type SarifLog = {
     tool: {
       driver: {
         name: string;
+        version?: string;
         informationUri?: string;
-        rules?: Array<{ id: string; defaultConfiguration: { level: SarifLevel }; helpUri: string }>;
+        rules?: Array<{
+          id: string;
+          shortDescription?: { text: string };
+          defaultConfiguration: { level: SarifLevel };
+          helpUri?: string;
+        }>;
       };
     };
     invocations?: Array<{
@@ -74,10 +87,11 @@ export function toSarif(
                   executionSuccessful: true,
                   toolExecutionNotifications: skipped.map((entry) => ({
                     level: "warning" as const,
-                    message: { text: `${entry.check}: skipped (${entry.reason})` },
+                    message: { text: `${skippedLabel(entry)}: skipped (${entry.reason})` },
                     descriptor: { id: `skipped/${entry.check}` },
                     properties: {
                       check: entry.check,
+                      ...(entry.plugin === undefined ? {} : { plugin: entry.plugin }),
                       ...(entry.hint === undefined ? {} : { hint: entry.hint }),
                     },
                   })),
@@ -91,6 +105,33 @@ export function toSarif(
   };
 }
 
+/**
+ * Each plugin's findings as a run of its own, under the plugin's name and version, with the rules
+ * its accepted manifest declares. A plugin that found nothing still has its run: it ran.
+ */
+export function pluginSarif(
+  plugins: Array<{ name: string; manifest: PluginManifest; diagnostics: Diagnostic[] }>,
+): SarifLog {
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: plugins.map(({ name, manifest, diagnostics }) => ({
+      tool: {
+        driver: {
+          name: `dek-${name}`,
+          version: manifest.version,
+          rules: Object.entries(manifest.check?.rules ?? {}).map(([id, rule]) => ({
+            id,
+            shortDescription: { text: rule.summary },
+            defaultConfiguration: { level: rule.severity },
+          })),
+        },
+      },
+      results: diagnostics.map(sarifResult),
+    })),
+  };
+}
+
 function sarifResult(diagnostic: Diagnostic): SarifLog["runs"][number]["results"][number] {
   const properties = {
     ...(diagnostic.slug === undefined ? {} : { slug: diagnostic.slug }),
@@ -126,10 +167,11 @@ function sarifResult(diagnostic: Diagnostic): SarifLog["runs"][number]["results"
   };
 }
 
-export function mergeSarif(dek: SarifLog, rumdl?: SarifLog): SarifLog {
+/** One log of every run in `dek` and the logs after it, such as rumdl's and the plugins'. */
+export function mergeSarif(dek: SarifLog, ...others: Array<SarifLog | undefined>): SarifLog {
   return {
     version: "2.1.0",
     $schema: dek.$schema,
-    runs: [...dek.runs, ...(rumdl?.runs ?? [])],
+    runs: [...dek.runs, ...others.flatMap((log) => log?.runs ?? [])],
   };
 }

package/src/core/slide-measure.ts

@@ -251,6 +251,7 @@ export function measureSlideInPage(): SlideMeasure {
     const own = squash(textNodes.map((node) => node.textContent ?? "").join(" "));
     // innerText separates block children; textContent would run "item 0item 1" together.
     // SVG and MathML have no innerText, so they fall back to textContent.
+    // biome-ignore lint/performance/useDomNodeTextContent: the rendered line breaks are the point here.
     const whole = el instanceof HTMLElement ? el.innerText : el.textContent;
     const text = own || squash(whole ?? "");
     const parentEl = el.parentElement;

package/src/core/spawn.ts

@@ -75,10 +75,16 @@ export async function runPiped(cmd: string[], options: PipedOptions): Promise<Pi
       hint: `it did not finish within ${Math.round(options.timeoutMs / 1000)}s and was stopped`,
     });
   try {
-    if (options.stdin !== undefined) {
-      proc.stdin.write(options.stdin);
+    try {
+      if (options.stdin !== undefined) {
+        // A write the pipe cannot take at once returns a promise, which can reject with the pipe.
+        await proc.stdin.write(options.stdin);
+      }
+      await proc.stdin.end();
+    } catch {
+      // The pipe broke: the command exited without reading all of its stdin, as `head` does, or
+      // was killed at its timeout while a write waited on it. Its exit says which, and how it went.
     }
-    await proc.stdin.end();
     const exitCode = await proc.exited;
     // It finished in time, however long what it left behind keeps the pipes open.
     stop.clear();
@@ -91,10 +97,6 @@ export async function runPiped(cmd: string[], options: PipedOptions): Promise<Pi
     if (error instanceof DekError) {
       throw error;
     }
-    // Killing the command breaks the pipe a write to its stdin was waiting on.
-    if (stop.fired()) {
-      throw overrun();
-    }
     throw new DekError(options.label, { hint: options.hint, cause: error });
   } finally {
     stop.clear();

package/src/core/sync.ts

@@ -3,6 +3,8 @@ import { join } from "node:path";
 import { loadConfig } from "./config.ts";
 import { type DeckPaths, deckPaths } from "./deck-paths.ts";
 import { foreignLine, TITLE_MAX } from "./foreign-text.ts";
+import { pluginsSection } from "./plugin.ts";
+import { pinnedPlugins } from "./plugin-host.ts";
 import { parseRefSource, refDir, refTitle } from "./ref.ts";
 import { asResolvedDeck, listSlides, type ResolvedDeck, SLIDE_SIDECARS } from "./resolve.ts";
 import { outputDir, readSourceIfExists, removeInside, writeInside } from "./safe-fs.ts";
@@ -289,7 +291,7 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 - \`dekc lint --visual\` passes.
 - You have read \`dekc shot --sheet\` and judged the deck's balance.
 - Say what you could not judge, such as the argument and the timing, and leave it to the author.
-${referencesSection(root)}
+${referencesSection(root)}${pluginsSection(pinnedPlugins(root))}
 For commands, run \`dekc help --agent\`.
 `;
 }