@hajimism/dek 0.1.0

package/src/core/resolve.ts

@@ -0,0 +1,228 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { deckPaths } from "./deck-paths.ts";
+import { DekError } from "./error.ts";
+import { walkUp } from "./optional.ts";
+import { parseScript } from "./parse.ts";
+import { deckProjectRoot } from "./path.ts";
+import { readSourceIfExists, requireInside } from "./safe-fs.ts";
+import type { Deck, Section } from "./schema.ts";
+import { suggest } from "./suggest.ts";
+
+export type ProjectDeck = {
+  name: string;
+  dir: string;
+  scriptPath: string;
+  deck: Deck;
+};
+
+export type Project = {
+  root: string;
+  configPath: string;
+  decks: ProjectDeck[];
+  failed: Array<{ name: string; dir: string; scriptPath: string; error: DekError }>;
+};
+
+export type ResolvedDeck = {
+  project: Project;
+  deck: ProjectDeck;
+};
+
+/** The file's text, or nothing when there is no such file. */
+export function readTextIfExists(path: string): string | undefined {
+  return existsSync(path) ? readFileSync(path, "utf8") : undefined;
+}
+
+/**
+ * A file of the deck's, or nothing when there is none. It may be a symlink to elsewhere in the
+ * project, but not out of it: what a deck reads, a build publishes.
+ */
+export function readDeckFile(deckDir: string, path: string): string | undefined {
+  return readSourceIfExists(path, deckProjectRoot(deckDir));
+}
+
+export function resolveProject(startDir: string): Project {
+  const { root, configPath } = findRoot(resolve(startDir));
+  const { decks, failed } = loadDecks(root);
+  return { root, configPath, decks, failed };
+}
+
+export function locateDeck(root: string, dir: string): { name: string; dir: string } | undefined {
+  const name = deckNameFromDir(root, dir);
+  if (!name) {
+    return undefined;
+  }
+  return { name, dir: join(root, "decks", name) };
+}
+
+export function resolveDeck(dir: string): ResolvedDeck {
+  const { root, configPath } = findRoot(resolve(dir));
+  const located = locateDeck(root, dir);
+  if (!located) {
+    throw new DekError("not a deck directory", {
+      path: dir,
+      hint: "pass a deck name or run from a deck directory",
+    });
+  }
+  const loaded = readDeck(root, located.name);
+  if (!loaded.ok) {
+    throw loaded.error.error;
+  }
+  return {
+    project: { root, configPath, decks: [loaded.deck], failed: [] },
+    deck: loaded.deck,
+  };
+}
+
+export function asResolvedDeck(input: string | ResolvedDeck): ResolvedDeck {
+  return typeof input === "string" ? resolveDeck(input) : input;
+}
+
+export function requireSection(deck: ProjectDeck, slug: string): Section {
+  const section = deck.deck.sections.find((entry) => entry.slug === slug);
+  if (!section) {
+    const guess = suggest(
+      slug,
+      deck.deck.sections.map((entry) => entry.slug),
+    );
+    throw new DekError(`section "${slug}" not found`, {
+      path: deck.scriptPath,
+      hint: guess ? `did you mean \`${guess}\`? run \`dekc ls\` for every slide` : "run `dekc ls`",
+    });
+  }
+  return section;
+}
+
+export function listSlides(deckDir: string): { slug: string; path: string }[] {
+  return listSlideFiles(deckDir, ".html");
+}
+
+/** Files a slide may keep next to its HTML, moved and linted with it. */
+export const SLIDE_SIDECARS = [".css", ".ts"] as const;
+
+export type SlideSidecar = (typeof SLIDE_SIDECARS)[number];
+
+export function listSlideFiles(
+  deckDir: string,
+  ext: ".html" | ".js" | SlideSidecar,
+): { slug: string; path: string }[] {
+  const dir = deckPaths(deckDir).slides;
+  const root = deckProjectRoot(deckDir);
+  if (!existsSync(dir) || !statSync(requireInside(dir, root)).isDirectory()) {
+    return [];
+  }
+  return (
+    readdirSync(dir)
+      // A declaration file carries types for the editor, not a slide.
+      .filter((name) => name.endsWith(ext) && !name.endsWith(".d.ts"))
+      .sort((a, b) => a.localeCompare(b))
+      .flatMap((name) => {
+        const path = join(dir, name);
+        if (!statSync(requireInside(path, root)).isFile()) {
+          return [];
+        }
+        return [{ slug: name.slice(0, -ext.length), path }];
+      })
+  );
+}
+
+function findRoot(startDir: string): { root: string; configPath: string } {
+  const hit = walkUp(startDir, (dir) => {
+    const configPath = join(dir, "dek.toml");
+    if (existsSync(configPath) && statSync(configPath).isFile()) {
+      return { root: dir, configPath };
+    }
+  });
+  if (!hit) {
+    throw new DekError("not a dek project", {
+      path: startDir,
+      hint: "run `dekc init` to create one here, or cd into a project",
+    });
+  }
+  return hit;
+}
+
+function loadDecks(root: string): {
+  decks: ProjectDeck[];
+  failed: Project["failed"];
+} {
+  const decksDir = join(root, "decks");
+  if (!existsSync(decksDir)) {
+    return { decks: [], failed: [] };
+  }
+  if (!statSync(decksDir).isDirectory()) {
+    throw new DekError("decks is not a directory", { path: decksDir });
+  }
+
+  const decks: ProjectDeck[] = [];
+  const failed: Project["failed"] = [];
+
+  for (const entry of readdirSync(decksDir, { withFileTypes: true })
+    .filter((item) => item.isDirectory())
+    .sort((a, b) => a.name.localeCompare(b.name))) {
+    const loaded = readDeck(root, entry.name);
+    if (loaded.ok) {
+      decks.push(loaded.deck);
+    } else {
+      failed.push(loaded.error);
+    }
+  }
+
+  return { decks, failed };
+}
+
+function deckNameFromDir(root: string, dir: string): string | undefined {
+  const rel = relative(join(root, "decks"), resolve(dir));
+  if (!rel || rel === "." || rel === ".." || rel.startsWith(`..${sep}`)) {
+    return undefined;
+  }
+  const name = rel.split(sep)[0];
+  return name || undefined;
+}
+
+function readDeck(
+  root: string,
+  name: string,
+): { ok: true; deck: ProjectDeck } | { ok: false; error: Project["failed"][number] } {
+  const dir = join(root, "decks", name);
+  const scriptPath = deckPaths(dir).script;
+  let source: string | undefined;
+  try {
+    source = readDeckFile(dir, scriptPath);
+  } catch (error) {
+    return { ok: false, error: { name, dir, scriptPath, error: error as DekError } };
+  }
+  if (source === undefined) {
+    return {
+      ok: false,
+      error: {
+        name,
+        dir,
+        scriptPath,
+        error: new DekError(`deck "${name}" has no script.md`, { path: scriptPath }),
+      },
+    };
+  }
+  try {
+    return {
+      ok: true,
+      deck: {
+        name,
+        dir,
+        scriptPath,
+        deck: parseScript(source, scriptPath),
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: {
+        name,
+        dir,
+        scriptPath,
+        error:
+          error instanceof DekError ? error : new DekError(String(error), { path: scriptPath }),
+      },
+    };
+  }
+}

package/src/core/rumdl.ts

@@ -0,0 +1,99 @@
+import { dirname } from "node:path";
+import { type Diagnostic, errorDiagnostic } from "./diagnostic.ts";
+import { resolveBinFromAncestors } from "./optional.ts";
+import type { SarifLog } from "./sarif.ts";
+import { awaitPiped, workerCommand } from "./spawn.ts";
+
+export type RumdlRunner = (scriptPath: string) => Promise<string | null>;
+
+export function resolveRumdlBin(): string | undefined {
+  if (process.env.DEK_RUMDL) {
+    return process.env.DEK_RUMDL;
+  }
+  // Beside dek's own install, as `bun add -d rumdl` puts it, never the working directory's: a
+  // repository someone else wrote can commit a node_modules/.bin/rumdl for `dekc lint` to run.
+  // The PATH as it is now: Bun.which alone searches the one the process started with.
+  const onPath = Bun.which("rumdl", { PATH: process.env.PATH ?? "" });
+  return onPath ?? resolveBinFromAncestors("rumdl", import.meta.dir);
+}
+
+export async function defaultRumdlRunner(scriptPath: string): Promise<string | null> {
+  const bin = resolveRumdlBin();
+  if (!bin) {
+    return null;
+  }
+
+  try {
+    const args = ["check", scriptPath, "--output-format", "sarif"];
+    const cmd = workerCommand(bin, args);
+    const proc = Bun.spawn(cmd, {
+      cwd: dirname(scriptPath),
+      // The environment as it is now, like the PATH rumdl was found on; left out, Bun passes
+      // the one the process started with.
+      env: process.env,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const { stdout, exitCode } = await awaitPiped(proc);
+    if (exitCode === 2) {
+      return null;
+    }
+    return stdout;
+  } catch {
+    return null;
+  }
+}
+
+export async function rumdlDiagnostics(
+  scriptPath: string,
+  run: RumdlRunner = defaultRumdlRunner,
+): Promise<Diagnostic[]> {
+  return (await runRumdl(scriptPath, run)).diagnostics;
+}
+
+export async function runRumdl(
+  scriptPath: string,
+  run: RumdlRunner = defaultRumdlRunner,
+): Promise<{ diagnostics: Diagnostic[]; sarif?: SarifLog; skipped?: boolean }> {
+  const text = await run(scriptPath);
+  if (text === null) {
+    return { diagnostics: [], skipped: true };
+  }
+  return parseRumdlSarif(text);
+}
+
+function parseRumdlSarif(text: string | null): {
+  diagnostics: Diagnostic[];
+  sarif?: SarifLog;
+} {
+  if (!text?.trim()) {
+    return { diagnostics: [] };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { diagnostics: [] };
+  }
+
+  if (!parsed || typeof parsed !== "object" || !("runs" in parsed) || !Array.isArray(parsed.runs)) {
+    return { diagnostics: [] };
+  }
+
+  const sarif = parsed as SarifLog;
+  const diagnostics: Diagnostic[] = [];
+  for (const run of sarif.runs) {
+    for (const result of run.results ?? []) {
+      const loc = result.locations?.[0]?.physicalLocation;
+      diagnostics.push(
+        errorDiagnostic(result.ruleId, {
+          message: result.message.text,
+          ...(loc?.artifactLocation.uri ? { path: loc.artifactLocation.uri } : {}),
+          ...(loc?.region?.startLine !== undefined ? { line: loc.region.startLine } : {}),
+        }),
+      );
+    }
+  }
+  return { diagnostics, sarif };
+}

package/src/core/safe-fs.ts

@@ -0,0 +1,196 @@
+import { randomUUID } from "node:crypto";
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
+import { DekError } from "./error.ts";
+import { isInside } from "./path.ts";
+
+/**
+ * Where `path` really lives, when dek may follow it there, else undefined. A path with no link
+ * in it is taken as written. A link must stay inside `root`, keep its name's extension, and not
+ * lead into a hidden file or folder: a cloned repository can commit `theme.css -> ../../.env`
+ * or `.dek/schema.json -> ~/.zshrc`, and dek must neither publish the one nor overwrite the
+ * other. The part of `path` that does not exist yet is judged as written.
+ */
+export function followInside(path: string, root: string): string | undefined {
+  const wanted = resolve(path);
+  if (!isInside(wanted, root)) {
+    return undefined;
+  }
+  const realRoot = realpathSync(root);
+  const asWritten = join(realRoot, relative(resolve(root), wanted));
+  const real = realOf(wanted);
+  if (real === asWritten) {
+    return real;
+  }
+  const rel = relative(realRoot, real);
+  if (
+    !isInside(real, realRoot) ||
+    rel.split(sep).some((segment) => segment.startsWith(".")) ||
+    extname(real) !== extname(wanted)
+  ) {
+    return undefined;
+  }
+  return real;
+}
+
+/** The deepest part of `path` that exists, with its links resolved, then the rest as written. */
+function realOf(path: string): string {
+  const rest: string[] = [];
+  let head = path;
+  for (;;) {
+    try {
+      return join(realpathSync(head), ...rest);
+    } catch {
+      const up = dirname(head);
+      if (up === head) {
+        return path;
+      }
+      rest.unshift(basename(head));
+      head = up;
+    }
+  }
+}
+
+function refused(path: string, root: string): DekError {
+  return new DekError(`${relative(root, path) || path} leads outside the project`, {
+    path,
+    hint: "dek follows a symlink only to a file of the same kind inside the project and outside hidden folders; copy the file instead",
+  });
+}
+
+/** Like `followInside`, but a path dek may not follow is an error that says why. */
+export function requireInside(path: string, root: string): string {
+  const real = followInside(path, root);
+  if (real === undefined) {
+    throw refused(path, root);
+  }
+  return real;
+}
+
+/** A source file's text, or nothing when there is no such file; a link out is an error. */
+export function readSourceIfExists(path: string, root: string): string | undefined {
+  const real = requireInside(path, root);
+  return existsSync(real) ? readFileSync(real, "utf8") : undefined;
+}
+
+/** A folder dek writes into, made if missing; a link out of `root` on the way is an error. */
+export function outputDir(path: string, root: string): string {
+  const real = requireInside(path, root);
+  mkdirSync(real, { recursive: true });
+  // Making the folders may have followed a dangling link to a folder; look again.
+  if (followInside(path, root) !== real) {
+    throw refused(path, root);
+  }
+  return real;
+}
+
+/**
+ * Where a writer that opens `path` itself, such as Chromium or ffmpeg, may write it: the folders
+ * exist, and nothing at the path is a link it would follow. A link that stays inside comes back
+ * resolved; a dangling one, which would create its file wherever it points, is removed.
+ */
+export function outputPath(path: string, root: string): string {
+  outputDir(dirname(path), root);
+  const real = requireInside(path, root);
+  try {
+    if (lstatSync(real).isSymbolicLink()) {
+      unlinkSync(real);
+    }
+  } catch {
+    /* nothing there yet */
+  }
+  return real;
+}
+
+/**
+ * True when a cache entry dek wrote is there: a plain file. A link in its place is not dek's and
+ * is removed, so neither a build publishes what it points at nor a new entry is written through it.
+ */
+export function isCachedFile(path: string): boolean {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      unlinkSync(path);
+      return false;
+    }
+    return stat.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write `data` to `path` inside `root`: to a fresh file beside it, then renamed into place, so a
+ * reader never sees half a file and a link in the way is replaced rather than written through.
+ */
+export function writeInside(
+  path: string,
+  data: string | NodeJS.ArrayBufferView,
+  root: string,
+  options: { mode?: number } = {},
+): void {
+  replaceFile(outputPath(path, root), data, options);
+}
+
+/**
+ * Write `data` as a new file at `path`, in a folder already known to be inside the project: a
+ * link at `path`, such as one planted at a cache entry's predictable name, is replaced, never
+ * written through.
+ */
+export function replaceFile(
+  path: string,
+  data: string | NodeJS.ArrayBufferView,
+  options: { mode?: number } = {},
+): void {
+  const temp = join(dirname(path), `.${basename(path)}.${randomUUID().slice(0, 8)}.tmp`);
+  writeFileSync(temp, data, {
+    flag: "wx",
+    ...(options.mode !== undefined ? { mode: options.mode } : {}),
+  });
+  try {
+    renameSync(temp, path);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+}
+
+/** Remove every link directly in `dir`, a folder of dek's own output that a writer fills by name. */
+export function dropLinks(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isSymbolicLink()) {
+      unlinkSync(join(dir, entry.name));
+    }
+  }
+}
+
+/**
+ * Remove `path` inside `root`. A link is removed itself, never what it points at; a path whose
+ * folders lead out of `root` is refused, so no link can aim a delete at a file elsewhere.
+ */
+export function removeInside(
+  path: string,
+  root: string,
+  options: { recursive?: boolean } = {},
+): void {
+  let isLink = false;
+  try {
+    isLink = lstatSync(path).isSymbolicLink();
+  } catch {
+    return;
+  }
+  const parent = requireInside(dirname(path), root);
+  const target = isLink ? join(parent, basename(path)) : requireInside(path, root);
+  rmSync(target, { force: true, recursive: options.recursive === true });
+}

package/src/core/sarif.ts

@@ -0,0 +1,135 @@
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { type Diagnostic, type DiagnosticValue, RULES, type SkippedCheck } from "./diagnostic.ts";
+
+type SarifLevel = "error" | "warning" | "note" | "none";
+
+export type SarifLog = {
+  version: "2.1.0";
+  $schema: string;
+  runs: Array<{
+    tool: {
+      driver: {
+        name: string;
+        informationUri?: string;
+        rules?: Array<{ id: string; defaultConfiguration: { level: SarifLevel }; helpUri: string }>;
+      };
+    };
+    invocations?: Array<{
+      executionSuccessful: boolean;
+      toolExecutionNotifications?: Array<{
+        level: SarifLevel;
+        message: { text: string };
+        descriptor: { id: string };
+        properties?: { [key: string]: DiagnosticValue };
+      }>;
+    }>;
+    results: Array<{
+      ruleId: string;
+      level?: SarifLevel;
+      message: { text: string };
+      locations?: Array<{
+        physicalLocation: {
+          artifactLocation: { uri: string };
+          region?: { startLine: number; startColumn?: number };
+        };
+      }>;
+      properties?: { [key: string]: DiagnosticValue };
+    }>;
+  }>;
+};
+
+const RULES_URI = "https://hajimism.github.io/dek/reference/lint.html";
+
+/**
+ * dek's own diagnostics as one SARIF run. The message stays as written; the hint, slug, and data
+ * go in `properties`, the bag SARIF leaves to the tool. A check that did not run is a tool
+ * execution notification, so a log without results never reads as a pass for it.
+ */
+export function toSarif(
+  diagnostics: Diagnostic[],
+  options: { skipped?: SkippedCheck[] } = {},
+): SarifLog {
+  const skipped = options.skipped ?? [];
+  return {
+    version: "2.1.0",
+    $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "dek",
+            informationUri: "https://hajimism.github.io/dek/",
+            rules: Object.entries(RULES).map(([id, rule]) => ({
+              id,
+              defaultConfiguration: { level: rule.severity },
+              helpUri: RULES_URI,
+            })),
+          },
+        },
+        ...(skipped.length > 0
+          ? {
+              invocations: [
+                {
+                  executionSuccessful: true,
+                  toolExecutionNotifications: skipped.map((entry) => ({
+                    level: "warning" as const,
+                    message: { text: `${entry.check}: skipped (${entry.reason})` },
+                    descriptor: { id: `skipped/${entry.check}` },
+                    properties: {
+                      check: entry.check,
+                      ...(entry.hint === undefined ? {} : { hint: entry.hint }),
+                    },
+                  })),
+                },
+              ],
+            }
+          : {}),
+        results: diagnostics.map(sarifResult),
+      },
+    ],
+  };
+}
+
+function sarifResult(diagnostic: Diagnostic): SarifLog["runs"][number]["results"][number] {
+  const properties = {
+    ...(diagnostic.slug === undefined ? {} : { slug: diagnostic.slug }),
+    ...(diagnostic.hint === undefined ? {} : { hint: diagnostic.hint }),
+    ...(diagnostic.data === undefined ? {} : { data: diagnostic.data }),
+  };
+  return {
+    ruleId: diagnostic.id,
+    level: diagnostic.severity,
+    message: { text: diagnostic.message },
+    ...(diagnostic.path
+      ? {
+          locations: [
+            {
+              physicalLocation: {
+                artifactLocation: { uri: pathToFileURL(resolve(diagnostic.path)).href },
+                ...(diagnostic.line !== undefined
+                  ? {
+                      region: {
+                        startLine: diagnostic.line,
+                        ...(diagnostic.column === undefined
+                          ? {}
+                          : { startColumn: diagnostic.column }),
+                      },
+                    }
+                  : {}),
+              },
+            },
+          ],
+        }
+      : {}),
+    ...(Object.keys(properties).length > 0 ? { properties } : {}),
+  };
+}
+
+export function mergeSarif(dek: SarifLog, rumdl?: SarifLog): SarifLog {
+  return {
+    version: "2.1.0",
+    $schema: dek.$schema,
+    runs: [...dek.runs, ...(rumdl?.runs ?? [])],
+  };
+}