@hajimism/dek 0.1.0

package/src/core/lint/slide-html.ts

@@ -0,0 +1,466 @@
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import type { HtmlAttribute, HtmlScan, SourceSpot } from "../html-scan.ts";
+import type { Section } from "../schema.ts";
+import { beatAt, formatStepChoices, resolveStep, stepChoices } from "../step.ts";
+import { suggest } from "../suggest.ts";
+import { isUrlAttribute } from "../url-attributes.ts";
+import { assetRefDiagnostics } from "./asset-refs.ts";
+import { RESERVED_MORPHS } from "./morph.ts";
+import { isRawThemeValue } from "./tokens.ts";
+
+/**
+ * view-transition-names a data-morph may not take. The player names the slide box "slide",
+ * the browser names the page "root", and the rest are keywords of the property itself.
+ */
+/** One slide's markup, scanned once; every finding in it is located by the scan. */
+type SlideHtml = {
+  section: Section;
+  path: string;
+  scan: HtmlScan;
+  /** Whether the file is still the skeleton `dekc sync` wrote, which sync keeps in step. */
+  skeleton: boolean;
+};
+
+export function lintSlideHtml(
+  section: Section,
+  path: string,
+  scan: HtmlScan,
+  options: {
+    deckDir: string;
+    skeleton?: boolean;
+    classes?: Set<string>;
+    layouts?: Set<string>;
+    hasScript?: boolean;
+  },
+): Diagnostic[] {
+  const slide: SlideHtml = {
+    section,
+    path,
+    scan,
+    skeleton: options.skeleton === true,
+  };
+  if (slide.scan.slides.length === 0) {
+    return [missingSectionDiagnostic(slide)];
+  }
+  return [
+    ...extraSectionDiagnostics(slide),
+    ...(options.layouts ? layoutDiagnostics(slide, options.layouts) : []),
+    ...slugDiagnostics(slide),
+    ...stepDiagnostics(slide),
+    ...morphDiagnostics(slide),
+    ...inlineCodeDiagnostics(slide),
+    ...presentationDiagnostics(slide),
+    ...emptyHeadingDiagnostics(slide),
+    ...hiddenTextDiagnostics(slide),
+    ...(options.classes
+      ? unknownClassDiagnostics(slide, options.classes, options.hasScript === true)
+      : []),
+    ...slide.scan.refs.flatMap((ref) =>
+      assetRefDiagnostics(ref, {
+        path,
+        ...spotOf(ref),
+        slug: section.slug,
+        deckDir: options.deckDir,
+      }),
+    ),
+  ];
+}
+
+/** Every `name` attribute in the markup, in document order. */
+function attributesNamed(scan: HtmlScan, name: string): HtmlAttribute[] {
+  return scan.elements.flatMap((element) =>
+    element.attributes.filter((attribute) => attribute.name === name),
+  );
+}
+
+/** The location fields of a diagnostic, from wherever the scan found the thing. */
+function spotOf({ line, column }: SourceSpot): { line: number; column: number } {
+  return { line, column };
+}
+
+/**
+ * The attributes that style an element as a property would, and the property each stands for:
+ * SVG's presentation attributes and the HTML ones that outlived CSS. Only colors and families are
+ * read; SVG's unitless lengths are its own coordinates.
+ */
+const PRESENTATION_ATTRIBUTES: Record<string, string> = {
+  fill: "fill",
+  stroke: "stroke",
+  color: "color",
+  "stop-color": "stop-color",
+  "flood-color": "flood-color",
+  "lighting-color": "lighting-color",
+  "font-family": "font-family",
+  face: "font-family",
+  bgcolor: "background-color",
+};
+
+/**
+ * DEK014: a raw color or font family in a presentation attribute, which styles the element where
+ * no var() can reach. `fill="none"` and `currentColor` take nothing from the theme and pass.
+ */
+function presentationDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  const css = `slides/${section.slug}.css`;
+  return scan.elements.flatMap((element) =>
+    element.attributes.flatMap((attribute) => {
+      const property = PRESENTATION_ATTRIBUTES[attribute.name];
+      if (property === undefined || !isRawThemeValue(property, attribute.value)) {
+        return [];
+      }
+      const token = property === "font-family" ? "var(--font-body)" : "var(--accent)";
+      return [
+        diag("DEK014", {
+          message: `raw value in ${attribute.name}="${attribute.value}"; use a theme token`,
+          path,
+          ...spotOf(attribute),
+          slug: section.slug,
+          hint: `set ${property} in ${css} with a theme token instead, such as ${property}: ${token}; an attribute cannot take var()`,
+          data: { attribute: attribute.name, value: attribute.value },
+        }),
+      ];
+    }),
+  );
+}
+
+/** DEK007: the file is there, but nothing in it is a slide, so build and show draw nothing for it. */
+function missingSectionDiagnostic({ section, path }: SlideHtml): Diagnostic {
+  return diag("DEK007", {
+    message: `slides/${section.slug}.html has no <section class="slide">`,
+    path,
+    slug: section.slug,
+    hint: 'wrap the slide markup in <section class="slide">…</section>',
+  });
+}
+
+/** DEK009: more than one slide in a file; the player shows the first and drops the rest. */
+function extraSectionDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  const [, second] = scan.slides;
+  if (!second) {
+    return [];
+  }
+  return [
+    diag("DEK009", {
+      message: `slides/${section.slug}.html has ${scan.slides.length} <section class="slide">; only the first is shown`,
+      path,
+      ...spotOf(second),
+      slug: section.slug,
+      hint: "one file is one slide: add a ## section to script.md and move the rest into its file",
+      data: { sections: scan.slides.length },
+    }),
+  ];
+}
+
+/** DEK019: a data-layout that neither the theme nor the slide's stylesheet lays out. */
+function layoutDiagnostics({ section, path, scan }: SlideHtml, layouts: Set<string>): Diagnostic[] {
+  const attribute = scan.slides[0]?.attributes.find((entry) => entry.name === "data-layout");
+  if (scan.layout === undefined || !attribute || layouts.has(scan.layout)) {
+    return [];
+  }
+  const known = [...layouts].sort();
+  const guess = suggest(scan.layout, known);
+  return [
+    diag("DEK019", {
+      message: `data-layout "${scan.layout}" is not a layout of the theme`,
+      path,
+      ...spotOf(attribute),
+      slug: section.slug,
+      hint: `${guess ? `did you mean ${guess}? ` : ""}run \`dekc theme\` to see the layouts`,
+      data: { layout: scan.layout, layouts: known },
+    }),
+  ];
+}
+
+/** DEK006: the slide's data-slug names another section. */
+function slugDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  const found = scan.slides
+    .flatMap((element) => element.attributes)
+    .find((attribute) => attribute.name === "data-slug");
+  if (!found || found.value === section.slug) {
+    return [];
+  }
+  return [
+    diag("DEK006", {
+      message: `data-slug "${found.value}" does not match section "${section.slug}"`,
+      path,
+      ...spotOf(found),
+      slug: section.slug,
+      data: { slug: found.value, expected: section.slug },
+    }),
+  ];
+}
+
+/**
+ * DEK003: a data-step that is neither a beat id nor a beat index. DEK025: a beat index where
+ * that beat has an id, which silently binds the next beat over once one is inserted before it.
+ */
+function stepDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  return attributesNamed(scan, "data-step").flatMap((attribute) => {
+    const step = attribute.value;
+    const beatIndex = resolveStep(section.beats, step);
+    if (beatIndex === undefined) {
+      return [
+        diag("DEK003", {
+          message: `data-step "${step}" is not a beat id or index in "${section.slug}"`,
+          path,
+          ...spotOf(attribute),
+          slug: section.slug,
+          hint: stepHint(section),
+          data: { step, choices: stepChoices(section.beats) },
+        }),
+      ];
+    }
+    const id = beatAt(section.beats, beatIndex)?.id;
+    if (id === undefined || id === step) {
+      return [];
+    }
+    return [
+      diag("DEK025", {
+        message: `data-step "${step}" is beat "${id}" by position; it moves if a beat is inserted before it`,
+        path,
+        ...spotOf(attribute),
+        slug: section.slug,
+        hint: `use data-step="${id}"`,
+        data: { step, id },
+      }),
+    ];
+  });
+}
+
+/** DEK005: a data-morph used twice, or one the player or CSS already means something by. */
+function morphDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const first = new Map<string, HtmlAttribute>();
+  const reported = new Set<string>();
+  for (const attribute of attributesNamed(scan, "data-morph")) {
+    const morph = attribute.value;
+    if (!first.has(morph)) {
+      first.set(morph, attribute);
+      continue;
+    }
+    if (reported.has(morph)) {
+      continue;
+    }
+    reported.add(morph);
+    diagnostics.push(
+      diag("DEK005", {
+        message: `duplicate data-morph "${morph}"`,
+        path,
+        ...spotOf(attribute),
+        slug: section.slug,
+        data: { morph },
+      }),
+    );
+  }
+  for (const [morph, attribute] of first) {
+    if (!RESERVED_MORPHS.has(morph)) {
+      continue;
+    }
+    diagnostics.push(
+      diag("DEK005", {
+        message: `data-morph "${morph}" is reserved`,
+        path,
+        ...spotOf(attribute),
+        slug: section.slug,
+        hint: `rename it; the player uses "slide" and "root" for the page itself, and "none", "auto", and "match-element" are CSS keywords`,
+        data: { morph },
+      }),
+    );
+  }
+  return diagnostics;
+}
+
+/**
+ * DEK011: style or script inside the markup, which belongs in the slide's own .css or .ts. Every
+ * occurrence is its own finding: a `<style>` or `<script>` element, a `style` attribute, an event
+ * handler attribute, and a `javascript:` URL.
+ */
+function inlineCodeDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  return scan.elements
+    .flatMap((element) => [
+      {
+        spot: element as SourceSpot,
+        found: inlineElement(element, section.slug),
+        data: { kind: "element", name: element.tag },
+      },
+      ...element.attributes.map((attribute) => ({
+        spot: attribute as SourceSpot,
+        found: inlineAttribute(element.tag, attribute, section.slug),
+        data: { kind: "attribute", name: attribute.name, value: attribute.value },
+      })),
+    ])
+    .flatMap(({ spot, found, data }) =>
+      found
+        ? [
+            diag("DEK011", {
+              message: found.message,
+              path,
+              ...spotOf(spot),
+              slug: section.slug,
+              hint: found.hint,
+              data,
+            }),
+          ]
+        : [],
+    );
+}
+
+type InlineCode = { message: string; hint: string };
+
+function inlineElement(
+  { tag, inSlide }: { tag: string; inSlide: boolean },
+  slug: string,
+): InlineCode | undefined {
+  // In a full document's head it is dropped with the head; in the slide it loads for every slide.
+  if (tag === "link" && inSlide) {
+    return {
+      message: "slide contains a <link>, which loads its stylesheet for every slide",
+      hint: `move what it loads into theme.css, or into slides/${slug}.css for this slide alone; a font goes in assets/ with @font-face`,
+    };
+  }
+  if (tag === "style") {
+    return {
+      message: "slide contains a <style> element",
+      hint: `move the rules to slides/${slug}.css`,
+    };
+  }
+  if (tag === "script") {
+    return { message: "slide contains a <script> element", hint: motionHint(slug) };
+  }
+  return undefined;
+}
+
+function inlineAttribute(
+  tag: string,
+  attribute: HtmlAttribute,
+  slug: string,
+): InlineCode | undefined {
+  if (attribute.name === "style") {
+    return {
+      message: "slide contains a style attribute",
+      hint: `move it to a class in slides/${slug}.css, using token var()`,
+    };
+  }
+  if (EVENT_HANDLER_RE.test(attribute.name)) {
+    return {
+      message: `slide contains an ${attribute.name} attribute`,
+      hint: `remove it; a slide takes no input, and motion goes in slides/${slug}.ts as a draw(t) function`,
+    };
+  }
+  if (isUrlAttribute(tag, attribute.name) && isJavascriptUrl(attribute.value)) {
+    return { message: "slide contains a javascript: URL", hint: motionHint(slug) };
+  }
+  return undefined;
+}
+
+function motionHint(slug: string): string {
+  return `move motion to slides/${slug}.ts as a draw(t) function`;
+}
+
+/** `onclick`, `onload`, and every other attribute the browser runs as script. */
+const EVENT_HANDLER_RE = /^on[a-z]+$/;
+/** Read the way the URL parser reads it: tabs and newlines dropped, leading space trimmed, any case. */
+function isJavascriptUrl(value: string): boolean {
+  return value
+    .replace(/[\t\n\r]/g, "")
+    .trimStart()
+    .toLowerCase()
+    .startsWith("javascript:");
+}
+
+/**
+ * DEK024: a heading with nothing in it, which the audience sees as a gap where a title should
+ * be. An id-only `##` heading after the first slide makes one: sync never puts the id on a slide.
+ * Such a heading may also mean the slide has no title, as a quote's does, so its skeleton's hint
+ * offers both: a title for sync to write, or the element gone, which sync then leaves alone.
+ */
+function emptyHeadingDiagnostics({ section, path, scan, skeleton }: SlideHtml): Diagnostic[] {
+  const hint = skeleton
+    ? `give the slide a title in script.md, like \`## Your title {#${section.slug}}\`, then run \`dekc sync\`; for a slide with no title, such as a quote, remove the element from slides/${section.slug}.html`
+    : `write the heading's text in slides/${section.slug}.html, or remove the element`;
+  return scan.emptyHeadings.map((element) =>
+    diag("DEK024", {
+      message: `<${element.tag}> is empty, so the slide shows no heading`,
+      path,
+      ...spotOf(element),
+      slug: section.slug,
+      hint,
+      data: { tag: element.tag },
+    }),
+  );
+}
+
+/** How much of a hidden text a message quotes. */
+const HIDDEN_SNIPPET_CHARS = 24;
+
+/**
+ * DEK029: text under `aria-hidden="true"`. That is how a slide marks decoration, and lint
+ * measures neither the contrast nor the overflow of anything under it, so a labeled figure
+ * marked that way is text the audience reads and no check sees. Right only on a sample the talk
+ * shows as unreadable, so it warns.
+ */
+function hiddenTextDiagnostics({ section, path, scan }: SlideHtml): Diagnostic[] {
+  return scan.hiddenTexts.map(({ element, text }) => {
+    const chars = [...text];
+    const quoted =
+      chars.length > HIDDEN_SNIPPET_CHARS
+        ? `${chars.slice(0, HIDDEN_SNIPPET_CHARS).join("")}…`
+        : text;
+    const svg =
+      element.tag === "svg" ? '; an SVG can take role="img" and an aria-label instead' : "";
+    return diag("DEK029", {
+      message: `<${element.tag} aria-hidden="true"> holds text the audience reads, "${quoted}", which lint does not measure`,
+      path,
+      ...spotOf(element),
+      slug: section.slug,
+      hint: `if the audience should read it, remove aria-hidden="true" from it so lint measures its contrast and overflow${svg}. Keep aria-hidden only on decoration, or on a sample the talk shows as unreadable`,
+      data: { tag: element.tag, text },
+    });
+  });
+}
+
+/** DEK010: a class neither theme.css nor the slide's own stylesheet defines. */
+function unknownClassDiagnostics(
+  { section, path, scan }: SlideHtml,
+  classes: Set<string>,
+  hasScript: boolean,
+): Diagnostic[] {
+  // `slide` is the root every slide already has, never a word to give content.
+  const known = [...classes].filter((name) => name !== "slide").sort();
+  const shown =
+    known.length > MAX_HINT_CLASSES ? [...known.slice(0, MAX_HINT_CLASSES), "…"] : known;
+  const scriptHint = hasScript
+    ? `; to find an element from slides/${section.slug}.ts, use a data-* attribute instead`
+    : "";
+  const hint =
+    known.length === 0
+      ? `define it in slides/${section.slug}.css, or in theme.css for every slide; the theme defines no class yet${scriptHint}`
+      : `define it in slides/${section.slug}.css, or use one of: ${shown.join(", ")}${scriptHint}`;
+  const unknown = new Map<string, HtmlAttribute>();
+  for (const attribute of attributesNamed(scan, "class")) {
+    for (const name of attribute.value.split(/\s+/).filter(Boolean)) {
+      if (!classes.has(name) && !unknown.has(name)) {
+        unknown.set(name, attribute);
+      }
+    }
+  }
+  return [...unknown].map(([name, attribute]) => {
+    const suggestion = suggest(name, known);
+    return diag("DEK010", {
+      message: `class "${name}" is not defined in theme.css`,
+      path,
+      ...spotOf(attribute),
+      slug: section.slug,
+      hint: suggestion ? `did you mean ${suggestion}? ${hint}` : hint,
+      data: { class: name, ...(suggestion ? { suggestion } : {}) },
+    });
+  });
+}
+
+const MAX_HINT_CLASSES = 20;
+
+function stepHint(section: Section): string {
+  if (section.beats.length === 0) {
+    return `add a ### beat under "## ${section.title}" in script.md, or drop data-step`;
+  }
+  return formatStepChoices(stepChoices(section.beats));
+}

