@hajimism/dek 0.1.0

package/src/core/lint.ts

@@ -0,0 +1,137 @@
+import { cssClassNames, cssLayoutNames } from "./css.ts";
+import type { Diagnostic } from "./diagnostic.ts";
+import { type DeckFiles, type LintContext, readDeckFiles } from "./lint/context.ts";
+import { pairingDiagnostics, suggestRename } from "./lint/files.ts";
+import { frontmatterKeyDiagnostics, tomlKeyDiagnostics } from "./lint/keys.ts";
+import { unpairedMorphDiagnostics } from "./lint/morph.ts";
+import { duplicateIdDiagnostics, strayHeadingDiagnostics } from "./lint/script.ts";
+import { sharedStyleDiagnostics } from "./lint/shared-styles.ts";
+import { lintSlideHtml } from "./lint/slide-html.ts";
+import {
+  javascriptDiagnostics,
+  type LintedScript,
+  lintedSlideScripts,
+  slideScriptDiagnostics,
+} from "./lint/slide-script.ts";
+import { lintSlideStyle, themeDiagnostics } from "./lint/theme-css.ts";
+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 { evaluateSlideScripts, slideScriptsProblems } from "./slide-script-eval.ts";
+
+export { unreadableScriptDiagnostics } from "./lint/script.ts";
+export { silentCueDiagnostics } from "./lint/voice.ts";
+
+export type LintDeckOptions = {
+  /** Only this slide's findings: the ones that name it. Deck findings are `dekc lint`'s. */
+  slug?: string;
+};
+
+type DeckInput = string | { project: Project; deck: ProjectDeck };
+
+/**
+ * The project's own findings (DEK008 on dek.toml): the same for every deck, so a command that
+ * covers several decks reports them once, beside each deck's `lintDeck`.
+ */
+export function lintProject(project: Project): Diagnostic[] {
+  return tomlKeyDiagnostics(project);
+}
+
+/**
+ * Every deck and slide rule over one deck, or with `slug` only that slide's. Each module under
+ * lint/ owns the rules of one kind of file and exports them as functions of the shared context;
+ * this puts their findings in order. Slide scripts are evaluated first, in a child process that
+ * this waits for; the dev server uses `lintDeckAsync` instead.
+ */
+export function lintDeck(dir: string, options?: LintDeckOptions): Diagnostic[];
+export function lintDeck(
+  source: { project: Project; deck: ProjectDeck },
+  options?: LintDeckOptions,
+): Diagnostic[];
+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);
+}
+
+/**
+ * `lintDeck` that evaluates slide scripts off the event loop. The scripts are read once, before
+ * the evaluation, so one saved meanwhile is checked on the next pass instead of in this one.
+ */
+export async function lintDeckAsync(
+  input: DeckInput,
+  options?: LintDeckOptions,
+): Promise<Diagnostic[]> {
+  const { files, scripted } = readLintInput(input);
+  const problems = await evaluateSlideScripts(scripted.map((entry) => entry.input));
+  return runRules({ ...files, scripts: slideScriptDiagnostics(scripted, problems) }, options);
+}
+
+function readLintInput(input: DeckInput): { files: DeckFiles; scripted: LintedScript[] } {
+  const { project, deck } = asResolvedDeck(input);
+  const files = readDeckFiles(project, deck);
+  return { files, scripted: lintedSlideScripts(files) };
+}
+
+/**
+ * A finding with a slug is about that slide; one without is about the deck. So one slide's
+ * check is the findings that name it, whichever rule made them: no rule filters on its own.
+ */
+function runRules(ctx: LintContext, options: LintDeckOptions | undefined): Diagnostic[] {
+  const diagnostics = [
+    ...frontmatterKeyDiagnostics(ctx),
+    ...suggestRename(
+      [
+        ...duplicateIdDiagnostics(ctx),
+        ...pairingDiagnostics(ctx),
+        ...javascriptDiagnostics(ctx),
+        ...themeDiagnostics(ctx),
+        ...[...ctx.sectionsBySlug.values()].flatMap((section) => slideDiagnostics(ctx, section)),
+        ...unpairedMorphDiagnostics(ctx),
+        ...sharedStyleDiagnostics(ctx),
+      ],
+      ctx,
+    ),
+    ...voiceDiagnostics(ctx),
+    ...strayHeadingDiagnostics(ctx),
+    ...timingDiagnostics(ctx),
+  ];
+  const slug = options?.slug;
+  return slug === undefined
+    ? diagnostics
+    : diagnostics.filter((diagnostic) => diagnostic.slug === slug);
+}
+
+/** Everything about one slide that has HTML: its stylesheet, its script, then its markup. */
+function slideDiagnostics(ctx: LintContext, section: Section): Diagnostic[] {
+  const slide = ctx.slidesBySlug.get(section.slug);
+  const source = ctx.slideSource(section.slug);
+  if (!slide || !source) {
+    return [];
+  }
+  const style = ctx.slideStyle(section.slug);
+  const sheet = style?.sheet;
+  const script = ctx.scripts.get(section.slug);
+  return [
+    ...(style
+      ? lintSlideStyle(section.slug, style.path, style.sheet, ctx.theme?.tokens ?? [], ctx.deck.dir)
+      : []),
+    ...(script ?? []),
+    ...lintSlideHtml(section, slide.path, source.scan, {
+      deckDir: ctx.deck.dir,
+      skeleton: source.skeleton,
+      hasScript: script !== undefined,
+      classes: ctx.theme && new Set([...ctx.theme.classes, ...(sheet ? cssClassNames(sheet) : [])]),
+      // A theme with no layouts at all has nothing to check a data-layout against.
+      ...(ctx.theme && ctx.theme.layouts.length > 0
+        ? {
+            layouts: new Set([
+              ...ctx.theme.layouts.map((layout) => layout.name),
+              ...(sheet ? cssLayoutNames(sheet) : []),
+            ]),
+          }
+        : {}),
+    }),
+  ];
+}

