@hajimism/dek 0.1.0

package/src/core/lint/files.ts

@@ -0,0 +1,117 @@
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import { either } from "../prose.ts";
+import { listSlideFiles, SLIDE_SIDECARS } from "../resolve.ts";
+import type { LintContext } from "./context.ts";
+
+/** DEK001 for a section without slides/<slug>.html; DEK002 for a slide file without its section. */
+export function pairingDiagnostics(ctx: LintContext): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  for (const section of ctx.deck.deck.sections) {
+    if (ctx.slidesBySlug.has(section.slug)) {
+      continue;
+    }
+    diagnostics.push(
+      diag("DEK001", {
+        message: `missing slide HTML for "${section.slug}"`,
+        path: ctx.deck.scriptPath,
+        line: section.line,
+        slug: section.slug,
+        hint: "run `dekc sync` to create the skeleton",
+        data: { expected: `slides/${section.slug}.html` },
+      }),
+    );
+  }
+
+  for (const slide of ctx.slidesBySlug.values()) {
+    if (ctx.sectionsBySlug.has(slide.slug)) {
+      continue;
+    }
+    diagnostics.push(
+      diag("DEK002", {
+        message: `slide HTML has no section "${slide.slug}"`,
+        path: slide.path,
+        slug: slide.slug,
+        hint: orphanHint(slide.slug, `slides/${slide.slug}.html`),
+        data: { slug: slide.slug, file: `slides/${slide.slug}.html` },
+      }),
+    );
+  }
+
+  for (const ext of SLIDE_SIDECARS) {
+    const kind = ext === ".css" ? "stylesheet" : "script";
+    for (const file of listSlideFiles(ctx.deck.dir, ext)) {
+      // A sidecar next to an orphaned HTML file travels with it; DEK002 already names the slug.
+      if (ctx.sectionsBySlug.has(file.slug) || ctx.slidesBySlug.has(file.slug)) {
+        continue;
+      }
+      diagnostics.push(
+        diag("DEK002", {
+          message: `slide ${kind} has no section "${file.slug}"`,
+          path: file.path,
+          slug: file.slug,
+          hint: orphanHint(file.slug, `slides/${file.slug}${ext}`),
+          data: { slug: file.slug, file: `slides/${file.slug}${ext}` },
+        }),
+      );
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * What to do with a slide file the script does not name, when no rename explains it: give it a
+ * section, or take it out of the talk. Which one is the author's call.
+ */
+function orphanHint(slug: string, file: string): string {
+  const title = slug.charAt(0).toUpperCase() + slug.slice(1).replaceAll("-", " ");
+  return `add a section for it to script.md, like \`## ${title} {#${slug}}\`, or remove ${file} if the slide is gone from the talk`;
+}
+
+/**
+ * An orphaned HTML file beside sections without their own slide (missing, or still the skeleton
+ * the dev server generated on save) looks like a heading renamed in script.md first. `dekc mv`
+ * finishes that rename from either state, so each orphan's hint names a `dekc mv` for every such
+ * section, in script order, rather than asking to delete a slide someone wrote. With one of each
+ * the pairing is certain, and both diagnostics also offer the rename the other way.
+ */
+export function suggestRename(diagnostics: Diagnostic[], ctx: LintContext): Diagnostic[] {
+  const orphans = new Set(
+    diagnostics.filter(
+      (diagnostic) => diagnostic.id === "DEK002" && diagnostic.path?.endsWith(".html"),
+    ),
+  );
+  const targets = ctx.deck.deck.sections
+    .filter(
+      (section) =>
+        !ctx.slidesBySlug.has(section.slug) || ctx.slideSource(section.slug)?.skeleton === true,
+    )
+    .map((section) => section.slug);
+  if (orphans.size === 0 || targets.length === 0) {
+    return diagnostics;
+  }
+  const [orphan] = orphans;
+  const [target] = targets;
+  if (orphans.size === 1 && targets.length === 1 && orphan?.slug && target) {
+    // An orphan beside a section without its own slide is a rename, made in the script or in the
+    // files: which one is the author's to say, and each command finishes it from this state.
+    const hint = `run \`dekc mv ${orphan.slug} ${target}\` to move the files to the script's id, or \`dekc mv ${target} ${orphan.slug}\` to give the section the files' id`;
+    return diagnostics.map((diagnostic) =>
+      diagnostic === orphan
+        ? { ...diagnostic, hint, data: { ...diagnostic.data, renames: targets } }
+        : diagnostic.id === "DEK001" && diagnostic.slug === target
+          ? { ...diagnostic, hint }
+          : diagnostic,
+    );
+  }
+  return diagnostics.map((diagnostic) => {
+    if (!orphans.has(diagnostic) || !diagnostic.slug) {
+      return diagnostic;
+    }
+    const commands = targets.map((slug) => `\`dekc mv ${diagnostic.slug} ${slug}\``);
+    return {
+      ...diagnostic,
+      hint: `run ${either(commands)} to move the files to the section they now belong to`,
+      data: { ...diagnostic.data, renames: targets },
+    };
+  });
+}

package/src/core/lint/keys.ts

@@ -0,0 +1,48 @@
+import {
+  FRONTMATTER_KEYS,
+  type UnknownKey,
+  unknownFrontmatterKeys,
+  unknownTomlKeys,
+} from "../config-keys.ts";
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import { type Project, readTextIfExists } from "../resolve.ts";
+import type { LintContext } from "./context.ts";
+
+/*
+ * DEK008: a key in dek.toml or the frontmatter that dek does not read. Parsing drops it
+ * without a word, so a typo leaves the default in place and nobody knows why.
+ */
+
+/** DEK008 for dek.toml: a project finding, the same for every deck. */
+export function tomlKeyDiagnostics(project: Project): Diagnostic[] {
+  return unknownTomlKeys(readTextIfExists(project.configPath) ?? "").map((key) =>
+    unknownKeyDiagnostic(key, { file: "dek.toml", path: project.configPath }),
+  );
+}
+
+/** DEK008 for the deck's frontmatter. */
+export function frontmatterKeyDiagnostics({ deck, script }: LintContext): Diagnostic[] {
+  return (script ? unknownFrontmatterKeys(script.yaml, 2) : []).map((key) =>
+    unknownKeyDiagnostic(key, { file: "frontmatter", path: deck.scriptPath }),
+  );
+}
+
+function unknownKeyDiagnostic(
+  { key, line, suggestion }: UnknownKey,
+  where: { file: "dek.toml" | "frontmatter"; path: string },
+): Diagnostic {
+  const place = where.file === "dek.toml" ? "dek.toml" : "the frontmatter";
+  const known =
+    where.file === "dek.toml"
+      ? `see ${REFERENCE_URL}#dek-toml`
+      : `the keys are ${FRONTMATTER_KEYS.join(", ")}; see ${REFERENCE_URL}#frontmatter`;
+  return diag("DEK008", {
+    message: `unknown key ${key} in ${place}; dek ignores it`,
+    path: where.path,
+    line,
+    hint: suggestion ? `did you mean ${suggestion}?` : known,
+    data: { file: where.file, key, ...(suggestion ? { suggestion } : {}) },
+  });
+}
+
+const REFERENCE_URL = "https://hajimism.github.io/dek/reference/config.html";

package/src/core/lint/morph.ts

@@ -0,0 +1,91 @@
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import type { HtmlAttribute } from "../html-scan.ts";
+import { suggest } from "../suggest.ts";
+import type { LintContext } from "./context.ts";
+
+/** Names the player takes for the page itself, and the CSS keywords of `view-transition-name`. */
+export const RESERVED_MORPHS = new Set(["slide", "root", "none", "auto", "match-element"]);
+
+/**
+ * DEK028: a data-morph that no slide beside it names. The browser morphs an element only into
+ * the element of the same name on the slide it goes to, so a name with no partner on the slide
+ * before or after is a plain fade, however it is spelled. A partner that is one typo away is the
+ * likeliest fix; otherwise the hint names the files a partner could go in.
+ */
+export function unpairedMorphDiagnostics(ctx: LintContext): Diagnostic[] {
+  const order = [...ctx.sectionsBySlug.keys()];
+  const morphs = order.map((slug) => morphsOf(ctx, slug));
+  return order.flatMap((slug, index) => {
+    const own = morphs[index];
+    const path = ctx.slidesBySlug.get(slug)?.path;
+    if (!own || !path) {
+      return [];
+    }
+    const neighbors = [index - 1, index + 1].flatMap((at) => {
+      const names = morphs[at];
+      const neighbor = order[at];
+      return names && neighbor ? [{ slug: neighbor, names }] : [];
+    });
+    return [...own].flatMap(([morph, attribute]) => {
+      if (neighbors.some((neighbor) => neighbor.names.has(morph))) {
+        return [];
+      }
+      return [
+        diag("DEK028", {
+          message: `data-morph "${morph}" is on neither slide beside it, so nothing morphs`,
+          path,
+          line: attribute.line,
+          column: attribute.column,
+          slug,
+          hint: partnerHint(morph, neighbors, own),
+          data: { morph, neighbors: neighbors.map((neighbor) => neighbor.slug) },
+        }),
+      ];
+    });
+  });
+}
+
+/** Each data-morph a slide names, at its first use; reserved names are DEK005's. */
+function morphsOf(ctx: LintContext, slug: string): Map<string, HtmlAttribute> | undefined {
+  const scan = ctx.slideSource(slug)?.scan;
+  if (!scan) {
+    return undefined;
+  }
+  const morphs = new Map<string, HtmlAttribute>();
+  for (const element of scan.elements) {
+    for (const attribute of element.attributes) {
+      const morph = attribute.value;
+      if (
+        element.inSlide &&
+        attribute.name === "data-morph" &&
+        !RESERVED_MORPHS.has(morph) &&
+        !morphs.has(morph)
+      ) {
+        morphs.set(morph, attribute);
+      }
+    }
+  }
+  return morphs;
+}
+
+function partnerHint(
+  morph: string,
+  neighbors: { slug: string; names: Map<string, HtmlAttribute> }[],
+  own: Map<string, HtmlAttribute>,
+): string {
+  for (const neighbor of neighbors) {
+    // A name this slide already uses is some other element's partner, not this one's.
+    const guess = suggest(
+      morph,
+      [...neighbor.names.keys()].filter((name) => !own.has(name)),
+    );
+    if (guess) {
+      return `did you mean "${guess}", as in slides/${neighbor.slug}.html?`;
+    }
+  }
+  if (neighbors.length === 0) {
+    return "remove it; a morph carries an element into the slide before or after, and this deck has no other";
+  }
+  const files = neighbors.map((neighbor) => `slides/${neighbor.slug}.html`).join(" or ");
+  return `give its partner data-morph="${morph}" in ${files}, or remove it`;
+}

package/src/core/lint/script.ts

@@ -0,0 +1,102 @@
+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 type { LintContext } from "./context.ts";
+
+/** DEK004: a section id or a beat id used twice. */
+export function duplicateIdDiagnostics(ctx: LintContext): Diagnostic[] {
+  const diagnostics: Diagnostic[] = [];
+  const scriptPath = ctx.deck.scriptPath;
+  const seenSlugs = new Set<string>();
+  for (const section of ctx.deck.deck.sections) {
+    if (seenSlugs.has(section.slug)) {
+      diagnostics.push(
+        diag("DEK004", {
+          message: `duplicate section id "${section.slug}"`,
+          path: scriptPath,
+          line: section.line,
+          slug: section.slug,
+          data: { id: section.slug },
+        }),
+      );
+    } else {
+      seenSlugs.add(section.slug);
+    }
+
+    const seenBeats = new Set<string>();
+    for (const beat of section.beats) {
+      if (!beat.id) {
+        continue;
+      }
+      if (seenBeats.has(beat.id)) {
+        diagnostics.push(
+          diag("DEK004", {
+            message: `duplicate beat id "${beat.id}" in "${section.slug}"`,
+            path: scriptPath,
+            line: beat.line,
+            slug: section.slug,
+            data: { id: beat.id },
+          }),
+        );
+      } else {
+        seenBeats.add(beat.id);
+      }
+    }
+  }
+  return diagnostics;
+}
+
+/**
+ * DEK044: a `#` or `####` heading. Only `##` (slide) and `###` (beat) mean anything, so any
+ * other level is read out as part of the script, `#` and all.
+ */
+export function strayHeadingDiagnostics(ctx: LintContext): Diagnostic[] {
+  const { deck, script } = ctx;
+  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()) {
+    const level = literal ? undefined : text.match(/^(#{1,6})\s/)?.[1]?.length;
+    if (level === undefined || level === 2 || level === 3) {
+      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;
+    diagnostics.push(
+      diag("DEK044", {
+        message: `${"#".repeat(level)} heading is not a slide or a beat; it is read as spoken text`,
+        path: deck.scriptPath,
+        line,
+        ...(slug !== undefined ? { slug } : {}),
+        hint: "use ## for a slide and ### for a beat, or drop the #",
+        data: { level },
+      }),
+    );
+  }
+  return diagnostics;
+}
+
+/**
+ * DEK027: a script.md that cannot be read, one finding for each problem that stops it. Nothing
+ * else in the deck can be checked against a script that does not read, so these are its findings.
+ */
+export function unreadableScriptDiagnostics(deck: {
+  scriptPath: string;
+  error: DekError;
+}): Diagnostic[] {
+  const { error } = deck;
+  const problems = error instanceof ScriptError ? error.problems : [error];
+  return problems.map(({ message, line, hint }) =>
+    diag("DEK027", {
+      message,
+      path: error.path ?? deck.scriptPath,
+      ...(line !== undefined ? { line } : {}),
+      ...(hint !== undefined ? { hint } : {}),
+    }),
+  );
+}

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

@@ -0,0 +1,165 @@
+import { isKeyframesPrelude, selectorClasses, splitSelectorList, startsAtSlide } from "../css.ts";
+import { deckPaths } from "../deck-paths.ts";
+import { type Diagnostic, diag } from "../diagnostic.ts";
+import { listed } from "../prose.ts";
+import type { LintContext } from "./context.ts";
+
+/** How many slides may style something alike before it belongs in the theme: the third copy. */
+const SHARED_BY = 3;
+
+/** One declaration as one slide writes it. */
+type Setting = {
+  /** The selector part as this slide writes it, spaces squashed. */
+  selector: string;
+  declaration: string;
+  atPath: string[];
+  line: number;
+};
+
+/** One slide's share under one selector: the slides it shares any of it with, and its settings. */
+type Finding = { slugs: Set<string>; settings: Setting[] };
+
+const squash = (text: string): string => text.replace(/\s+/g, " ").trim();
+
+/**
+ * A selector part as the slide's scope reads it, the way `scopeToSlide` rewrites it: a leading
+ * `.slide` compound is the slide itself, anything else sits under it. So `.card` and
+ * `.slide .card` match the same elements and are one selector here, and `.slide > .card` is not.
+ */
+function scopedSelector(part: string): string {
+  const item = squash(part);
+  return startsAtSlide(item) ? item.slice(".slide".length) : ` ${item}`;
+}
+
+/**
+ * The selector part as theme.css must write it: under `.slide`, as the theme scopes every rule
+ * and as the slide's own scope already read it.
+ */
+function themeSelector(part: string): string {
+  return `.slide${scopedSelector(part)}`;
+}
+
+/**
+ * The other slides a rule moved into the theme would also reach: the ones whose markup uses
+ * every class the selector names, and that do not set it themselves. A selector with no class,
+ * such as `h2`, is left out: which slides it matches is for the author to look at.
+ */
+function alsoReaches(ctx: LintContext, selector: string, setters: string[]): string[] {
+  const classes = selectorClasses(selector);
+  if (classes.length === 0) {
+    return [];
+  }
+  return [...ctx.sectionsBySlug.keys()].filter((slug) => {
+    const source = setters.includes(slug) ? undefined : ctx.slideSource(slug);
+    const used = source && new Set(source.scan.classes);
+    return used !== undefined && classes.every((name) => used.has(name));
+  });
+}
+
+/**
+ * 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
+ * fix the theme is missing. Each slide hears of it in its own check, once per selector: what it
+ * shares there, and every slide it shares any of that with.
+ */
+export function sharedStyleDiagnostics(ctx: LintContext): Diagnostic[] {
+  // Where a declaration applies and what it sets, to the slides that write it.
+  const bySetting = new Map<string, { where: string; slides: Map<string, Setting> }>();
+  for (const slug of ctx.sectionsBySlug.keys()) {
+    const style = ctx.slideStyle(slug);
+    if (!style) {
+      continue;
+    }
+    for (const decl of style.sheet.decls) {
+      // A slide's keyframes are renamed apart from every other slide's.
+      if (!decl.selector || decl.atPath.some(isKeyframesPrelude)) {
+        continue;
+      }
+      const declaration = `${decl.property}: ${squash(decl.value)}`;
+      for (const part of splitSelectorList(decl.selector)) {
+        const where = [...decl.atPath.map(squash), scopedSelector(part)].join("\0");
+        const key = [where, decl.property.toLowerCase(), squash(decl.value)].join("\0");
+        const entry = bySetting.get(key) ?? { where, slides: new Map<string, Setting>() };
+        if (!entry.slides.has(slug)) {
+          entry.slides.set(slug, {
+            selector: squash(part),
+            declaration,
+            atPath: decl.atPath,
+            line: decl.line,
+          });
+        }
+        bySetting.set(key, entry);
+      }
+    }
+  }
+
+  // Per slide, what it shares under one selector makes one finding, whoever it shares it with.
+  const order = [...ctx.sectionsBySlug.keys()];
+  const findings = new Map<string, Map<string, Finding>>();
+  for (const { where, slides } of bySetting.values()) {
+    if (slides.size < SHARED_BY) {
+      continue;
+    }
+    for (const [slug, setting] of slides) {
+      const groups = findings.get(slug) ?? new Map<string, Finding>();
+      const found = groups.get(where) ?? { slugs: new Set<string>(), settings: [] };
+      for (const other of slides.keys()) {
+        found.slugs.add(other);
+      }
+      found.settings.push(setting);
+      groups.set(where, found);
+      findings.set(slug, groups);
+    }
+  }
+
+  const paths = deckPaths(ctx.deck.dir);
+  const cssOf = (slug: string): string => `slides/${slug}.css`;
+  return order.flatMap((slug) =>
+    [...(findings.get(slug)?.values() ?? [])]
+      // In the order this slide's own file writes them.
+      .map(({ slugs, settings }) => {
+        const own = [...settings].sort((a, b) => a.line - b.line);
+        const all = order.filter((other) => slugs.has(other));
+        return { slugs: all, settings: own, line: own[0]?.line ?? 0 };
+      })
+      .sort((a, b) => a.line - b.line)
+      .map(({ slugs, settings, line }) => {
+        const [first] = settings;
+        const selector = first?.selector ?? "";
+        const atPath = first?.atPath ?? [];
+        const declarations = settings.map((setting) => setting.declaration);
+        const block = `{ ${declarations.join("; ")} }`;
+        const rule = `${[...atPath, selector].join(" ")} ${block}`;
+        const themeRule = `${[...atPath, themeSelector(selector)].join(" ")} ${block}`;
+        const others = slugs.filter((other) => other !== slug).map(cssOf);
+        // Moving it changes these too: a theme default that slides override is a real finding,
+        // and whether the rest should follow is the author's call, made with these in view.
+        const reaches = alsoReaches(ctx, selector, slugs);
+        const htmlOf = (other: string): string => `slides/${other}.html`;
+        const affected =
+          reaches.length === 0
+            ? ""
+            : `; it also reaches ${listed(reaches.map(htmlOf))}, which ${reaches.length === 1 ? "uses" : "use"} ${selectorClasses(
+                selector,
+              )
+                .map((name) => `.${name}`)
+                .join(
+                  "",
+                )} without it, so check ${reaches.length === 1 ? "that slide" : "those slides"} after the move`;
+        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}`,
+          data: {
+            selector,
+            declarations,
+            slides: slugs,
+            ...(atPath.length > 0 ? { atRules: atPath } : {}),
+            ...(reaches.length > 0 ? { alsoReaches: reaches } : {}),
+          },
+        });
+      }),
+  );
+}