package/src/core/lint/slide-script.ts

@@ -0,0 +1,179 @@
+import { readFileSync } from "node:fs";
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import { listSlideFiles } from "../resolve.ts";
+import type { Section } from "../schema.ts";
+import type { SlideScriptProblem } from "../slide-script.ts";
+import type { ScriptInput } from "../slide-script-eval.ts";
+import { stepKeys } from "../step.ts";
+import type { DeckFiles, LintContext } from "./context.ts";
+
+export type LintedScript = { section: Section; path: string; input: ScriptInput };
+
+/**
+ * The `slides/<slug>.ts` scripts lint evaluates, each read once: one per section that has HTML.
+ * Evaluating is the slow part of lint, so `lintDeck` does it before the rules run.
+ */
+export function lintedSlideScripts(files: DeckFiles): LintedScript[] {
+  const scripts = new Map(listSlideFiles(files.deck.dir, ".ts").map((file) => [file.slug, file]));
+  return [...files.sectionsBySlug.values()].flatMap((section) => {
+    const path = scripts.get(section.slug)?.path;
+    if (!path || !files.slidesBySlug.has(section.slug)) {
+      return [];
+    }
+    const steps = stepKeys(section.beats);
+    return [{ section, path, input: { code: readFileSync(path, "utf8"), steps } }];
+  });
+}
+
+/** DEK016 from what evaluating each script found, and DEK017 from its source, by slug. */
+export function slideScriptDiagnostics(
+  scripted: LintedScript[],
+  problems: SlideScriptProblem[][],
+): Map<string, Diagnostic[]> {
+  return new Map(
+    scripted.map(({ section, path, input }, index) => [
+      section.slug,
+      [
+        ...(problems[index] ?? []).map(({ message, line, hint }) =>
+          diag("DEK016", {
+            message,
+            path,
+            ...(line !== undefined ? { line } : {}),
+            slug: section.slug,
+            ...(hint !== undefined ? { hint } : {}),
+            data: { file: `slides/${section.slug}.ts` },
+          }),
+        ),
+        ...seekProblems(input.code).map((problem) =>
+          diag("DEK017", { path, slug: section.slug, ...problem }),
+        ),
+      ],
+    ]),
+  );
+}
+
+/** DEK016 for a slides/<slug>.js, which dek does not load: motion is written in TypeScript. */
+export function javascriptDiagnostics(ctx: LintContext): Diagnostic[] {
+  return listSlideFiles(ctx.deck.dir, ".js").map((file) =>
+    diag("DEK016", {
+      message: `slide scripts are TypeScript; rename ${file.slug}.js to ${file.slug}.ts`,
+      path: file.path,
+      slug: file.slug,
+      hint: `run \`mv slides/${file.slug}.js slides/${file.slug}.ts\`; plain JavaScript is valid TypeScript`,
+      data: { file: `slides/${file.slug}.js` },
+    }),
+  );
+}
+
+export type SeekProblem = {
+  line: number;
+  message: string;
+  /** The call that reads a clock, or the class used to find an element. */
+  data: { call: string } | { class: string };
+};
+
+const CLOCK_MESSAGE =
+  "runs on its own clock; draw from t alone so video and screenshots can seek it";
+
+type SeekFinding = { message: string; data: SeekProblem["data"] } | undefined;
+
+const clock = (call: string): SeekFinding => ({
+  message: `${call} ${CLOCK_MESSAGE}`,
+  data: { call },
+});
+const byClass = (name: string | undefined): SeekFinding =>
+  name
+    ? {
+        message: `finds elements by class ".${name}"; give the element a data-* attribute and select that`,
+        data: { class: name },
+      }
+    : undefined;
+
+const SEEK_PATTERNS: Array<{ re: RegExp; find: (match: RegExpMatchArray) => SeekFinding }> = [
+  {
+    re: /\b(setTimeout|setInterval|requestAnimationFrame|requestIdleCallback|Date\.now|performance\.now)\s*\(/g,
+    find: (m) => clock(m[1] ?? ""),
+  },
+  { re: /\bnew\s+Date\b/g, find: () => clock("new Date") },
+  {
+    re: /\bMath\.random\s*\(/g,
+    find: () => ({
+      message: "Math.random differs on every call; derive the value from t or the slide's beats",
+      data: { call: "Math.random" },
+    }),
+  },
+  {
+    re: /\b(?:querySelectorAll|querySelector|closest|matches)\s*\(\s*(["'`])((?:(?!\1)[^\\\n])*)\1/g,
+    find: (m) =>
+      byClass((m[2] ?? "").replace(/\[[^\]]*\]/g, "").match(/\.(-?[_a-zA-Z][\w-]*)/)?.[1]),
+  },
+  { re: /\bgetElementsByClassName\s*\(\s*(["'`])\s*([\w-]+)/g, find: (m) => byClass(m[2]) },
+  {
+    // One slide is on a still page, and every slide is in the built deck.
+    re: /\bdocument\s*\.\s*(querySelectorAll|querySelector|getElementById|getElementsBy\w+|body|documentElement)\b/g,
+    find: (m) => ({
+      message: `document.${m[1]} reaches every slide in the deck; find elements from the slide draw is given, as slide.querySelector`,
+      data: { call: `document.${m[1]}` },
+    }),
+  },
+];
+
+/**
+ * DEK017: what makes a slide script draw something other than a function of
+ * `t`, so a seek to the same `t` in video, screenshots, or the PDF would not
+ * give the same frame. Also classes used to find elements, which a theme may
+ * rename. Comments are ignored; lines are 1-based.
+ */
+export function seekProblems(code: string): SeekProblem[] {
+  const source = blankComments(code);
+  const found: Array<SeekProblem & { index: number }> = [];
+  for (const { re, find } of SEEK_PATTERNS) {
+    for (const match of source.matchAll(re)) {
+      const finding = find(match);
+      if (finding) {
+        const index = match.index ?? 0;
+        found.push({ index, line: source.slice(0, index).split("\n").length, ...finding });
+      }
+    }
+  }
+  return found.sort((a, b) => a.index - b.index).map(({ index: _index, ...problem }) => problem);
+}
+
+/** Comments replaced by spaces, newlines and string literals kept. */
+function blankComments(code: string): string {
+  let out = "";
+  let quote: string | undefined;
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i] ?? "";
+    if (quote !== undefined) {
+      out += ch;
+      if (ch === "\\") {
+        out += code[i + 1] ?? "";
+        i++;
+      } else if (ch === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if (ch === "/" && code[i + 1] === "/") {
+      while (i < code.length && code[i] !== "\n") {
+        out += " ";
+        i++;
+      }
+      out += code[i] ?? "";
+      continue;
+    }
+    if (ch === "/" && code[i + 1] === "*") {
+      const end = code.indexOf("*/", i + 2);
+      const stop = end < 0 ? code.length : end + 2;
+      out += code.slice(i, stop).replace(/[^\n]/g, " ");
+      i = stop - 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+    }
+    out += ch;
+  }
+  return out;
+}