package/src/core/live-protocol.ts

@@ -0,0 +1,130 @@
+import type { Diagnostic } from "./diagnostic.ts";
+import type { Position } from "./step.ts";
+
+/**
+ * What the dev server tells an open deck on `/events`. The server sends these and the page
+ * reads them, so both sides take the shape from here.
+ */
+export type LiveEvent =
+  /** Slides by slug: the stream reaches the audience, so it names no path on disk. */
+  | { type: "sync"; created: string[]; updated?: string[]; removed?: string[] }
+  | { type: "reload-slide"; slug: string }
+  | { type: "reload-theme" }
+  | { type: "reload-script"; slugs: string[] }
+  | { type: "diagnostics"; diagnostics: Diagnostic[] }
+  | { type: "timeline" };
+
+export type LiveEventType = LiveEvent["type"];
+
+const isStrings = (value: unknown): value is string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === "string");
+
+const isOptionalStrings = (value: unknown): boolean => value === undefined || isStrings(value);
+
+/** Checks each type's own fields; a new type must be placed here to be let through. */
+const FIELDS_OK: Record<LiveEventType, (event: Record<string, unknown>) => boolean> = {
+  sync: (event) =>
+    isStrings(event.created) &&
+    isOptionalStrings(event.updated) &&
+    isOptionalStrings(event.removed),
+  "reload-slide": (event) => typeof event.slug === "string",
+  "reload-theme": () => true,
+  "reload-script": (event) => isStrings(event.slugs),
+  diagnostics: (event) => Array.isArray(event.diagnostics),
+  timeline: () => true,
+};
+
+/** Whether a message read off the stream is one this build of the page understands. */
+export function isLiveEvent(value: unknown): value is LiveEvent {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const event = value as Record<string, unknown>;
+  const type = event.type;
+  return typeof type === "string" && Object.hasOwn(FIELDS_OK, type)
+    ? FIELDS_OK[type as LiveEventType](event)
+    : false;
+}
+
+/**
+ * A position on the wire: what the socket, the server's rooms, and the windows of one deck send
+ * each other. Only the two indexes travel, so nothing else rides along to a room.
+ */
+export function encodePosition(pos: Position): string {
+  return JSON.stringify({ slideIndex: pos.slideIndex, beatIndex: pos.beatIndex });
+}
+
+/** A position read off the wire, as text or as the object a BroadcastChannel carries. */
+export function decodePosition(raw: unknown): Position | undefined {
+  let value = raw;
+  if (typeof raw === "string") {
+    try {
+      value = JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+  if (typeof value !== "object" || value === null) {
+    return undefined;
+  }
+  const { slideIndex, beatIndex } = value as Record<string, unknown>;
+  return isIndex(slideIndex) && isIndex(beatIndex) ? { slideIndex, beatIndex } : undefined;
+}
+
+const isIndex = (value: unknown): value is number =>
+  typeof value === "number" && Number.isInteger(value) && value >= 0;
+
+/**
+ * Where the laser points: a slide, and a point on it as a share of its width and height, so every
+ * window draws it at the same place on the slide whatever size the window is.
+ */
+export type Pointer = { slideIndex: number; x: number; y: number };
+
+/** What the laser says on the wire: where it points, or null once it went away. */
+export type PointerMessage = { pointer: Pointer | null };
+
+/** Four decimals: a ten-thousandth of the slide is finer than any screen shows it. */
+const round = (share: number): number => Math.round(share * 10_000) / 10_000;
+
+export function encodePointer(pointer: Pointer | null): string {
+  return JSON.stringify({
+    pointer: pointer && {
+      slideIndex: pointer.slideIndex,
+      x: round(pointer.x),
+      y: round(pointer.y),
+    },
+  });
+}
+
+/**
+ * A laser message read off the wire, as text or as the object a BroadcastChannel carries; nothing
+ * for anything else, a position included. Only the three fields travel, within the slide.
+ */
+export function decodePointer(raw: unknown): PointerMessage | undefined {
+  const value = typeof raw === "string" ? parseJson(raw) : raw;
+  if (typeof value !== "object" || value === null || !Object.hasOwn(value, "pointer")) {
+    return undefined;
+  }
+  const pointer = (value as { pointer: unknown }).pointer;
+  if (pointer === null) {
+    return { pointer: null };
+  }
+  if (typeof pointer !== "object") {
+    return undefined;
+  }
+  const { slideIndex, x, y } = pointer as Record<string, unknown>;
+  return isIndex(slideIndex) && isShare(x) && isShare(y)
+    ? { pointer: { slideIndex, x, y } }
+    : undefined;
+}
+
+function parseJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+const isShare = (value: unknown): value is number =>
+  typeof value === "number" && value >= 0 && value <= 1;

package/src/core/marks.ts

@@ -0,0 +1,198 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { DekError } from "./error.ts";
+import type { ProjectDeck } from "./resolve.ts";
+import { readSourceIfExists, writeInside } from "./safe-fs.ts";
+import type { Section } from "./schema.ts";
+import type { Position } from "./step.ts";
+import { formatZodIssues } from "./zod.ts";
+
+/**
+ * A mark the speaker left on a beat while rehearsing: these words want rewriting. It names its
+ * beat by the section's slug and the beat's id, or its title when it has none, never by index,
+ * so it stays on its beat while beats are added before it. It keeps the words as they were when
+ * marked, so a reader can tell a beat already rewritten from one still waiting.
+ */
+const Mark = z.object({
+  slug: z.string(),
+  /** The beat's title; null for what the slide says as it arrives, before its first `###`. */
+  beat: z.string().nullable(),
+  id: z.string().optional(),
+  was: z.string(),
+  markedAt: z.string(),
+});
+
+type Mark = z.infer<typeof Mark>;
+
+/** Every deck's marks, by deck name, in one file of the project's. */
+const MarksFile = z.object({ version: z.literal(1), decks: z.record(z.string(), z.array(Mark)) });
+
+type MarksFile = z.infer<typeof MarksFile>;
+
+/** Where the marks are kept: beside the dev server's lock, out of every deck. */
+export function marksPath(root: string): string {
+  return join(root, ".dek", "marks.json");
+}
+
+/**
+ * A mark as the script has it now: where its beat is and what it says, or `gone` when no beat by
+ * its name is left. `edited` once the words differ from what was marked.
+ */
+export type MarkRow = {
+  slug: string;
+  beat: string | null;
+  beatIndex: number | null;
+  line: number | null;
+  path: string;
+  status: "open" | "edited" | "gone";
+  was: string;
+  text: string | null;
+  markedAt: string;
+};
+
+/** Mark the beat at `position`, or unmark it when it is marked; the deck's marks after. */
+export function toggleMark(
+  root: string,
+  deck: ProjectDeck,
+  position: Position,
+  now: Date = new Date(),
+): { marked: boolean; positions: Position[] } {
+  const beat = beatAt(deck.deck.sections, position);
+  if (!beat) {
+    throw new DekError(
+      `no beat ${position.beatIndex} on slide ${position.slideIndex + 1} of deck "${deck.name}"`,
+      { hint: "reload the presenter view: the script changed since it opened" },
+    );
+  }
+  const file = readMarksFile(root);
+  const marks = file.decks[deck.name] ?? [];
+  const at = marks.findIndex((mark) => sameBeat(mark, beat));
+  const next =
+    at >= 0
+      ? marks.filter((_, index) => index !== at)
+      : [...marks, { ...beat.anchor, was: beat.text, markedAt: now.toISOString() }];
+  writeMarksFile(root, deck.name, next, file);
+  return {
+    marked: at < 0,
+    positions: positionsOf(deck, next),
+  };
+}
+
+/** The deck's marks in the order they were made, each where the script has it now. */
+export function listMarks(root: string, deck: ProjectDeck): MarkRow[] {
+  return (readMarksFile(root).decks[deck.name] ?? []).map((mark) => {
+    const found = findBeat(deck.deck.sections, mark);
+    const text = found?.text ?? null;
+    return {
+      slug: mark.slug,
+      beat: found ? found.anchor.beat : mark.beat,
+      beatIndex: found?.position.beatIndex ?? null,
+      line: found?.line ?? null,
+      path: deck.scriptPath,
+      status: !found ? "gone" : text === mark.was ? "open" : "edited",
+      was: mark.was,
+      text,
+      markedAt: mark.markedAt,
+    };
+  });
+}
+
+/** Where the deck's marked beats are now; a mark whose beat is gone is on no slide. */
+export function markedPositions(root: string, deck: ProjectDeck): Position[] {
+  return positionsOf(deck, readMarksFile(root).decks[deck.name] ?? []);
+}
+
+/** Drop the deck's marks, the other decks' kept; how many there were. */
+export function clearMarks(root: string, deck: ProjectDeck): number {
+  const file = readMarksFile(root);
+  const count = file.decks[deck.name]?.length ?? 0;
+  if (count > 0) {
+    writeMarksFile(root, deck.name, [], file);
+  }
+  return count;
+}
+
+type FoundBeat = {
+  position: Position;
+  line: number;
+  text: string;
+  anchor: Pick<Mark, "slug" | "beat" | "id">;
+};
+
+function beatsOf(sections: Section[]): FoundBeat[] {
+  return sections.flatMap((section, slideIndex) => [
+    {
+      position: { slideIndex, beatIndex: 0 },
+      line: section.line,
+      text: section.body,
+      anchor: { slug: section.slug, beat: null },
+    },
+    ...section.beats.map((beat, index) => ({
+      position: { slideIndex, beatIndex: index + 1 },
+      line: beat.line,
+      text: beat.body,
+      anchor: { slug: section.slug, beat: beat.title, ...(beat.id ? { id: beat.id } : {}) },
+    })),
+  ]);
+}
+
+function beatAt(sections: Section[], position: Position): FoundBeat | undefined {
+  return beatsOf(sections).find(
+    (beat) =>
+      beat.position.slideIndex === position.slideIndex &&
+      beat.position.beatIndex === position.beatIndex,
+  );
+}
+
+function findBeat(sections: Section[], mark: Mark): FoundBeat | undefined {
+  return beatsOf(sections).find((beat) => sameBeat(mark, beat));
+}
+
+/** A beat with an id is known by it, so retitling it keeps its mark; any other, by its title. */
+function sameBeat(mark: Pick<Mark, "slug" | "beat" | "id">, beat: FoundBeat): boolean {
+  if (mark.slug !== beat.anchor.slug) {
+    return false;
+  }
+  return mark.id !== undefined ? mark.id === beat.anchor.id : mark.beat === beat.anchor.beat;
+}
+
+function positionsOf(deck: ProjectDeck, marks: Mark[]): Position[] {
+  return marks
+    .flatMap((mark) => {
+      const found = findBeat(deck.deck.sections, mark);
+      return found ? [found.position] : [];
+    })
+    .sort((a, b) => a.slideIndex - b.slideIndex || a.beatIndex - b.beatIndex);
+}
+
+function readMarksFile(root: string): MarksFile {
+  const path = marksPath(root);
+  const text = readSourceIfExists(path, root);
+  if (text === undefined) {
+    return { version: 1, decks: {} };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw unreadable(path, error instanceof Error ? error.message : String(error));
+  }
+  const parsed = MarksFile.safeParse(value);
+  if (!parsed.success) {
+    throw unreadable(path, formatZodIssues(parsed.error));
+  }
+  return parsed.data;
+}
+
+function unreadable(path: string, why: string): DekError {
+  return new DekError(`.dek/marks.json does not read: ${why}`, {
+    path,
+    hint: "delete .dek/marks.json to start over; every deck's marks go with it",
+  });
+}
+
+function writeMarksFile(root: string, deck: string, marks: Mark[], file: MarksFile): void {
+  const { [deck]: _old, ...others } = file.decks;
+  const decks = marks.length > 0 ? { ...others, [deck]: marks } : others;
+  writeInside(marksPath(root), `${JSON.stringify({ version: 1, decks }, null, 2)}\n`, root);
+}