@hajimism/dek 0.5.0 → 0.6.0

package/src/core/config.ts

@@ -4,6 +4,7 @@ import { DekError } from "./error.ts";
 import { shellQuote } from "./escape.ts";
 import { isPackLicense, PACK_LICENSES, type PackLicense } from "./licenses.ts";
 import { parsePublicUrl } from "./ogp.ts";
+import { pluginNameProblem } from "./plugin.ts";
 import {
   isPinFor,
   isPlainRefName,
@@ -31,6 +32,12 @@ export const Pack = z.object({
     .optional(),
 });
 
+/**
+ * A plugin's table in `[plugins]`. It takes no key yet: a project chooses which of the plugins the
+ * user installed it uses, and never names a path, an argument, or a program for dek to run.
+ */
+export const PluginTable = z.object({});
+
 export const DekToml = z.object({
   url: z
     .string()
@@ -71,6 +78,18 @@ export const DekToml = z.object({
     })
     .transform((refs) => refs as Record<string, string>)
     .optional(),
+  // A name that is no plugin's is refused without being repeated, as a ref's is.
+  plugins: z
+    .record(z.string(), PluginTable)
+    .superRefine((plugins, ctx) => {
+      for (const name of Object.keys(plugins)) {
+        const problem = pluginNameProblem(name);
+        if (problem) {
+          ctx.addIssue({ code: "custom", path: [], message: problem });
+        }
+      }
+    })
+    .optional(),
 });
 
 const REFUSED_REF_KEY = "a key in [refs] names no ref";
@@ -107,6 +126,37 @@ function refusedRefKey(source: string): { line?: number } | undefined {
   return entry === undefined ? {} : { line: entry.line };
 }
 
+/**
+ * The first name in [plugins] that is no plugin's, with what is wrong and its line. Like a ref's,
+ * the name may be someone else's text, so the error points at it and never repeats it.
+ */
+function refusedPluginKey(source: string): { problem: string; line?: number } | undefined {
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(source);
+  } catch {
+    return undefined;
+  }
+  const plugins = (parsed as { plugins?: unknown } | null)?.plugins;
+  if (plugins === null || typeof plugins !== "object") {
+    return undefined;
+  }
+  for (const name of Object.keys(plugins)) {
+    const problem = pluginNameProblem(name);
+    if (problem === undefined) {
+      continue;
+    }
+    const written = scanTomlKeys(source).filter(
+      (entry) => entry.path[0] === "plugins" && entry.path.length === 2,
+    );
+    const entry =
+      written.find((key) => key.path[1] === name) ??
+      written.find((key) => pluginNameProblem(key.path[1] ?? "") !== undefined);
+    return entry === undefined ? { problem } : { problem, line: entry.line };
+  }
+  return undefined;
+}
+
 type VoiceDefaults = {
   engine: string;
   speaker: string;
@@ -126,6 +176,8 @@ export type DekConfig = {
   pack?: { license?: PackLicense };
   /** `[refs]`: each ref name and what it is pinned to: a commit, or a pack's digest. */
   refs?: Record<string, string>;
+  /** `[plugins]`: the name of each plugin the project uses, sorted, as dek runs them. */
+  plugins?: string[];
 };
 
 export function parseDekToml(source: string, path?: string): DekConfig {
@@ -133,6 +185,14 @@ export function parseDekToml(source: string, path?: string): DekConfig {
   if (refused) {
     throw new DekError(REFUSED_REF_KEY, { path, ...refused, hint: REFUSED_REF_HINT });
   }
+  const plugin = refusedPluginKey(source);
+  if (plugin) {
+    throw new DekError(`a name in [plugins] is no plugin's: ${plugin.problem}`, {
+      path,
+      ...(plugin.line === undefined ? {} : { line: plugin.line }),
+      hint: "rename the table to the <name> of the dek-<name> you installed, or delete it",
+    });
+  }
   const data = parseTomlWith(DekToml, source, {
     label: "dek.toml",
     anchor: "dek-toml",
@@ -155,6 +215,9 @@ export function parseDekToml(source: string, path?: string): DekConfig {
       ? { pack: data.pack.license ? { license: data.pack.license as PackLicense } : {} }
       : {}),
     ...(data.refs && Object.keys(data.refs).length > 0 ? { refs: data.refs } : {}),
+    ...(data.plugins && Object.keys(data.plugins).length > 0
+      ? { plugins: Object.keys(data.plugins).sort() }
+      : {}),
   };
 }
 

package/src/core/diagnostic.ts

@@ -64,6 +64,7 @@ export const RULES = {
   DEK043: { severity: "warning", scopes: ["deck"] },
   DEK044: { severity: "warning", scopes: ["deck", "slide"] },
   DEK045: { severity: "warning", scopes: ["deck"] },
+  DEK046: { severity: "error", scopes: ["deck"] },
 } as const satisfies Record<string, { severity: Severity; scopes: readonly Scope[] }>;
 
 export type RuleId = keyof typeof RULES;
@@ -113,7 +114,14 @@ export function hasErrors(diagnostics: Diagnostic[]): boolean {
  */
 export type SkippedCheck = {
   /** `preview` is a build's link preview image, which needs a URL and Playwright. */
-  check: "lint" | "preview" | "rumdl" | "visual" | "voice";
+  check: "lint" | "plugin" | "preview" | "rumdl" | "visual" | "voice";
+  /** The plugin, for a `plugin` check: its name in dek.toml `[plugins]`. */
+  plugin?: string;
   reason: string;
   hint?: string;
 };
+
+/** A skipped check as text names it: the check, or the plugin for a plugin's. */
+export function skippedLabel(entry: SkippedCheck): string {
+  return entry.plugin === undefined ? entry.check : `plugin ${entry.plugin}`;
+}

package/src/core/document.ts

@@ -4,6 +4,7 @@ import { escapeAttr, escapeHtml } from "./escape.ts";
 import { collectSlidesHtml, htmlShell } from "./html.ts";
 import { type OgpImage, ogpHead } from "./ogp.ts";
 import { PAGE_ID, type PageMode, pageConfigAttrs } from "./page.ts";
+import type { PluginPage } from "./plugin.ts";
 import {
   nextPresenterTitle,
   presenterSlides,
@@ -49,14 +50,19 @@ export type PageTarget =
 /** The deck at `dir`, rendered for `target`. */
 export function renderDeckHtml(
   dir: string,
-  options: { playerScript: string; target: PageTarget },
+  options: { playerScript: string; target: PageTarget; plugins?: PluginPage[] },
 ): string {
   return renderDeckDocument(resolveDeck(dir).deck, options);
 }
 
 export function renderDeckDocument(
   deck: ProjectDeck,
-  options: { playerScript: string; target: PageTarget },
+  options: {
+    playerScript: string;
+    target: PageTarget;
+    /** Each plugin's page; only the player and the build carry them (ADR 33). */
+    plugins?: PluginPage[];
+  },
 ): string {
   const { target } = options;
   const mode: PageMode =
@@ -160,7 +166,8 @@ export function renderDeckDocument(
   ${slideScriptTags(slideScripts)}
   <script>${options.playerScript}</script>
   ${target.kind === "dev" ? `<script>${target.liveReloadScript}</script>` : ""}
-  ${target.kind === "dev" && includeNotes ? `<script>${target.annotateScript}</script>` : ""}`,
+  ${target.kind === "dev" && includeNotes ? `<script>${target.annotateScript}</script>` : ""}
+  ${pluginPagesHtml(target, options.plugins ?? [])}`,
   });
 }
 
@@ -225,6 +232,24 @@ function renderKeyHintHtml(lang: string): string {
   return `<div id="${PAGE_ID.hint}" role="status"><span><kbd>s</kbd>${labels.rail}</span><span><kbd>p</kbd>${labels.presenter}</span></div>`;
 }
 
+/**
+ * The plugins' pages, after the player, which gives them `dek.plugin`: their keys and data as one
+ * JSON block, then each script in name order. Only the player and the build carry them; the
+ * presenter view and a video, like every still page, never do.
+ */
+function pluginPagesHtml(target: PageTarget, plugins: PluginPage[]): string {
+  const carried = target.kind === "build" || (target.kind === "dev" && target.mode === "player");
+  if (!carried || plugins.length === 0) {
+    return "";
+  }
+  const ordered = plugins.toSorted((a, b) => a.name.localeCompare(b.name));
+  const config = Object.fromEntries(ordered.map(({ name, keys, data }) => [name, { keys, data }]));
+  return [
+    `<script type="application/json" id="${PAGE_ID.plugins}">${jsonForScript(config)}</script>`,
+    ...ordered.map(({ script }) => `<script>${script.replace(/<\/(script)/gi, "<\\/$1")}</script>`),
+  ].join("\n  ");
+}
+
 function jsonForScript(value: unknown): string {
   return JSON.stringify(value).replace(/</g, "\\u003c");
 }

package/src/core/lint/context.ts

@@ -26,6 +26,8 @@ type SlideSource = { html: string; scan: HtmlScan; skeleton: boolean };
 export type LintContext = DeckFiles & {
   /** DEK016 and DEK017 of each slide script, by slug: evaluated before the rules run. */
   scripts: Map<string, Diagnostic[]>;
+  /** The source of each slide script lint evaluated, by slug. */
+  scriptCode: Map<string, string>;
 };
 
 /** The deck as read from disk, each file once. */

package/src/core/lint/shared-styles.ts

@@ -2,6 +2,7 @@ import { isKeyframesPrelude, selectorClasses, splitSelectorList, startsAtSlide }
 import { deckPaths } from "../deck-paths.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import { listed } from "../prose.ts";
+import { RUNTIME_CLASSES } from "../theme-facts.ts";
 import type { LintContext } from "./context.ts";
 
 /** How many slides may style something alike before it belongs in the theme: the third copy. */
@@ -56,6 +57,21 @@ function alsoReaches(ctx: LintContext, selector: string, setters: string[]): str
   });
 }
 
+/**
+ * How many classes theme.css would define with a rule under `selector` moved into it, when that
+ * is more than the deck's `max_classes` (DEK013); nothing while the move stays within it.
+ */
+function overBudget(ctx: LintContext, selector: string): number | undefined {
+  const defined = ctx.theme?.classes ?? new Set<string>();
+  const added = new Set(
+    selectorClasses(themeSelector(selector)).filter(
+      (name) => !defined.has(name) && !RUNTIME_CLASSES.has(name),
+    ),
+  );
+  const after = defined.size + added.size;
+  return added.size > 0 && after > ctx.deck.deck.max_classes ? after : undefined;
+}
+
 /**
  * DEK026: the same declaration under the same selector in the stylesheets of SHARED_BY slides
  * or more. Each slide fixed alike on its own, as agents working on one slide each will, is one
@@ -146,18 +162,27 @@ export function sharedStyleDiagnostics(ctx: LintContext): Diagnostic[] {
                 .join(
                   "",
                 )} without it, so check ${reaches.length === 1 ? "that slide" : "those slides"} after the move`;
+        // Following the hint must not trade this warning for DEK013's error.
+        const themeClasses = overBudget(ctx, selector);
+        const budget =
+          themeClasses === undefined
+            ? ""
+            : `; theme.css would then define ${themeClasses} classes, past max_classes ${ctx.deck.deck.max_classes}, so set \`max_classes: ${themeClasses}\` in the frontmatter too, or leave the rule in the slides`;
         return diag("DEK026", {
           message: `${rule} is also in ${listed(others)}`,
           path: paths.slide(slug, ".css"),
           line,
           slug,
-          hint: `write ${themeRule} once in theme.css and delete it from ${listed(slugs.map(cssOf))}${affected}`,
+          hint: `write ${themeRule} once in theme.css and delete it from ${listed(slugs.map(cssOf))}${affected}${budget}`,
           data: {
             selector,
             declarations,
             slides: slugs,
             ...(atPath.length > 0 ? { atRules: atPath } : {}),
             ...(reaches.length > 0 ? { alsoReaches: reaches } : {}),
+            ...(themeClasses !== undefined
+              ? { themeClasses, limit: ctx.deck.deck.max_classes }
+              : {}),
           },
         });
       }),

package/src/core/lint/theme-css.ts

@@ -12,6 +12,8 @@ import {
 } from "../css.ts";
 import { deckPaths } from "../deck-paths.ts";
 import { type Diagnostic, diag } from "../diagnostic.ts";
+import { escapeRegExp } from "../escape.ts";
+import { listed } from "../prose.ts";
 import { assetRefDiagnostics } from "./asset-refs.ts";
 import type { LintContext } from "./context.ts";
 import { isRawThemeValue, isRawTokenValue, REQUIRED_TOKENS, tokenSuggestion } from "./tokens.ts";
@@ -24,14 +26,18 @@ function missingThemeDiagnostic(ctx: LintContext): Diagnostic {
   return diag("DEK018", {
     message: "theme.css not found",
     path: deckPaths(ctx.deck.dir).theme,
-    hint: "copy theme.css from the project root or another deck into the deck directory",
+    hint: "copy the project's template, ../../theme.css, or another deck's theme into the deck directory",
   });
 }
 
 /** DEK012, DEK013, DEK015, DEK014, and what its `url()`s load (DEK020 to DEK023) for theme.css. */
 function lintTheme(
   { path, sheet, classes, tokens }: NonNullable<LintContext["theme"]>,
-  { maxClasses, deckDir }: { maxClasses: number; deckDir: string },
+  {
+    maxClasses,
+    deckDir,
+    usedBy,
+  }: { maxClasses: number; deckDir: string; usedBy: Map<string, string[]> | undefined },
 ): Diagnostic[] {
   const diagnostics: Diagnostic[] = [];
   // A rule inside `@media` reaches the page as surely as one outside it.
@@ -56,6 +62,7 @@ function lintTheme(
       diag("DEK013", {
         message: `theme.css has ${classCount} classes; limit is ${maxClasses}`,
         path,
+        hint: classBudgetHint(classCount, usedBy),
         data: { classes: classCount, limit: maxClasses },
       }),
     );
@@ -287,9 +294,63 @@ function themeScopeHint(selector: string): string {
   return `write it as ${scoped.join(", ")}`;
 }
 
+/**
+ * How to bring the theme back within its class budget: first what frees a class without changing
+ * a slide, a class no slide uses and one only one slide uses, then raising the budget itself.
+ */
+function classBudgetHint(classCount: number, usedBy: Map<string, string[]> | undefined): string {
+  if (usedBy === undefined) {
+    return `set \`max_classes: ${classCount}\` in the frontmatter`;
+  }
+  const unused = [...usedBy].filter(([, slugs]) => slugs.length === 0).map(([name]) => `.${name}`);
+  const single = [...usedBy].flatMap(([name, slugs]) =>
+    slugs.length === 1 ? [`.${name} into slides/${slugs[0]}.css`] : [],
+  );
+  return [
+    ...(unused.length > 0 ? [`delete ${listed(unused)}, which no slide uses`] : []),
+    ...(single.length > 0
+      ? [`move each class only one slide uses into that slide's stylesheet: ${listed(single)}`]
+      : []),
+    `set \`max_classes: ${classCount}\` in the frontmatter`,
+  ].join("; or ");
+}
+
+/**
+ * Each class the theme defines but `.slide`, which every slide is, to the slides that use it, in
+ * script order: in their markup, or anywhere in their script, which may set it with `classList`.
+ * None while a section has no HTML yet or only its skeleton: what it will use is unknown.
+ */
+function slidesUsing(ctx: LintContext, classes: Set<string>): Map<string, string[]> | undefined {
+  const usedBy = new Map(
+    [...classes].filter((name) => name !== "slide").map((name) => [name, [] as string[]]),
+  );
+  for (const slug of ctx.sectionsBySlug.keys()) {
+    const source = ctx.slideSource(slug);
+    if (source === undefined || source.skeleton) {
+      return undefined;
+    }
+    const code = ctx.scriptCode.get(slug);
+    for (const [name, slugs] of usedBy) {
+      if (source.scan.classes.includes(name) || (code !== undefined && namesClass(code, name))) {
+        slugs.push(slug);
+      }
+    }
+  }
+  return usedBy;
+}
+
+/** Whether `code` holds `name` as a class token: a word of its own, wherever it stands. */
+function namesClass(code: string, name: string): boolean {
+  return new RegExp(`(^|[^\\w-])${escapeRegExp(name)}($|[^\\w-])`).test(code);
+}
+
 /** The theme's own findings, or DEK018 when there is no theme. */
 export function themeDiagnostics(ctx: LintContext): Diagnostic[] {
   return ctx.theme
-    ? lintTheme(ctx.theme, { maxClasses: ctx.deck.deck.max_classes, deckDir: ctx.deck.dir })
+    ? lintTheme(ctx.theme, {
+        maxClasses: ctx.deck.deck.max_classes,
+        deckDir: ctx.deck.dir,
+        usedBy: slidesUsing(ctx, ctx.theme.classes),
+      })
     : [missingThemeDiagnostic(ctx)];
 }

package/src/core/lint.ts

@@ -18,6 +18,7 @@ import { timingDiagnostics } from "./lint/timing.ts";
 import { voiceDiagnostics } from "./lint/voice.ts";
 import { asResolvedDeck, type Project, type ProjectDeck } from "./resolve.ts";
 import type { Section } from "./schema.ts";
+import type { SlideScriptProblem } from "./slide-script.ts";
 import { evaluateSlideScripts, slideScriptsProblems } from "./slide-script-eval.ts";
 import { RUNTIME_CLASSES } from "./theme-facts.ts";
 
@@ -53,7 +54,7 @@ export function lintDeck(
 export function lintDeck(input: DeckInput, options?: LintDeckOptions): Diagnostic[] {
   const { files, scripted } = readLintInput(input);
   const problems = slideScriptsProblems(scripted.map((entry) => entry.input));
-  return runRules({ ...files, scripts: slideScriptDiagnostics(scripted, problems) }, options);
+  return runRules(lintContext(files, scripted, problems), options);
 }
 
 /**
@@ -66,7 +67,19 @@ export async function lintDeckAsync(
 ): Promise<Diagnostic[]> {
   const { files, scripted } = readLintInput(input);
   const problems = await evaluateSlideScripts(scripted.map((entry) => entry.input));
-  return runRules({ ...files, scripts: slideScriptDiagnostics(scripted, problems) }, options);
+  return runRules(lintContext(files, scripted, problems), options);
+}
+
+function lintContext(
+  files: DeckFiles,
+  scripted: LintedScript[],
+  problems: SlideScriptProblem[][],
+): LintContext {
+  return {
+    ...files,
+    scripts: slideScriptDiagnostics(scripted, problems),
+    scriptCode: new Map(scripted.map(({ section, input }) => [section.slug, input.code])),
+  };
 }
 
 function readLintInput(input: DeckInput): { files: DeckFiles; scripted: LintedScript[] } {

package/src/core/page.ts

@@ -7,6 +7,7 @@ import { escapeAttr } from "./escape.ts";
 export const PAGE_ID = {
   deck: "deck",
   data: "dek-data",
+  plugins: "dek-plugins",
   shell: "dek-shell",
   rail: "dek-rail",
   railResize: "dek-rail-resize",