@hajimism/dek 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 Release notes for `@hajimism/dek`. From 0.1.0 on, release-please writes this file from the Conventional Commits on `main`.
 
+## [0.6.1](https://github.com/hajimism/dek/compare/v0.6.0...v0.6.1) (2026-11-09)
+
+
+### Features
+
+* run a project's plugins in dekc check, for the slide it checks ([8f091ca](https://github.com/hajimism/dek/commit/8f091ca1ee65f0c2994f59ad1f40bcb30ac35141))
+* run a project's plugins in dekc check, for the slide it checks ([07cd3cc](https://github.com/hajimism/dek/commit/07cd3ccc14ec5ce0ff299880f2895780438a1510))
+
+
+### Bug Fixes
+
+* tell the agent to deal with lint's warnings, and which plugin data is whose ([8550412](https://github.com/hajimism/dek/commit/85504129dbe29b3a4b3b92b7033a903ef7c321e2))
+* tell the agent to deal with lint's warnings, and which plugin data is whose ([7e69b3b](https://github.com/hajimism/dek/commit/7e69b3b525421f08de65fe806b525d70504e7923))
+
+
+### Documentation
+
+* **adr:** record what AGENTS.md says of warnings and of whose plugin data is ([d42d28f](https://github.com/hajimism/dek/commit/d42d28f4d70572ecdd0e5ea9c15678f69b46af17))
+* say in the lint reference that plugins run in dekc check too ([c7f0cbb](https://github.com/hajimism/dek/commit/c7f0cbbbf49cf3bccab9cc7996f49d8e067d8f73))
+
 ## [0.6.0](https://github.com/hajimism/dek/compare/v0.5.1...v0.6.0) (2026-11-07)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hajimism/dek",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "A build system for talks.",
   "license": "MIT",
   "author": "Hajime Nakagawa (https://github.com/hajimism)",

package/src/cli/check.ts

@@ -4,6 +4,7 @@ import { shellQuote } from "../core/escape.ts";
 import type { Fill } from "../core/fill.ts";
 import { lintDeck } from "../core/lint.ts";
 import { type PlaywrightRunner, playwrightMissingError } from "../core/playwright.ts";
+import { checkSlide } from "../core/plugin-host.ts";
 import { runVisualDeck } from "../core/visual.ts";
 import { hasVoice, loadCachedTimeline, VOICE_SETUP_HINT } from "../core/voice.ts";
 import { type SkippedCheck, skippedChecks, visualSkipped } from "./result.ts";
@@ -35,26 +36,34 @@ export async function checkCommand(
   requireSection(deck, slug);
 
   const diagnostics = lintDeck({ project, deck }, { slug });
-  const visual = await runVisualDeck(
-    { project, deck },
-    {
-      slug,
-      screenshot: options.shot === true,
-      ...(options.runner ? { runner: options.runner } : {}),
-    },
-  );
+  // The plugins run in processes of their own while the browser measures the slide.
+  const [visual, plugins] = await Promise.all([
+    runVisualDeck(
+      { project, deck },
+      {
+        slug,
+        screenshot: options.shot === true,
+        ...(options.runner ? { runner: options.runner } : {}),
+      },
+    ),
+    checkSlide(project, deck, slug),
+  ]);
   if (visual) {
     diagnostics.push(...visual.diagnostics);
   } else if (options.shot) {
     throw playwrightMissingError();
   }
+  diagnostics.push(...plugins.diagnostics);
 
   const shot = visual?.screenshotPath;
   const { slug: _slide, ...fill } = visual?.fills.find((found) => found.slug === slug) ?? {};
 
-  const skipped: SkippedCheck[] = visual
-    ? []
-    : [visualSkipped(`dekc check ${shellQuote(slug)}`, { reason: "Playwright is not installed" })];
+  const skipped: SkippedCheck[] = [...plugins.skipped];
+  if (!visual) {
+    skipped.push(
+      visualSkipped(`dekc check ${shellQuote(slug)}`, { reason: "Playwright is not installed" }),
+    );
+  }
 
   // A live-only deck is done without voice, so asking for it skips the check rather than failing,
   // the way a missing Playwright skips visual.

package/src/core/lint/script.ts

@@ -1,7 +1,7 @@
 import { type Diagnostic, diag } from "../diagnostic.ts";
 import type { DekError } from "../error.ts";
 import { ScriptError } from "../parse.ts";
-import { scriptLines } from "../script-lines.ts";
+import { scriptLines, slugAtLine } from "../script-lines.ts";
 import type { LintContext } from "./context.ts";
 
 /** DEK004: a section id or a beat id used twice. */
@@ -56,7 +56,6 @@ export function strayHeadingDiagnostics(ctx: LintContext): Diagnostic[] {
   if (!script) {
     return [];
   }
-  const starts = deck.deck.sections.map((section) => ({ line: section.line, slug: section.slug }));
   const diagnostics: Diagnostic[] = [];
   // What the parser reads as text, a code block or a comment, is not a heading here either.
   for (const [offset, { text, literal }] of scriptLines(script.body).entries()) {
@@ -65,8 +64,7 @@ export function strayHeadingDiagnostics(ctx: LintContext): Diagnostic[] {
       continue;
     }
     const line = script.bodyStartLine + offset;
-    // Under a slide heading it belongs to that slide; above the first, to the deck.
-    const slug = starts.filter((start) => start.line < line).at(-1)?.slug;
+    const slug = slugAtLine(deck.deck.sections, line);
     diagnostics.push(
       diag("DEK044", {
         message: `${"#".repeat(level)} heading is not a slide or a beat; it is read as spoken text`,

package/src/core/plugin-host.ts

@@ -20,6 +20,7 @@ import {
 } from "./plugin.ts";
 import type { Project, ProjectDeck } from "./resolve.ts";
 import { readSourceIfExists, writeInside } from "./safe-fs.ts";
+import { slugAtLine } from "./script-lines.ts";
 import { OverrunError, runPiped, workerCommand } from "./spawn.ts";
 
 /**
@@ -53,14 +54,21 @@ function binName(name: string): string {
  * any plugin does, and never from PATH: its code is the dek the project installed, which the
  * project's lockfile pins.
  */
-const BUNDLED: Record<string, { main: string; page?: string }> = {
+const BUNDLED: Record<string, { main: string; page?: string; guide: string }> = {
   study: bundled("study", { page: true }),
   words: bundled("words", { page: false }),
 };
 
-function bundled(name: string, { page }: { page: boolean }): { main: string; page?: string } {
+function bundled(
+  name: string,
+  { page }: { page: boolean },
+): { main: string; page?: string; guide: string } {
   const dir = join(import.meta.dir, "..", "plugins", name);
-  return { main: join(dir, "main.ts"), ...(page ? { page: join(dir, "page.ts") } : {}) };
+  return {
+    main: join(dir, "main.ts"),
+    ...(page ? { page: join(dir, "page.ts") } : {}),
+    guide: `https://hajimism.github.io/dek/reference/plugins.html#dek-${name}`,
+  };
 }
 
 /** The page of each plugin dek ships with one, as a file to compile for the browser (ADR 34). */
@@ -304,7 +312,7 @@ export async function checkDeck(
     }
     return { diagnostics: [failed("could not start")] };
   }
-  const read = readSarif(stdout, plugin, [deck.dir, pluginDir(project.root, plugin.name)]);
+  const read = readSarif(stdout, plugin, deck, pluginDir(project.root, plugin.name));
   return typeof read === "string" ? { diagnostics: [failed(read)] } : { diagnostics: read };
 }
 
@@ -340,13 +348,14 @@ type SarifResult = {
 };
 
 /**
- * The findings in a check's SARIF, or what is wrong with it, as the end of a DEK046 message.
- * `dirs` are the deck's folder, which a relative location is read against, then the plugin's own.
+ * The findings in a check's SARIF, or what is wrong with it, as the end of a DEK046 message. A
+ * relative location is read against the deck's folder; `ownDir` is the plugin's own.
  */
 function readSarif(
   stdout: string,
   plugin: ReadyPlugin,
-  dirs: [deck: string, plugin: string],
+  deck: ProjectDeck,
+  ownDir: string,
 ): Diagnostic[] | string {
   let log: unknown;
   try {
@@ -381,7 +390,7 @@ function readSarif(
         id,
         severity: rule.severity,
         message: foreignLine(text, PLUGIN_TEXT_MAX),
-        ...location(result, dirs),
+        ...location(result, deck, ownDir),
         ...(typeof hint === "string" && hint.trim() !== ""
           ? { hint: foreignLine(hint, PLUGIN_TEXT_MAX) }
           : {}),
@@ -394,11 +403,13 @@ function readSarif(
 /**
  * Where a finding is, from its first location: a path relative to the deck, or a file URL, inside
  * the deck or the plugin's own `plugins/<name>/` (ADR 35). A location anywhere else is dropped,
- * never shown as a file to change.
+ * never shown as a file to change. A finding in a slide's files, or in its section of script.md,
+ * is on that slide, as dek's own are.
  */
 function location(
   result: SarifResult,
-  [deckDir, ownDir]: [string, string],
+  deck: ProjectDeck,
+  ownDir: string,
 ): Pick<Diagnostic, "path" | "line" | "column" | "slug"> {
   const physical = result.locations?.[0]?.physicalLocation;
   const uri = physical?.artifactLocation?.uri;
@@ -407,20 +418,20 @@ function location(
   }
   let path: string;
   try {
-    path = uri.startsWith("file:") ? fileURLToPath(uri) : resolve(deckDir, decodeURI(uri));
+    path = uri.startsWith("file:") ? fileURLToPath(uri) : resolve(deck.dir, decodeURI(uri));
   } catch {
     return {};
   }
-  const inDeck = inside(deckDir, path);
+  const inDeck = inside(deck.dir, path)?.split(sep).join("/");
   if (inDeck === undefined && inside(ownDir, path) === undefined) {
     return {};
   }
   const line = positive(physical?.region?.startLine);
   const column = line === undefined ? undefined : positive(physical?.region?.startColumn);
-  const slug = inDeck
-    ?.split(sep)
-    .join("/")
-    .match(/^slides\/([^/]+)\.(?:html|css|ts)$/)?.[1];
+  const slug =
+    inDeck === "script.md" && line !== undefined
+      ? slugAtLine(deck.deck.sections, line)
+      : inDeck?.match(/^slides\/([^/]+)\.(?:html|css|ts)$/)?.[1];
   return {
     path,
     ...(line === undefined ? {} : { line }),
@@ -530,6 +541,30 @@ export async function pluginChecks(
   return { ready, skipped, diagnostics };
 }
 
+/**
+ * The plugins' findings for `dekc check` on one slide, and the plugins that did not run. Each
+ * pinned plugin checks the deck, as lint has it, and the slide keeps what is on it. It also keeps
+ * an error on no slide, such as data that does not read or a plugin that failed: the slide's
+ * check may rest on it, and leaving it out would pass a slide no plugin checked.
+ */
+export async function checkSlide(
+  project: Project,
+  deck: ProjectDeck,
+  slug: string,
+): Promise<{ diagnostics: Diagnostic[]; skipped: SkippedCheck[] }> {
+  const plugins = await pluginChecks(project);
+  const outcomes = await Promise.all(
+    plugins.ready.map((plugin) => checkDeck(plugin, project, deck)),
+  );
+  const diagnostics = [
+    ...plugins.diagnostics,
+    ...outcomes.flatMap((outcome) => outcome.diagnostics),
+  ].filter((found) =>
+    found.slug === undefined ? found.severity === "error" : found.slug === slug,
+  );
+  return { diagnostics, skipped: plugins.skipped };
+}
+
 /** What `dekc sync` did with one plugin, for its `--json` and its notes. */
 export type PluginSync = {
   name: string;
@@ -628,7 +663,12 @@ export function pinnedPlugins(root: string): PinnedPlugin[] {
     } catch {
       reading = undefined;
     }
-    return { name, manifest: reading?.ok ? reading.manifest : undefined };
+    const guide = BUNDLED[name]?.guide;
+    return {
+      name,
+      manifest: reading?.ok ? reading.manifest : undefined,
+      ...(guide === undefined ? {} : { guide }),
+    };
   });
 }
 

package/src/core/plugin.ts

@@ -359,30 +359,35 @@ function checkChanges(
   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 };
+/**
+ * A plugin dek.toml names, with the manifest its lock pins when it has one, and dek's own page on
+ * how to write its data when dek ships it.
+ */
+export type PinnedPlugin = { name: string; manifest: PluginManifest | undefined; guide?: string };
 
 /**
  * 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.
+ * checked fields; the plugin's own summaries stay out. A data file says whether it is the
+ * project's or each deck's, since the two can share a name. Empty when dek.toml names no plugin.
  */
 export function pluginsSection(plugins: PinnedPlugin[]): string {
   if (plugins.length === 0) {
     return "";
   }
-  const lines = plugins.map(({ name, manifest }) => {
+  const lines = plugins.map(({ name, manifest, guide }) => {
     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.check ? [`It checks ${ruleList(Object.keys(manifest.check.rules))}.`] : []),
       ...(manifest.data && manifest.data.length > 0
         ? [
             `Its data: ${projectFirst(manifest.data)
-              .map((entry) => `\`${dataPath(name, entry)}\``)
+              .map(
+                (entry) =>
+                  `\`${dataPath(name, entry)}\` ${entry.in === "project" ? "in the project" : "in each deck"}`,
+              )
               .join(", ")}.`,
           ]
         : []),
@@ -391,13 +396,14 @@ export function pluginsSection(plugins: PinnedPlugin[]): string {
             `Its page takes the ${manifest.page.keys.length === 1 ? "key" : "keys"} ${manifest.page.keys.map((key) => `\`${key}\``).join(", ")}.`,
           ]
         : []),
+      ...(guide && manifest.data && manifest.data.length > 0 ? [`How to write it: ${guide}`] : []),
     ];
     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.
+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, and \`dekc check <slug>\` reports what they find on that slide; their findings carry the plugin's rule ids.
 
 ${lines.join("\n")}
 `;

package/src/core/script-lines.ts

@@ -51,3 +51,14 @@ function commentOpenAfter(text: string, open: boolean): boolean {
   }
   return inside;
 }
+
+/**
+ * The slide a line of script.md belongs to: the `##` section it is in, heading included. Above the
+ * first heading it belongs to the deck, and to no slide.
+ */
+export function slugAtLine(
+  sections: ReadonlyArray<{ line: number; slug: string }>,
+  line: number,
+): string | undefined {
+  return sections.filter((section) => section.line <= line).at(-1)?.slug;
+}

package/src/core/sync.ts

@@ -288,7 +288,7 @@ A build system for talks. Write what you will say; dek builds, measures, and shi
 
 ## Before you report a deck as done
 
-- \`dekc lint --visual\` passes.
+- \`dekc lint --visual\` passes. Warnings do not fail it: fix each one, or tell the author which you kept and why.
 - 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)}${pluginsSection(pinnedPlugins(root))}