@hajimism/dek 0.3.2 → 0.4.0

package/src/core/annotation-rows.ts

@@ -3,6 +3,8 @@
 // edit, and the Markdown Copy writes. No DOM and no file system here, so all of it is decided by
 // these functions alone.
 
+import { isPlainWord } from "./escape.ts";
+
 /** A box on the slide, in logical pixels, from its top left. */
 export type Box = { x: number; y: number; width: number; height: number };
 
@@ -115,8 +117,10 @@ export function formatNotes(
     groups.set(key, [...(groups.get(key) ?? []), row]);
   }
 
+  // The deck's folder and the notes file are the project's text, which a clone brings along.
+  const folder = shown(deck, "<deck>");
   const lines = [
-    `## Notes on decks/${deck}`,
+    `## Notes on decks/${folder}`,
     "",
     "Boxes and points are in the slide's own pixels, from its top left.",
   ];
@@ -129,11 +133,11 @@ export function formatNotes(
     const title = slides[index]?.title;
     lines.push(
       "",
-      `### Slide ${index + 1} of ${slides.length}, ${first.slug}${title ? ` (${JSON.stringify(title)})` : ""}, ${beatLabel(first.step)}`,
+      `### Slide ${index + 1} of ${slides.length}, ${shown(first.slug, "<slug>")}${title ? ` (${JSON.stringify(title)})` : ""}, ${beatLabel(first.step)}`,
     );
     for (const row of group) {
       const where = (target: TargetRow): string =>
-        `${describe(target)} at decks/${deck}/slides/${row.slug}.html:${target.line}:${target.column} (${measure(target)})${target.found ? "" : ", as written before an edit; the line may have moved"}`;
+        `${describe(target)} at decks/${folder}/slides/${shown(row.slug, "<slug>")}.html:${target.line}:${target.column} (${measure(target)})${target.found ? "" : ", as written before an edit; the line may have moved"}`;
       lines.push("");
       if (row.targets.length === 1 && row.targets[0]) {
         lines.push(`${row.number}. ${where(row.targets[0])}`);
@@ -159,7 +163,15 @@ function beatLabel(step: string): string {
   if (step === "0") {
     return "as it arrives";
   }
-  return /^\d+$/.test(step) ? `at beat ${step}` : `at beat \`${step}\``;
+  if (/^\d+$/.test(step)) {
+    return `at beat ${step}`;
+  }
+  return isPlainWord(step) ? `at beat \`${step}\`` : "at beat <step>";
+}
+
+/** `word` as it is when it is plain, else `placeholder`: see `isPlainWord`. */
+function shown(word: string, placeholder: string): string {
+  return isPlainWord(word) ? word : placeholder;
 }
 
 function describe(target: TargetRow): string {

package/src/core/annotations.ts

@@ -9,6 +9,7 @@ import {
 } from "./annotation-rows.ts";
 import { deckPaths } from "./deck-paths.ts";
 import { DekError } from "./error.ts";
+import { shellName } from "./escape.ts";
 import { deckSlides, type WrittenElement, writtenElements } from "./html.ts";
 import { type ProjectDeck, readDeckFile } from "./resolve.ts";
 import { readSourceIfExists, writeInside } from "./safe-fs.ts";
@@ -306,11 +307,28 @@ function toRow(
     text: note.text,
     targets,
     changed,
-    shot: `dekc shot ${deck.name} ${note.slug} --step ${note.step}`,
+    shot: shotCommand(deck.name, note.slug, note.step),
     createdAt: note.createdAt,
   };
 }
 
+/**
+ * The shot of a note's slide at its beat, as a command to paste. Each name is the file's, so one
+ * that no word holds alike in every shell is a placeholder, and one that starts with a dash goes
+ * after `--`, where it reads as no flag.
+ */
+function shotCommand(deck: string, slug: string, step: string): string {
+  const [name, slide, beat] = [
+    shellName(deck) ?? "<deck>",
+    shellName(slug) ?? "<slug>",
+    shellName(step) ?? "<step>",
+  ];
+  const flag = step.startsWith("-") ? `--step=${beat}` : `--step ${beat}`;
+  return deck.startsWith("-") || slug.startsWith("-")
+    ? `dekc shot ${flag} -- ${name} ${slide}`
+    : `dekc shot ${name} ${slide} ${flag}`;
+}
+
 /** A hash of each of the slide's own files there is, by its extension. */
 function slideFileHashes(deck: ProjectDeck, slug: string): Record<string, string> {
   const paths = deckPaths(deck.dir);

package/src/core/config-keys.ts

@@ -1,4 +1,4 @@
-import { DekToml, Voice } from "./config.ts";
+import { DekToml, Pack, Voice } from "./config.ts";
 import { splitLines } from "./lines.ts";
 import { readFrontmatterYaml } from "./parse.ts";
 import { Frontmatter } from "./schema.ts";
@@ -10,12 +10,16 @@ import { unrecognizedKeys } from "./zod.ts";
 export type UnknownKey = { key: string; line: number; suggestion?: string };
 
 /** dek.toml's schema, but a key it does not read is an issue; `refs` still takes any key. */
-const StrictDekToml = DekToml.extend({ voice: Voice.strict().optional() }).strict();
+const StrictDekToml = DekToml.extend({
+  voice: Voice.strict().optional(),
+  pack: Pack.strict().optional(),
+}).strict();
 
 /** Every key dek.toml may hold, as dotted paths. */
 const DEK_TOML_KEYS: readonly string[] = [
   ...Object.keys(DekToml.shape),
   ...Object.keys(Voice.shape).map((key) => `voice.${key}`),
+  ...Object.keys(Pack.shape).map((key) => `pack.${key}`),
 ];
 
 export const FRONTMATTER_KEYS: readonly string[] = Object.keys(Frontmatter.shape);

package/src/core/config.ts

@@ -1,8 +1,19 @@
-import { existsSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
 import { z } from "zod";
+import { DekError } from "./error.ts";
+import { shellQuote } from "./escape.ts";
+import { isPackLicense, PACK_LICENSES, type PackLicense } from "./licenses.ts";
 import { parsePublicUrl } from "./ogp.ts";
-import { isPinnedRev, isPlainRefName } from "./ref-name.ts";
+import {
+  isPinFor,
+  isPlainRefName,
+  packFile,
+  parseRefSource,
+  REF_DECK_NAME_RULE,
+} from "./ref-name.ts";
+import { readSourceIfExists } from "./safe-fs.ts";
 import { DeckSettings } from "./schema.ts";
+import { scanTomlKeys } from "./toml-keys.ts";
 import { parseTomlWith } from "./zod.ts";
 
 export const Voice = z.object({
@@ -11,6 +22,15 @@ export const Voice = z.object({
   speed: z.number().optional(),
 });
 
+export const Pack = z.object({
+  license: z
+    .string()
+    .refine(isPackLicense, {
+      message: `write ${PACK_LICENSES.join(" or ")}, or delete the line and put a LICENSE at the project root`,
+    })
+    .optional(),
+});
+
 export const DekToml = z.object({
   url: z
     .string()
@@ -21,24 +41,72 @@ export const DekToml = z.object({
     .optional(),
   ...DeckSettings.partial().shape,
   voice: Voice.optional(),
+  pack: Pack.optional(),
+  // Each key is checked before its value, so a key that names no ref is never repeated.
   refs: z
-    .record(z.string(), z.string())
+    .record(z.string(), z.unknown())
     .superRefine((refs, ctx) => {
       for (const [name, rev] of Object.entries(refs)) {
         if (!isPlainRefName(name)) {
-          ctx.addIssue({ code: "custom", path: [name], message: "a ref is named owner/repo/deck" });
-        } else if (!isPinnedRev(rev)) {
           ctx.addIssue({
             code: "custom",
-            path: [name],
-            message: `pin a ref to a 40-character commit sha; run \`dekc ref ${name}\` to pin one`,
+            path: [],
+            message: `${REFUSED_REF_KEY}; ${REFUSED_REF_HINT}`,
           });
+          continue;
+        }
+        const source = parseRefSource(name);
+        if (typeof rev === "string" && isPinFor(source, rev)) {
+          continue;
         }
+        ctx.addIssue({
+          code: "custom",
+          path: [name],
+          message:
+            source.kind === "file"
+              ? `pin a pack's ref to the 64-character sha256 of its files; run \`dekc ref ${shellQuote(packFile(source.deck))}\` to pin one`
+              : `pin a ref to a 40-character commit sha; run \`dekc ref ${shellQuote(name)}\` to pin one`,
+        });
       }
     })
+    .transform((refs) => refs as Record<string, string>)
     .optional(),
 });
 
+const REFUSED_REF_KEY = "a key in [refs] names no ref";
+
+const REFUSED_REF_HINT = `delete that line, and for a pack its packs/<deck>.tgz and refs/file/<deck>, then pin the deck again under a name a ref can carry: a ref is named owner/repo/deck, or file/<deck> for a pack, and ${REF_DECK_NAME_RULE}`;
+
+/**
+ * The first key in [refs] that names no ref, by its line when the file says it plainly. Such a
+ * key may be someone else's text, from a project cloned or a pack added before dek checked it, so
+ * the error points at it and never repeats it.
+ */
+function refusedRefKey(source: string): { line?: number } | undefined {
+  let parsed: unknown;
+  try {
+    parsed = Bun.TOML.parse(source);
+  } catch {
+    return undefined;
+  }
+  const refs = (parsed as { refs?: unknown } | null)?.refs;
+  const name =
+    refs !== null && typeof refs === "object"
+      ? Object.keys(refs).find((key) => !isPlainRefName(key))
+      : undefined;
+  if (name === undefined) {
+    return undefined;
+  }
+  const written = scanTomlKeys(source).filter(
+    (entry) => entry.path[0] === "refs" && entry.path.length === 2,
+  );
+  // A key written with escapes reads differently on its line; any key there that names no ref is it.
+  const entry =
+    written.find((key) => key.path[1] === name) ??
+    written.find((key) => !isPlainRefName(key.path[1] ?? ""));
+  return entry === undefined ? {} : { line: entry.line };
+}
+
 type VoiceDefaults = {
   engine: string;
   speaker: string;
@@ -54,11 +122,17 @@ export type DekConfig = {
    */
   seed?: Partial<DeckSettings>;
   voice?: VoiceDefaults;
-  /** `[refs]`: each ref name and the commit it is pinned to. */
+  /** `[pack]`: what `dekc pack` hands a deck over with, the license it carries. */
+  pack?: { license?: PackLicense };
+  /** `[refs]`: each ref name and what it is pinned to: a commit, or a pack's digest. */
   refs?: Record<string, string>;
 };
 
 export function parseDekToml(source: string, path?: string): DekConfig {
+  const refused = refusedRefKey(source);
+  if (refused) {
+    throw new DekError(REFUSED_REF_KEY, { path, ...refused, hint: REFUSED_REF_HINT });
+  }
   const data = parseTomlWith(DekToml, source, {
     label: "dek.toml",
     anchor: "dek-toml",
@@ -77,13 +151,15 @@ export function parseDekToml(source: string, path?: string): DekConfig {
     ...(url ? { url } : {}),
     ...(Object.keys(seed).length > 0 ? { seed } : {}),
     ...(voice ? { voice } : {}),
+    ...(data.pack
+      ? { pack: data.pack.license ? { license: data.pack.license as PackLicense } : {} }
+      : {}),
     ...(data.refs && Object.keys(data.refs).length > 0 ? { refs: data.refs } : {}),
   };
 }
 
+/** The project's dek.toml, which sits at its root; a link out of the project is an error. */
 export function loadConfig(configPath: string): DekConfig {
-  if (!existsSync(configPath)) {
-    return {};
-  }
-  return parseDekToml(readFileSync(configPath, "utf8"), configPath);
+  const source = readSourceIfExists(configPath, dirname(configPath));
+  return source === undefined ? {} : parseDekToml(source, configPath);
 }

package/src/core/diagnostic.ts

@@ -17,7 +17,9 @@ export type Scope = "project" | "deck" | "slide";
  * (DEK044), an empty heading (DEK024), which a slide script may fill, and a step bound by
  * position where the beat has an id (DEK025), which is right until a beat is inserted, and a
  * style several slides repeat (DEK026), which works but belongs in the theme. Text under
- * aria-hidden (DEK029) is right on a sample the talk shows as unreadable.
+ * aria-hidden (DEK029) is right on a sample the talk shows as unreadable. A line break that
+ * reads wrong (DEK035) is fixed by a choice of words or of where to break, which is the author's,
+ * and an edge a few pixels off (DEK036) can be meant, as in a picture of something out of line.
  */
 export const RULES = {
   DEK001: { severity: "error", scopes: ["slide"] },
@@ -54,6 +56,8 @@ export const RULES = {
   DEK032: { severity: "error", scopes: ["slide"] },
   DEK033: { severity: "error", scopes: ["slide"] },
   DEK034: { severity: "error", scopes: ["slide"] },
+  DEK035: { severity: "warning", scopes: ["slide"] },
+  DEK036: { severity: "warning", scopes: ["slide"] },
   DEK040: { severity: "warning", scopes: ["slide"] },
   DEK041: { severity: "warning", scopes: ["deck"] },
   DEK042: { severity: "warning", scopes: ["slide"] },

package/src/core/escape.ts

@@ -14,3 +14,46 @@ export function escapeAttr(text: string): string {
 export function escapeRegExp(text: string): string {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+/**
+ * A word no shell reads anything in: letters, marks, and digits of any script, and `@%+=:,./_-`,
+ * but not first an `=`, which zsh reads as the path of the program named after it.
+ */
+const PLAIN_WORD = /^[\p{L}\p{M}\p{N}@%+:,./_-][\p{L}\p{M}\p{N}@%+=:,./_-]*$/u;
+
+/** Whether `word` is plain: dek prints it as it is, in a command or in prose. */
+export function isPlainWord(word: string): boolean {
+  return PLAIN_WORD.test(word);
+}
+
+/** A backtick, as a shell word that holds none: `printf` writes it from its octal code. */
+const BACKTICK_WORD = `"$(printf '\\140')"`;
+
+/**
+ * `word` as one shell word, as dek writes it in a command to paste: as it is when it is plain,
+ * else single-quoted. A command is printed inside a code span, which a backtick would close, so a
+ * backtick is written as `printf` of its code, between quoted runs. The quoting is a POSIX shell's,
+ * as sh, bash, and zsh read it: fish reads a backslash in single quotes apart, and PowerShell and
+ * cmd quote otherwise. A name from a file goes through `shellName` instead.
+ */
+export function shellQuote(word: string): string {
+  if (isPlainWord(word)) {
+    return word;
+  }
+  const quoted = word
+    .split("`")
+    .map((run) => (run === "" ? "" : `'${run.replaceAll("'", "'\\''")}'`))
+    .join(BACKTICK_WORD);
+  return quoted === "" ? "''" : quoted;
+}
+
+/**
+ * A name from a file, such as a deck's folder or a slide's file, as a word in a command dek
+ * suggests, or nothing when it has none: fish reads a quote or a backslash in it apart from a
+ * POSIX shell, and a control character would start a line of its own. The command then shows a
+ * placeholder, such as `<deck>`, and says where the name is.
+ */
+export function shellName(name: string): string | undefined {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: a control in a name is the problem.
+  return /['\\\x00-\x1f\x7f-\x9f]/.test(name) ? undefined : shellQuote(name);
+}