@hajimism/dek 0.5.1 → 0.6.1

package/src/plugins/study/check.ts

@@ -0,0 +1,128 @@
+import type { CheckInput } from "../../plugin-api.ts";
+import { type RuleId, STUDY_FILE } from "./manifest.ts";
+import { follows, normalize, occurrences, placeStickers } from "./place.ts";
+import { readStudy, type Sticker } from "./study.ts";
+import { slideText } from "./text.ts";
+
+/** A finding, which can name only a rule the manifest declares. Paths are relative to the deck. */
+export type Finding = { rule: RuleId; message: string; path: string; line: number; hint: string };
+
+/** Reads a file of the deck by its path relative to the deck's folder; undefined when absent. */
+export type ReadFile = (path: string) => Promise<string | undefined>;
+
+/**
+ * Checks the deck's stickers against its slides: each sticker's words are on its slide (STUDY001),
+ * no other place on the slide shows them unhidden (STUDY002), and study.yaml reads (STUDY003). A
+ * deck with no study.yaml has nothing to check.
+ */
+export async function check(input: CheckInput, read: ReadFile): Promise<Finding[]> {
+  const source = await read(STUDY_FILE);
+  if (source === undefined) {
+    return [];
+  }
+  const { stickers, problems } = readStudy(source);
+  const findings: Finding[] = problems.map((problem) => ({
+    rule: "STUDY003",
+    message: problem.message,
+    path: STUDY_FILE,
+    line: problem.line,
+    hint: "write study.yaml as https://hajimism.github.io/dek/reference/plugins.html#dek-study shows",
+  }));
+
+  const texts = new Map<string, string>();
+  const htmlPaths = new Map<string, string>();
+  for (const slide of input.deck.slides) {
+    const html = slide.html === null ? undefined : await read(slide.html);
+    texts.set(slide.slug, html === undefined ? "" : await slideText(html));
+    htmlPaths.set(slide.slug, slide.html ?? `slides/${slide.slug}.html`);
+  }
+
+  /** The one other slide the sticker would find its place on, prefix and all, if exactly one. */
+  const elsewhere = (sticker: Sticker): string | undefined => {
+    const found = [...texts].filter(
+      ([slug, text]) => slug !== sticker.slide && placeStickers(text, [sticker]).lost.length === 0,
+    );
+    return found.length === 1 ? found[0]?.[0] : undefined;
+  };
+  const lost = (sticker: Sticker, message: string, fallback: string): Finding => {
+    const other = elsewhere(sticker);
+    return {
+      rule: "STUDY001",
+      message,
+      path: STUDY_FILE,
+      line: sticker.line,
+      hint:
+        other === undefined
+          ? fallback
+          : `the words are on slide ${other}: set the sticker's \`slide: ${other}\``,
+    };
+  };
+
+  /**
+   * Why a sticker on a slide that is there found no place: its words are gone, no place of them
+   * follows its prefix, or the stickers before it took every place. Only gone words are looked
+   * for on other slides; words still on the slide are the sticker's to find there.
+   */
+  const lostOnSlide = (sticker: Sticker, slug: string, text: string, path: string): Finding => {
+    const quote = normalize(sticker.quote);
+    const places = occurrences(text, quote);
+    if (places.length === 0) {
+      return lost(
+        sticker,
+        `sticker ${sticker.id}: 「${sticker.quote}」 is not on slide ${slug}`,
+        `find where the words went in ${path} and set the sticker's quote and prefix to them, or delete the sticker`,
+      );
+    }
+    const prefix = sticker.prefix === undefined ? undefined : normalize(sticker.prefix);
+    if (prefix !== undefined && !places.some((place) => follows(text, place, prefix))) {
+      return {
+        rule: "STUDY001",
+        message: `sticker ${sticker.id}: 「${sticker.quote}」 is on slide ${slug}, but not after 「${sticker.prefix}」`,
+        path: STUDY_FILE,
+        line: sticker.line,
+        hint: `set the sticker's prefix to the words right before 「${sticker.quote}」 in ${path}, or leave the prefix out`,
+      };
+    }
+    return {
+      rule: "STUDY001",
+      message: `sticker ${sticker.id}: every 「${sticker.quote}」 on slide ${slug} has a sticker before this one`,
+      path: STUDY_FILE,
+      line: sticker.line,
+      hint: "delete the sticker, since another already hides these words",
+    };
+  };
+
+  const bySlide = Map.groupBy(stickers, (sticker) => sticker.slide);
+  for (const [slug, onSlide] of bySlide) {
+    const text = texts.get(slug);
+    if (text === undefined) {
+      for (const sticker of onSlide) {
+        findings.push(
+          lost(
+            sticker,
+            `sticker ${sticker.id}: slide ${slug} is not in this deck`,
+            "set the sticker's `slide` to the slide its words are on, or delete the sticker",
+          ),
+        );
+      }
+      continue;
+    }
+    const placement = placeStickers(text, onSlide);
+    for (const sticker of placement.lost) {
+      findings.push(lostOnSlide(sticker, slug, text, htmlPaths.get(slug) ?? ""));
+    }
+    for (const { first, count } of placement.shown) {
+      findings.push({
+        rule: "STUDY002",
+        message: `「${first.quote}」 is hidden by sticker ${first.id} but shows ${count} more ${count === 1 ? "time" : "times"} on slide ${slug}`,
+        path: STUDY_FILE,
+        line: first.line,
+        hint: `add a sticker for each other 「${first.quote}」 on the slide, with a prefix that tells it apart, or reword the others`,
+      });
+    }
+  }
+  // The same deck gives the same output, in the same order.
+  return findings.sort(
+    (a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.rule.localeCompare(b.rule),
+  );
+}

package/src/plugins/study/main.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env bun
+/**
+ * dek-study, the plugin dek ships (ADR 34). dek runs it as any plugin (ADR 32), in a bun of its
+ * own: `manifest` to pin what it promises, and `check --protocol 1` in a deck's folder, with the
+ * deck on stdin, for SARIF. It shares only the types in plugin-api.ts with dek, never its code.
+ */
+import { readFileSync } from "node:fs";
+import type { CheckInput } from "../../plugin-api.ts";
+import { check } from "./check.ts";
+import { MANIFEST } from "./manifest.ts";
+import { toSarif } from "./sarif.ts";
+
+const USAGE = "usage: dek-study manifest | dek-study check --protocol 1  (dek runs both)";
+
+async function main(args: string[]): Promise<number> {
+  switch (args[0]) {
+    case "manifest":
+      process.stdout.write(`${JSON.stringify(MANIFEST)}\n`);
+      return 0;
+    case "check": {
+      if (args[1] !== "--protocol" || args[2] !== "1") {
+        process.stderr.write(
+          `dek-study speaks check protocol 1; dek asked for ${args.slice(1).join(" ")}\n`,
+        );
+        return 2;
+      }
+      const input = JSON.parse(await Bun.stdin.text()) as CheckInput;
+      const findings = await check(input, async (path) => readIfThere(path));
+      process.stdout.write(`${JSON.stringify(toSarif(findings))}\n`);
+      return 0;
+    }
+    default:
+      process.stderr.write(`${USAGE}\n`);
+      return 2;
+  }
+}
+
+/** A file of the deck, relative to its folder, which is where dek runs the check. */
+function readIfThere(path: string): string | undefined {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+process.exit(await main(process.argv.slice(2)));

package/src/plugins/study/manifest.ts

@@ -0,0 +1,32 @@
+import type { PluginManifest, PluginRules } from "../../plugin-api.ts";
+
+/**
+ * The one place each rule is declared: the manifest prints it, and a finding can name only a rule
+ * here, so dek-study cannot report an id its manifest does not declare.
+ */
+const RULES = {
+  STUDY001: { severity: "error", summary: "a sticker's words are not on its slide" },
+  STUDY002: { severity: "warning", summary: "a sticker's words also show elsewhere on its slide" },
+  STUDY003: { severity: "error", summary: "study.yaml cannot be read" },
+} as const satisfies PluginRules<"STUDY">;
+
+export type RuleId = keyof typeof RULES;
+
+/** The file of stickers, in each deck's folder. */
+export const STUDY_FILE = "study.yaml";
+
+/**
+ * dek-study's own version, apart from dek's: a project accepts a change to what it promises, and
+ * a dek release that leaves the rules as they were must not ask for that.
+ */
+const VERSION = "0.1.0";
+
+/** What `dek-study manifest` prints: the same every time, since dek pins it. */
+export const MANIFEST = {
+  schema: 1,
+  name: "study",
+  version: VERSION,
+  check: { protocol: 1, rules: RULES },
+  page: { api: 1, keys: ["r"] },
+  data: [{ path: STUDY_FILE }],
+} as const satisfies PluginManifest<"STUDY">;

package/src/plugins/study/page.ts

@@ -0,0 +1,295 @@
+/// <reference lib="dom" />
+/**
+ * dek-study's page (ADR 34): a sheet of stickers over the words in study.yaml. `r` lays the sheet
+ * on and takes it off, and the page remembers which for the deck. The pointer on a sticker peels it
+ * back, and the words show through. It finds each sticker's words as the check does, with
+ * the same reader and the same placement, so a deck that passes lint is a deck the sheet covers.
+ */
+import type { DekPage, PageApi } from "../../plugin-api.ts";
+import { STUDY_FILE } from "./manifest.ts";
+import { normalize, placeStickers } from "./place.ts";
+import { readStudy, type Sticker } from "./study.ts";
+
+declare const dek: DekPage;
+
+/** How long a sticker takes to fade away under the pointer, and to come back after it. */
+const FADE_OUT_MS = 180;
+const FADE_IN_MS = 120;
+/** How long the sheet's state shows after `r`, before it gets out of the slide's way. */
+const TOAST_MS = 1500;
+/** How far a sticker reaches past its words, in ems of the words it hides: a little to each side, barely above and below. */
+const PAD_X = 0.18;
+const PAD_Y = 0.04;
+const UNSEEN = new Set(["SCRIPT", "STYLE", "TEMPLATE", "NOSCRIPT"]);
+
+/**
+ * A sticker is a slip of pale yellow paper, as a sticky note is, with square corners and the same
+ * on every theme, so it reads as something laid on the slide rather than part of it. Under the
+ * pointer it fades away and leaves a yellow rule under the words, so the place still reads as a
+ * sticker's; it comes back once the pointer leaves.
+ */
+const STYLE = `
+  .sheet { position: absolute; inset: 0; }
+  .sheet[hidden] { display: none; }
+  .sticker {
+    position: absolute;
+    pointer-events: auto;
+    background: rgb(255 240 160);
+    box-shadow: inset 0 calc(-1 * max(2px, 0.08em)) 0 rgb(240 206 72);
+    transition: background-color ${FADE_IN_MS}ms ease-in;
+  }
+  .sticker.peek {
+    background: rgb(255 240 160 / 0);
+    transition: background-color ${FADE_OUT_MS}ms ease-out;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .sticker, .sticker.peek, .toast, .toast.show { transition: none; }
+  }
+  .toast {
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity ${FADE_OUT_MS}ms ease-in, visibility 0s ${FADE_OUT_MS}ms;
+    position: absolute;
+    top: 0;
+    right: 0;
+    padding: 6px 12px;
+    background: var(--study-ink);
+    color: var(--study-paper);
+    font: 600 13px/1.4 system-ui, sans-serif;
+    letter-spacing: 0.08em;
+  }
+  .toast.show {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity ${FADE_IN_MS}ms ease-out, visibility 0s;
+  }
+`;
+
+dek.plugin("study", { api: 1 }, (api) => {
+  const file = api.data(STUDY_FILE);
+  const stickers = file ? readStudy(file.text).stickers : [];
+  const bySlide = Map.groupBy(stickers, (sticker) => sticker.slide);
+  const storage = `dek-study:${api.deck.name}:sheet`;
+  let on = readOn(storage);
+  const mounted = new Map<
+    string,
+    { root: HTMLElement; layer: ShadowRoot; sheet: HTMLElement; toast: HTMLElement }
+  >();
+  let toastTimer: ReturnType<typeof setTimeout> | undefined;
+
+  api.on("mount", ({ slug, root, layer }) => {
+    // The slide's own ink and paper, for the hairline and the notice, through the layer's host.
+    const slideStyle = getComputedStyle(root);
+    const host = layer.host as HTMLElement;
+    host.style.setProperty("--study-ink", slideStyle.color);
+    host.style.setProperty("--study-paper", paper(slideStyle.backgroundColor));
+    const style = document.createElement("style");
+    style.textContent = STYLE;
+    const sheet = document.createElement("div");
+    sheet.className = "sheet";
+    const toast = document.createElement("div");
+    toast.className = "toast";
+    layer.append(style, sheet, toast);
+    mounted.set(slug, { root, layer, sheet, toast });
+  });
+  api.on("change", ({ slug }) => draw(slug));
+  api.key("r", () => {
+    on = !on;
+    writeOn(storage, on);
+    const slug = api.current().slug;
+    draw(slug);
+    announce(slug);
+  });
+  // Text set in a web font moves once the font arrives.
+  void document.fonts?.ready.then(() => draw(api.current().slug));
+
+  /** Says for a moment whether the sheet is on. */
+  function announce(slug: string): void {
+    const toast = mounted.get(slug)?.toast;
+    if (!toast) {
+      return;
+    }
+    toast.textContent = on ? "SHEET ON" : "SHEET OFF";
+    toast.classList.add("show");
+    clearTimeout(toastTimer);
+    toastTimer = setTimeout(() => {
+      toast.classList.remove("show");
+    }, TOAST_MS);
+  }
+
+  function draw(slug: string): void {
+    const view = mounted.get(slug);
+    if (!view) {
+      return;
+    }
+    const { root, layer, sheet } = view;
+    sheet.replaceChildren();
+    sheet.hidden = !on;
+    if (!on) {
+      return;
+    }
+    const onSlide = bySlide.get(slug) ?? [];
+
+    const host = layer.host as HTMLElement;
+    const box = host.getBoundingClientRect();
+    const scale = host.offsetWidth > 0 ? box.width / host.offsetWidth : 1;
+    const words = readWords(root);
+    for (const { sticker, at } of placeStickers(words.text, onSlide).placed) {
+      const range = words.range(at, normalize(sticker.quote).length);
+      if (!range || !shown(api, range)) {
+        continue;
+      }
+      const ink = getComputedStyle(range.startContainer.parentElement ?? root);
+      const em = Number.parseFloat(ink.fontSize) || 16;
+      const pieces = lines(range.getClientRects()).map((rect) =>
+        stickerEl(sticker, ink, {
+          left: (rect.left - box.left) / scale - em * PAD_X,
+          top: (rect.top - box.top) / scale - em * PAD_Y,
+          width: (rect.right - rect.left) / scale + em * PAD_X * 2,
+          height: (rect.bottom - rect.top) / scale + em * PAD_Y * 2,
+        }),
+      );
+      peekTogether(pieces);
+      sheet.append(...pieces);
+    }
+  }
+});
+
+type Box = { left: number; top: number; right: number; bottom: number };
+
+/**
+ * The words' boxes, one per line: a range across elements, such as `<strong>外部</strong>視点`,
+ * gives a box for each, and one sticker over the words reads as one.
+ */
+function lines(rects: DOMRectList): Box[] {
+  const merged: Box[] = [];
+  const sorted = [...rects]
+    .filter((rect) => rect.width > 0 && rect.height > 0)
+    .sort((a, b) => a.top - b.top || a.left - b.left);
+  for (const rect of sorted) {
+    const last = merged.at(-1);
+    const sameLine = last && rect.top < last.bottom && rect.bottom > last.top;
+    if (last && sameLine && rect.left <= last.right + 1) {
+      last.left = Math.min(last.left, rect.left);
+      last.top = Math.min(last.top, rect.top);
+      last.right = Math.max(last.right, rect.right);
+      last.bottom = Math.max(last.bottom, rect.bottom);
+    } else {
+      merged.push({ left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom });
+    }
+  }
+  return merged;
+}
+
+/** A sticker in the color and size of the words under it, so its ems are theirs. */
+function stickerEl(
+  sticker: Sticker,
+  ink: CSSStyleDeclaration,
+  box: { left: number; top: number; width: number; height: number },
+): HTMLElement {
+  const el = document.createElement("div");
+  el.className = "sticker";
+  el.dataset.id = sticker.id;
+  el.style.cssText = `left:${box.left}px;top:${box.top}px;width:${box.width}px;height:${box.height}px;font-size:${ink.fontSize}`;
+  return el;
+}
+
+/** The slide's background, or white where the slide leaves it transparent. */
+function paper(background: string): string {
+  return background === "" || background === "transparent" || /rgba\(.*,\s*0\)$/.test(background)
+    ? "#fff"
+    : background;
+}
+
+/** A sticker that wraps onto two lines is one sticker: the pointer on either piece peels both. */
+function peekTogether(pieces: HTMLElement[]): void {
+  const peek = (on: boolean) => {
+    for (const piece of pieces) {
+      piece.classList.toggle("peek", on);
+    }
+  };
+  for (const piece of pieces) {
+    piece.addEventListener("pointerenter", () => peek(true));
+    piece.addEventListener("pointerleave", () => peek(false));
+  }
+}
+
+/** A sticker covers words only once they show: one over a beat still to come would give it away. */
+function shown(api: PageApi, range: Range): boolean {
+  const start = range.startContainer.parentElement;
+  const end = range.endContainer.parentElement;
+  return (!start || api.shown(start)) && (!end || api.shown(end));
+}
+
+/**
+ * The slide's words as the check reads them, whitespace collapsed, and a way back from a place in
+ * them to the DOM: each character kept remembers the text node and offset it came from.
+ */
+function readWords(root: HTMLElement): {
+  text: string;
+  range: (at: number, length: number) => Range | undefined;
+} {
+  const chars: Array<{ node: Text; offset: number }> = [];
+  let text = "";
+  let space = false;
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+    acceptNode: (node) =>
+      unseen(node, root) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+  });
+  for (let node = walker.nextNode() as Text | null; node; node = walker.nextNode() as Text | null) {
+    const data = node.data;
+    for (let offset = 0; offset < data.length; offset += 1) {
+      const char = data[offset] as string;
+      if (/\s/.test(char)) {
+        space = text.length > 0;
+        continue;
+      }
+      if (space) {
+        text += " ";
+        chars.push({ node, offset });
+        space = false;
+      }
+      text += char;
+      chars.push({ node, offset });
+    }
+  }
+  return {
+    text,
+    range(at, length) {
+      const first = chars[at];
+      const last = chars[at + length - 1];
+      if (!first || !last) {
+        return undefined;
+      }
+      const range = document.createRange();
+      range.setStart(first.node, first.offset);
+      range.setEnd(last.node, last.offset + 1);
+      return range;
+    },
+  };
+}
+
+function unseen(node: Node, root: HTMLElement): boolean {
+  for (let el = node.parentElement; el && el !== root; el = el.parentElement) {
+    if (UNSEEN.has(el.tagName)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function readOn(key: string): boolean {
+  try {
+    return localStorage.getItem(key) === "on";
+  } catch {
+    return false;
+  }
+}
+
+function writeOn(key: string, on: boolean): void {
+  try {
+    localStorage.setItem(key, on ? "on" : "off");
+  } catch {
+    // A page whose storage is blocked forgets; the sheet still works for the visit.
+  }
+}

package/src/plugins/study/place.ts

@@ -0,0 +1,88 @@
+/**
+ * Where each sticker sits in a slide's words, decided the same in the check and in the page, so a
+ * deck that passes lint is a deck whose stickers the page finds.
+ */
+
+/** What a sticker needs to be placed: its words, the words right before them, and its line. */
+export type Placeable = { quote: string; prefix?: string; line: number };
+
+export type Placement<S extends Placeable> = {
+  /** Each sticker that found its place, with where its words start in the text. */
+  placed: Array<{ sticker: S; at: number }>;
+  /** Each sticker whose words are not where it says. */
+  lost: S[];
+  /** Words a sticker hides that show again with no sticker over them: how often, and the first sticker. */
+  shown: Array<{ quote: string; first: S; count: number }>;
+};
+
+/** Text with each run of whitespace as one space, trimmed, as words are compared. */
+export function normalize(text: string): string {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Places each sticker in `text`, a slide's words as `normalize` leaves them. Stickers over the same
+ * words take their places in order: one with a prefix the first place that follows it, then one
+ * without the first place left.
+ */
+export function placeStickers<S extends Placeable>(text: string, stickers: S[]): Placement<S> {
+  const placement: Placement<S> = { placed: [], lost: [], shown: [] };
+  const inOrder = stickers.toSorted((a, b) => a.line - b.line);
+  for (const [quote, same] of Map.groupBy(inOrder, (sticker) => normalize(sticker.quote))) {
+    const places = occurrences(text, quote);
+    const taken = new Set<number>();
+    const placed: S[] = [];
+    for (const sticker of [...same.filter((s) => s.prefix), ...same.filter((s) => !s.prefix)]) {
+      const prefix = sticker.prefix === undefined ? undefined : normalize(sticker.prefix);
+      const at = places.find(
+        (place) => !taken.has(place) && (prefix === undefined || follows(text, place, prefix)),
+      );
+      if (at === undefined) {
+        placement.lost.push(sticker);
+        continue;
+      }
+      taken.add(at);
+      placed.push(sticker);
+      placement.placed.push({ sticker, at });
+    }
+    const count = places.length - taken.size;
+    const first = placed.toSorted((a, b) => a.line - b.line)[0];
+    if (count > 0 && first) {
+      placement.shown.push({ quote, first, count });
+    }
+  }
+  placement.placed.sort((a, b) => a.sticker.line - b.sticker.line);
+  return placement;
+}
+
+/** Whether the words right before `place` in `text` end with `prefix`, as normalized. */
+export function follows(text: string, place: number, prefix: string): boolean {
+  return text.slice(0, place).trimEnd().endsWith(prefix);
+}
+
+/**
+ * A letter or digit of a script written with spaces between words. Next to one, a quote that
+ * starts or ends with one is part of a longer word: `is` is not in "This". Japanese, Chinese,
+ * Korean, and Thai run on without spaces, so a quote is any run of their words.
+ */
+const SPACED = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Nd}]/u;
+
+/** Where `quote` starts in `text`, each place it does, without overlaps, as whole words. */
+export function occurrences(text: string, quote: string): number[] {
+  const found: number[] = [];
+  if (quote === "") {
+    return found;
+  }
+  const end = quote.length;
+  const opens = SPACED.test(quote[0] ?? "");
+  const closes = SPACED.test(quote[end - 1] ?? "");
+  for (let at = text.indexOf(quote); at !== -1; ) {
+    const whole =
+      !(opens && SPACED.test(text[at - 1] ?? "")) && !(closes && SPACED.test(text[at + end] ?? ""));
+    if (whole) {
+      found.push(at);
+    }
+    at = text.indexOf(quote, whole ? at + end : at + 1);
+  }
+  return found;
+}

package/src/plugins/study/sarif.ts

@@ -0,0 +1,30 @@
+import type { CheckOutput } from "../../plugin-api.ts";
+import type { Finding } from "./check.ts";
+import type { RuleId } from "./manifest.ts";
+import { MANIFEST } from "./manifest.ts";
+
+/** Findings as the SARIF dek reads: the rule, the message, the place, and the hint. */
+export function toSarif(findings: Finding[]): CheckOutput<RuleId> {
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: { driver: { name: "dek-study", version: MANIFEST.version } },
+        results: findings.map((finding) => ({
+          ruleId: finding.rule,
+          message: { text: finding.message },
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: finding.path },
+                region: { startLine: finding.line },
+              },
+            },
+          ],
+          properties: { hint: finding.hint },
+        })),
+      },
+    ],
+  };
+}