@hajimism/dek 0.3.3 → 0.5.0

package/src/core/attribute-value.ts

@@ -0,0 +1,188 @@
+/**
+ * An attribute's value as the browser reads it. Bun's HTMLRewriter gives each value as written,
+ * character references and all, so `assets/Q&A.png` would name a file the page never loads.
+ * Every value lint or the build reads off the rewriter goes through here first; a value written
+ * back into the markup is written from the one as written, never from this.
+ */
+import { LEGACY_REFERENCES, NAMED_REFERENCES } from "./html-entities.ts";
+
+/** A decoded value, and where in the value as written each of its UTF-16 units comes from. */
+export type DecodedAttribute = {
+  value: string;
+  /** The offset in the written value of the unit at `index`; `value.length` maps past the end. */
+  writtenAt(index: number): number;
+};
+
+/** The value of `name` on a rewriter's element as the browser reads it, or null when absent. */
+export function attributeOf(
+  element: { getAttribute(name: string): string | null },
+  name: string,
+): string | null {
+  const written = element.getAttribute(name);
+  return written === null ? null : decodeAttribute(written).value;
+}
+
+/**
+ * Whether `char` is ASCII whitespace, the only whitespace HTML splits a list of tokens on or trims
+ * a value of. A no-break space, written as itself or as ` `, is part of the value.
+ */
+export function isAsciiWhitespace(char: string | undefined): boolean {
+  return char === " " || char === "\t" || char === "\n" || char === "\f" || char === "\r";
+}
+
+/** The tokens of a value such as `class` or `role`, split on ASCII whitespace as HTML splits it. */
+export function attributeTokens(value: string | null | undefined): string[] {
+  return (value ?? "").split(/[\t\n\f\r ]+/).filter(Boolean);
+}
+
+/** `value` without the ASCII whitespace at its ends, as HTML trims a keyword or a name. */
+export function trimAsciiWhitespace(value: string): string {
+  return value.replace(/^[\t\n\f\r ]+|[\t\n\f\r ]+$/g, "");
+}
+
+/**
+ * `written` read the way the HTML standard reads an attribute value: every numeric and named
+ * character reference decoded, a carriage return read as a line feed, and a NUL as U+FFFD. A
+ * name the standard allows without its `;` stays as written when a letter, a digit, or `=`
+ * follows it, so the `&copy` of `?a=1&copy=2` is left alone, as the browser leaves it.
+ */
+export function decodeAttribute(written: string): DecodedAttribute {
+  // Each replacement, where it is in the decoded value and where in the written one, in order.
+  const spans: Array<{ start: number; end: number; writtenStart: number; writtenEnd: number }> = [];
+  let shift = 0;
+  const value = written.replace(
+    REFERENCE_RE,
+    (match: string, hex?: string, decimal?: string, name?: string, semicolon?: string, at = 0) => {
+      const text = replacement(written, match, at, { hex, decimal, name, semicolon });
+      if (text !== match) {
+        const start = at - shift;
+        spans.push({
+          start,
+          end: start + text.length,
+          writtenStart: at,
+          writtenEnd: at + match.length,
+        });
+        shift += match.length - text.length;
+      }
+      return text;
+    },
+  );
+  return {
+    value,
+    writtenAt(index) {
+      let offset = index;
+      for (const span of spans) {
+        if (index < span.start) {
+          break;
+        }
+        if (index < span.end) {
+          return span.writtenStart;
+        }
+        offset = span.writtenEnd + (index - span.end);
+      }
+      return offset;
+    },
+  };
+}
+
+/**
+ * A character reference, with its parts as groups; a carriage return, which the input stream reads
+ * as a line feed; or a NUL, which the tokenizer reads as U+FFFD in a value.
+ */
+const REFERENCE_RE = /&(?:#(?:[xX]([0-9a-fA-F]+)|([0-9]+));?|([A-Za-z0-9]+)(;?))|\r\n?|\0/g;
+
+/** What one match of REFERENCE_RE reads as: itself, when the standard leaves it as written. */
+function replacement(
+  written: string,
+  match: string,
+  at: number,
+  parts: { hex?: string; decimal?: string; name?: string; semicolon?: string },
+): string {
+  if (match === "\0") {
+    return "\uFFFD";
+  }
+  if (match.startsWith("\r")) {
+    return "\n";
+  }
+  if (parts.hex !== undefined || parts.decimal !== undefined) {
+    return numericReference(
+      parts.hex === undefined
+        ? Number.parseInt(parts.decimal ?? "", 10)
+        : Number.parseInt(parts.hex, 16),
+    );
+  }
+  const name = parts.name ?? "";
+  if (parts.semicolon) {
+    return namedReferences().get(name) ?? match;
+  }
+  // The browser takes the longest name it knows. A legacy name shorter than the run of letters
+  // and digits is followed by one of them, which keeps it as written, so only the whole run can.
+  if (legacyReferences().has(name) && written[at + match.length] !== "=") {
+    return namedReferences().get(name) ?? match;
+  }
+  return match;
+}
+
+/**
+ * The character a numeric reference stands for: U+FFFD for NUL, a surrogate, or a number past
+ * Unicode, and for 0x80 to 0x9F the Windows-1252 character the standard reads it as.
+ */
+function numericReference(number: number): string {
+  if (number === 0 || number > 0x10ffff || (number >= 0xd800 && number <= 0xdfff)) {
+    return "\uFFFD";
+  }
+  return String.fromCodePoint(C1_REPLACEMENTS.get(number) ?? number);
+}
+
+/** The HTML standard's table for a numeric reference to a C1 control. */
+const C1_REPLACEMENTS: ReadonlyMap<number, number> = new Map([
+  [0x80, 0x20ac],
+  [0x82, 0x201a],
+  [0x83, 0x0192],
+  [0x84, 0x201e],
+  [0x85, 0x2026],
+  [0x86, 0x2020],
+  [0x87, 0x2021],
+  [0x88, 0x02c6],
+  [0x89, 0x2030],
+  [0x8a, 0x0160],
+  [0x8b, 0x2039],
+  [0x8c, 0x0152],
+  [0x8e, 0x017d],
+  [0x91, 0x2018],
+  [0x92, 0x2019],
+  [0x93, 0x201c],
+  [0x94, 0x201d],
+  [0x95, 0x2022],
+  [0x96, 0x2013],
+  [0x97, 0x2014],
+  [0x98, 0x02dc],
+  [0x99, 0x2122],
+  [0x9a, 0x0161],
+  [0x9b, 0x203a],
+  [0x9c, 0x0153],
+  [0x9e, 0x017e],
+  [0x9f, 0x0178],
+]);
+
+let named: Map<string, string> | undefined;
+let legacy: Set<string> | undefined;
+
+/** Each named reference, without its `;`, and the characters it stands for; read once. */
+function namedReferences(): Map<string, string> {
+  named ??= new Map(
+    NAMED_REFERENCES.split(" ").map((entry) => {
+      const [name = "", points = ""] = entry.split(":");
+      return [
+        name,
+        String.fromCodePoint(...points.split("+").map((point) => Number.parseInt(point, 16))),
+      ];
+    }),
+  );
+  return named;
+}
+
+function legacyReferences(): Set<string> {
+  legacy ??= new Set(LEGACY_REFERENCES.split(" "));
+  return legacy;
+}

package/src/core/build.ts

@@ -1,11 +1,11 @@
-import { copyFileSync } from "node:fs";
+import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { loadConfig } from "./config.ts";
 import { renderDeckDocument } from "./document.ts";
 import { type DistOptions, distFile } from "./path.ts";
 import type { PlaywrightRunner } from "./playwright.ts";
 import { asResolvedDeck, type ResolvedDeck } from "./resolve.ts";
-import { outputPath, removeInside, writeInside } from "./safe-fs.ts";
+import { removeInside, writeInside } from "./safe-fs.ts";
 import { coverShot } from "./shot/still.ts";
 import { logicalSize } from "./size.ts";
 
@@ -43,7 +43,7 @@ export async function buildDeck(
   const shot = baseUrl ? await coverShot(deck, options.runner) : undefined;
 
   if (shot) {
-    copyFileSync(shot, outputPath(imagePath, project.root));
+    writeInside(imagePath, readFileSync(shot), project.root);
   } else {
     // An image from an earlier build would outlive the tag that pointed at it.
     removeInside(imagePath, project.root);

package/src/core/config.ts

@@ -1,9 +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 { isPinFor, isPlainRefName, packFile, parseRefSource } 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({
@@ -32,20 +42,21 @@ export const DekToml = z.object({
   ...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, or file/<deck> for a pack",
+            path: [],
+            message: `${REFUSED_REF_KEY}; ${REFUSED_REF_HINT}`,
           });
           continue;
         }
         const source = parseRefSource(name);
-        if (isPinFor(source, rev)) {
+        if (typeof rev === "string" && isPinFor(source, rev)) {
           continue;
         }
         ctx.addIssue({
@@ -53,14 +64,49 @@ export const DekToml = z.object({
           path: [name],
           message:
             source.kind === "file"
-              ? `pin a pack's ref to the 64-character sha256 of its files; run \`dekc ref ${packFile(source.deck)}\` to pin one`
-              : `pin a ref to a 40-character commit sha; run \`dekc ref ${name}\` to pin one`,
+              ? `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;
@@ -83,6 +129,10 @@ export type DekConfig = {
 };
 
 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",
@@ -108,9 +158,8 @@ export function parseDekToml(source: string, path?: string): DekConfig {
   };
 }
 
+/** 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/css-scan.ts

@@ -1,9 +1,52 @@
 /**
- * The one way dek steps through CSS text: strings and comments are opaque, and a newline ends an
- * unclosed string, as the CSS tokenizer reads it. Every scanner in css.ts and lint/tokens.ts is built on
- * these, so none of them can disagree about where a string or a block ends.
+ * The one way dek steps through CSS text, as the CSS tokenizer reads it: strings, comments, and
+ * an unquoted `url()` are opaque, CR, FF, and CRLF are newlines as LF is, and a newline ends an
+ * unclosed string. Every scanner in css.ts, css-transform.ts, and theme-excerpt.ts is built on
+ * these, so none of them can disagree about where a string or a block ends. Nothing is rewritten
+ * before it is read, so every index still points into the text as written.
  */
 
+/** A newline as CSS preprocesses its input: LF, CR, or FF; CRLF is one, read at its CR. */
+function isNewline(ch: string | undefined): boolean {
+  return ch === "\n" || ch === "\r" || ch === "\f";
+}
+
+function isWhitespace(ch: string | undefined): boolean {
+  return ch === " " || ch === "\t" || isNewline(ch);
+}
+
+/** The index just past the whitespace at `i`, taking CRLF whole. */
+function whitespaceEnd(source: string, i: number, end: number): number {
+  return Math.min(source[i] === "\r" && source[i + 1] === "\n" ? i + 2 : i + 1, end);
+}
+
+function skipWhitespace(source: string, i: number, end: number): number {
+  let j = i;
+  while (j < end && isWhitespace(source[j])) {
+    j++;
+  }
+  return j;
+}
+
+/** Whether a `\` at `i` escapes what follows: anything but a newline, the end included. */
+function startsEscape(source: string, i: number, end: number): boolean {
+  return source[i] === "\\" && (i + 1 >= end || !isNewline(source[i + 1]));
+}
+
+const HEX_RE = /[0-9a-fA-F]/;
+
+/** The index just past the escape at `i`: one code point, or up to six hex digits and a space. */
+function consumeEscape(source: string, i: number, end: number): number {
+  let j = i + 1;
+  if (j >= end || !HEX_RE.test(source[j] ?? "")) {
+    return Math.min(j + 1, end);
+  }
+  while (j < end && j < i + 7 && HEX_RE.test(source[j] ?? "")) {
+    j++;
+  }
+  return j < end && isWhitespace(source[j]) ? whitespaceEnd(source, j, end) : j;
+}
+
 /** The index just past the string that opens at `start`, or the newline that cuts it short. */
 export function consumeString(source: string, start: number, end = source.length): number {
   const quote = source[start];
@@ -11,13 +54,16 @@ export function consumeString(source: string, start: number, end = source.length
   while (i < end) {
     const ch = source[i];
     if (ch === "\\") {
-      i += 2;
+      // A `\` before a newline carries the string on to the next line.
+      i = startsEscape(source, i, end)
+        ? consumeEscape(source, i, end)
+        : whitespaceEnd(source, i + 1, end);
       continue;
     }
     if (ch === quote) {
       return i + 1;
     }
-    if (ch === "\n") {
+    if (isNewline(ch)) {
       return i;
     }
     i++;
@@ -35,27 +81,122 @@ function isCommentStart(source: string, i: number): boolean {
   return source[i] === "/" && source[i + 1] === "*";
 }
 
+const NAME_RE = /[-\w\u0080-\uffff]/;
+
+/** A code point of a name: a letter, a digit, `-`, `_`, non-ASCII, or NUL, which CSS reads as U+FFFD. */
+function isNameChar(ch: string | undefined): boolean {
+  return ch === "\0" || NAME_RE.test(ch ?? "");
+}
+
+/** The index just past the name at `i`: letters, digits, `-`, `_`, non-ASCII, and escapes. */
+function consumeName(source: string, i: number, end: number): number {
+  let j = i;
+  while (j < end) {
+    if (startsEscape(source, j, end)) {
+      j = consumeEscape(source, j, end);
+    } else if (isNameChar(source[j])) {
+      j++;
+    } else {
+      break;
+    }
+  }
+  return j;
+}
+
+/** Whether a name reads `url` once its escapes are resolved, as `URL` or `u\72l` does. */
+function isUrlName(name: string): boolean {
+  const read = name.includes("\\")
+    ? name.replace(/\\(?:([0-9a-fA-F]{1,6})(?:\r\n|[ \t\n\r\f])?|([\s\S]))/g, (_, hex, ch) => {
+        const code = hex === undefined ? -1 : Number.parseInt(hex, 16);
+        return code < 0 ? ch : code > 0x10ffff ? "\ufffd" : String.fromCodePoint(code);
+      })
+    : name;
+  return read.toLowerCase() === "url";
+}
+
+function isNonPrintable(ch: string): boolean {
+  const code = ch.charCodeAt(0);
+  // NUL is no control character here: CSS reads it as U+FFFD.
+  return (
+    (code >= 0x01 && code <= 0x08) ||
+    code === 0x0b ||
+    (code >= 0x0e && code <= 0x1f) ||
+    code === 0x7f
+  );
+}
+
 /**
- * The first index from `start` whose character is one of `stops` outside strings, comments, and
- * `()`/`[]`; `end` when there is none. An opening brace counts only when `{` is a stop.
+ * The index just past an unquoted `url()` whose address starts at `start`, after its `(`; none
+ * when the address is quoted, which makes it a function holding a string. A broken one, with a
+ * space, a quote, a `(`, or a control character in its address, still runs to its `)`.
  */
-export function scanTopLevel(source: string, start: number, end: number, stops: string): number {
-  let depth = 0;
-  let i = start;
+function consumeUrl(source: string, start: number, end: number): number | undefined {
+  let i = skipWhitespace(source, start, end);
+  if (i < end && (source[i] === '"' || source[i] === "'")) {
+    return undefined;
+  }
+  let broken = false;
   while (i < end) {
     const ch = source[i] ?? "";
-    if (ch === '"' || ch === "'") {
-      i = consumeString(source, i, end);
-      continue;
+    if (ch === ")") {
+      return i + 1;
     }
-    if (isCommentStart(source, i)) {
-      i = consumeComment(source, i, end);
+    if (startsEscape(source, i, end)) {
+      i = consumeEscape(source, i, end);
       continue;
     }
-    if (ch === "\\") {
-      i += 2;
+    if (!broken && isWhitespace(ch)) {
+      i = skipWhitespace(source, i, end);
+      broken = i < end && source[i] !== ")";
       continue;
     }
+    broken ||= ch === '"' || ch === "'" || ch === "(" || ch === "\\" || isNonPrintable(ch);
+    i++;
+  }
+  return end;
+}
+
+/**
+ * The index just past the token that starts at `i`, as far as dek tells tokens apart: a string,
+ * a comment, an unquoted `url()`, or a name with its escapes, so the `url` of `myurl(` or
+ * `10url(` opens nothing. Any other code point is a token of its own. A `\` before a newline,
+ * which escapes nothing, takes the newline with it, so no rewrite can make an escape of the two.
+ */
+export function consumeToken(source: string, i: number, end = source.length): number {
+  const ch = source[i];
+  if (ch === '"' || ch === "'") {
+    return consumeString(source, i, end);
+  }
+  if (isCommentStart(source, i)) {
+    return consumeComment(source, i, end);
+  }
+  if (ch === "\\" && !startsEscape(source, i, end)) {
+    return whitespaceEnd(source, i + 1, end);
+  }
+  if (!startsEscape(source, i, end) && !isNameChar(ch)) {
+    return i + 1;
+  }
+  const nameEnd = consumeName(source, i, end);
+  // `#url(` is a hash and `@url(` an at-rule's name, not a url().
+  const url =
+    nameEnd < end &&
+    source[nameEnd] === "(" &&
+    source[i - 1] !== "#" &&
+    source[i - 1] !== "@" &&
+    isUrlName(source.slice(i, nameEnd));
+  return (url && consumeUrl(source, nameEnd + 1, end)) || nameEnd;
+}
+
+/**
+ * The first index from `start` whose character is one of `stops` outside strings, comments,
+ * `url()`s, and `()`/`[]`; `end` when there is none. An opening brace counts only when `{` is a
+ * stop. Stops are punctuation, which no name holds.
+ */
+export function scanTopLevel(source: string, start: number, end: number, stops: string): number {
+  let depth = 0;
+  let i = start;
+  while (i < end) {
+    const ch = source[i] ?? "";
     if (depth === 0 && stops.includes(ch)) {
       return i;
     }
@@ -64,7 +205,7 @@ export function scanTopLevel(source: string, start: number, end: number, stops:
     } else if ((ch === ")" || ch === "]") && depth > 0) {
       depth--;
     }
-    i++;
+    i = consumeToken(source, i, end);
   }
   return end;
 }
@@ -88,17 +229,17 @@ export function matchBrace(source: string, open: number, end = source.length): n
   return end;
 }
 
-/** The text with each comment removed, strings kept byte for byte. */
+/** The text with each comment removed, strings and `url()`s kept byte for byte. */
 export function stripComments(source: string): string {
   return replaceOpaque(source, { comment: () => "" });
 }
 
 /**
  * The text with each string and comment blanked to spaces, newlines kept, so only CSS syntax is
- * left and every offset still points where it did.
+ * left and every offset still points where it did. A `url()` is left as written.
  */
 export function blankStringsAndComments(source: string): string {
-  const blank = (text: string) => text.replace(/[^\n]/g, " ");
+  const blank = (text: string) => text.replace(/[^\n\r\f]/g, " ");
   return replaceOpaque(source, { comment: blank, string: blank });
 }
 
@@ -110,26 +251,19 @@ function replaceOpaque(
   let from = 0;
   let i = 0;
   while (i < source.length) {
+    const next = consumeToken(source, i);
     const ch = source[i];
-    if (ch === '"' || ch === "'") {
-      const end = consumeString(source, i);
-      if (replace.string) {
-        out += source.slice(from, i) + replace.string(source.slice(i, end));
-        from = end;
-      }
-      i = end;
-      continue;
-    }
-    if (isCommentStart(source, i)) {
-      const end = consumeComment(source, i);
-      if (replace.comment) {
-        out += source.slice(from, i) + replace.comment(source.slice(i, end));
-        from = end;
-      }
-      i = end;
-      continue;
+    const replacer =
+      ch === '"' || ch === "'"
+        ? replace.string
+        : isCommentStart(source, i)
+          ? replace.comment
+          : undefined;
+    if (replacer) {
+      out += source.slice(from, i) + replacer(source.slice(i, next));
+      from = next;
     }
-    i += ch === "\\" ? 2 : 1;
+    i = next;
   }
   return out + source.slice(from);
 }