@hajimism/dek 0.3.3 → 0.5.0

package/src/core/css-transform.ts

@@ -1,5 +1,5 @@
 import { outermostStyleRules, type Stylesheet, splitSelectorList, startsAtSlide } from "./css.ts";
-import { consumeComment, consumeString, cssIdents } from "./css-scan.ts";
+import { consumeComment, consumeToken, cssIdents } from "./css-scan.ts";
 
 /** Text to put in place of `[start, end)` of the stylesheet as it was read. */
 type CssEdit = { start: number; end: number; text: string };
@@ -108,32 +108,78 @@ export function replaceUrls(replace: (value: string) => string | undefined): Css
 
 /** Whitespace as CSS defines it. U+3000 and NBSP are content, not whitespace. */
 const CSS_WHITESPACE = new Set([" ", "\t", "\n", "\r", "\f"]);
+const CSS_NEWLINES = new Set(["\n", "\r", "\f"]);
+
+/** A token that runs on into the next with nothing between: a name, a number, or `#@.+/`. */
+const RUNS_ON_RE = /^[-\w\u0080-\uffff\0\\#@.+/]/;
+/** What such a token runs on into: a name, a number, `(`, `%`, or the `*` that opens a comment. */
+const RUNS_INTO_RE = /^[-\w\u0080-\uffff\0\\.+(%*]/;
 
 /**
- * Drops comments and collapses whitespace to one space, leaving strings byte for byte, so
- * `content: "a　b"` or `"  "` renders in the build as it does on the dev server.
+ * Whether the token `last` and the one that starts with `next` would read as one with nothing
+ * between them: `x` and `url(` as `xurl(`, `/` and `*` as a comment, or `--` and `>`, `<` and
+ * `!`, `!` and `--` as the `-->` and `<!--` a stylesheet skips.
+ */
+function runTogether(last: string, next: string): boolean {
+  return (
+    (RUNS_ON_RE.test(last) && RUNS_INTO_RE.test(next)) ||
+    (last.endsWith("--") && next === ">") ||
+    (last === "<" && next === "!") ||
+    (last === "!" && next === "-")
+  );
+}
+
+/** A hex escape at the end of a token, which takes one whitespace after it as its own. */
+const HEX_ESCAPE_END_RE = /\\[0-9a-fA-F]{1,6}$/;
+
+/**
+ * Drops comments and collapses whitespace to one space, leaving strings and `url()`s byte for
+ * byte, so `content: "a　b"` or `"  "` renders in the build as it does on the dev server. The
+ * result reads as the source does: a newline after a string stays one, since it is what ends a
+ * string cut short, and a comment between two tokens that would run into one, as `x` and `url(`
+ * into `xurl(`, stays as an empty one, since a space would make `div` and `p` two selectors. A
+ * hex escape that a comment ends, such as `\41` before a comment and ` x`, is followed by two
+ * spaces, since it takes one as its own.
  */
 export function minifyCss(css: string): string {
   let out = "";
-  let space = false;
+  let last = "";
+  // What parts the last token written from the next: "", "comment", a space, or the newline that
+  // ends a string.
+  let gap = "";
   let i = 0;
   while (i < css.length) {
     const ch = css[i] ?? "";
     if (ch === "/" && css[i + 1] === "*") {
       i = consumeComment(css, i);
+      gap ||= "comment";
       continue;
     }
     if (CSS_WHITESPACE.has(ch)) {
-      space = true;
-      i++;
+      const whitespace = ch === "\r" && css[i + 1] === "\n" ? "\r\n" : ch;
+      if (gap === "" && CSS_NEWLINES.has(ch) && (last[0] === '"' || last[0] === "'")) {
+        // One LF, unless the string ends on a CR it escapes, which an LF would join into a CRLF.
+        gap = last.endsWith("\r") ? whitespace : "\n";
+      } else if (gap === "" || gap === "comment") {
+        gap = " ";
+      }
+      i += whitespace.length;
       continue;
     }
-    if (space && out !== "") {
-      out += " ";
+    if (out !== "") {
+      out +=
+        gap === "comment"
+          ? runTogether(last, ch)
+            ? "/**/"
+            : ""
+          : gap === " " && HEX_ESCAPE_END_RE.test(last)
+            ? "  "
+            : gap;
     }
-    space = false;
-    const end = ch === '"' || ch === "'" ? consumeString(css, i) : ch === "\\" ? i + 2 : i + 1;
-    out += css.slice(i, end);
+    gap = "";
+    const end = consumeToken(css, i);
+    last = css.slice(i, end);
+    out += last;
     i = end;
   }
   return out;

package/src/core/css.ts

@@ -2,6 +2,7 @@ import {
   blankStringsAndComments,
   consumeComment,
   consumeString,
+  consumeToken,
   matchBrace,
   scanTopLevel,
   splitTopLevel,
@@ -131,16 +132,11 @@ class SheetReader {
     const { source } = this;
     let i = 0;
     while (i < source.length) {
-      const ch = source[i];
-      if (ch === '"' || ch === "'") {
-        i = consumeString(source, i);
-      } else if (ch === "/" && source[i + 1] === "*") {
-        const close = consumeComment(source, i);
-        this.comments.push([i, close]);
-        i = close;
-      } else {
-        i += ch === "\\" ? 2 : 1;
+      const next = consumeToken(source, i);
+      if (source[i] === "/" && source[i + 1] === "*") {
+        this.comments.push([i, next]);
       }
+      i = next;
     }
     const locate = lineLocator(sheet.source);
     this.lineOf = (offset) => locate(offset).line;
@@ -181,13 +177,23 @@ class SheetReader {
     return i;
   }
 
-  /** A prelude's span with its trailing spaces trimmed off. */
+  /**
+   * A prelude's span with the spaces and comments at its end trimmed off; a string it ends on,
+   * such as the name of `@keyframes "pop"`, stays.
+   */
   trimEnd(start: number, end: number): number {
     let j = end;
-    while (j > start && WHITESPACE_RE.test(this.blank[j - 1] ?? "")) {
-      j--;
+    while (j > start) {
+      const comment = this.comments.find(([, close]) => close === j);
+      if (comment) {
+        j = comment[0];
+      } else if (WHITESPACE_RE.test(this.source[j - 1] ?? "")) {
+        j--;
+      } else {
+        break;
+      }
     }
-    return j;
+    return Math.max(j, start);
   }
 
   atRule(start: number, end: number, scope: Scope): number {

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);
+}

package/src/core/foreign-text.ts

@@ -0,0 +1,138 @@
+/**
+ * Text someone else wrote, such as a ref's title or the folder names in its repository, as dek
+ * puts it inside its own words. An agent reads dek's messages and AGENTS.md's dek block as dek's,
+ * so such text must not start a line there, carry a control character, or hold a character the
+ * person reading never sees.
+ */
+
+/**
+ * Characters that show as nothing or move the text around them: those Unicode marks
+ * default-ignorable, such as zero-width ones, the byte order mark, bidi controls, Hangul fillers,
+ * and tag characters, which a model reads as text though a person sees nothing; and the line and
+ * paragraph separators and the interlinear annotation marks. The variation selectors, Mongolian's
+ * free ones included, are default-ignorable too and left out: emoji, ideographic variants of a
+ * kanji, and Mongolian text use them on purpose.
+ */
+const HIDDEN_RE =
+  /(?![\u{fe00}-\u{fe0f}\u{e0100}-\u{e01ef}\u{180b}-\u{180d}\u{180f}])[\p{Default_Ignorable_Code_Point}\u{2028}\u{2029}\u{fff9}-\u{fffb}]/u;
+
+/** Whitespace and control characters, which a line of someone else's text shows as one space. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point.
+const SPACE_RE = /[\s\x00-\x1f\x7f-\x9f]/u;
+
+/** HIDDEN_RE for every match. */
+const HIDDEN_ALL_RE = new RegExp(HIDDEN_RE.source, "gu");
+
+/** True when `text` holds a character that shows as nothing or moves the text around it. */
+export function holdsHidden(text: string): boolean {
+  return HIDDEN_RE.test(text);
+}
+
+/** `U+202E`, as a code point is written. */
+function codePoint(char: string): string {
+  return `U+${(char.codePointAt(0) ?? 0).toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+/** A hidden character as dek shows it, so a reader sees it is there and which it is. */
+function marker(char: string): string {
+  return `⟨${codePoint(char)}⟩`;
+}
+
+/** `text` with each hidden character as dek shows it, `⟨U+XXXX⟩`, and the rest as it is. */
+export function revealHidden(text: string): string {
+  return text.replace(HIDDEN_ALL_RE, marker);
+}
+
+/** A line of a file someone else wrote that holds characters a person cannot see. */
+export type HiddenText = {
+  path: string;
+  line: number;
+  /** 1-based, in UTF-16 units as editors count: where the first of them is. */
+  column: number;
+  /** Each of them on the line, in order, as U+XXXX. */
+  codePoints: string[];
+};
+
+/** Each line of `text`, read from `path` and starting at line `firstLine`, that holds any. */
+export function hiddenText(text: string, path: string, firstLine = 1): HiddenText[] {
+  return text.split("\n").flatMap((line, index) => {
+    const found = [...line.matchAll(HIDDEN_ALL_RE)];
+    const [first] = found;
+    if (first === undefined) {
+      return [];
+    }
+    return [
+      {
+        path,
+        line: firstLine + index,
+        column: first.index + 1,
+        codePoints: found.map((match) => codePoint(match[0])),
+      },
+    ];
+  });
+}
+
+/**
+ * A marker, which text revealHidden already went over holds, or else one code point: the units a
+ * line is cut between.
+ */
+const UNIT_RE = /⟨U\+[0-9A-F]{4,6}⟩|[\s\S]/gu;
+
+/**
+ * One line of someone else's text inside dek's own: each hidden character shows as `⟨U+XXXX⟩`,
+ * whitespace and control characters as one space, and the line is cut to `max` characters with
+ * an ellipsis, never through a marker, whether this made it or revealHidden did before.
+ */
+export function foreignLine(text: string, max: number): string {
+  const units: string[] = [];
+  for (const [char = ""] of text.matchAll(UNIT_RE)) {
+    // A marker is longer than any one code point, which is at most two UTF-16 units.
+    const unit =
+      char.length > 2
+        ? char
+        : HIDDEN_RE.test(char)
+          ? marker(char)
+          : SPACE_RE.test(char)
+            ? " "
+            : char;
+    if (unit !== " " || (units.length > 0 && units.at(-1) !== " ")) {
+      units.push(unit);
+    }
+  }
+  if (units.at(-1) === " ") {
+    units.pop();
+  }
+  const width = (unit: string) => [...unit].length;
+  if (units.reduce((sum, unit) => sum + width(unit), 0) <= max) {
+    return units.join("");
+  }
+  const kept: string[] = [];
+  let size = 0;
+  for (const unit of units) {
+    if (size + width(unit) > max - 1) {
+      break;
+    }
+    kept.push(unit);
+    size += width(unit);
+  }
+  return `${kept.join("")}…`;
+}
+
+/** The longest a ref's title shows in a line of dek's: a title names a deck, it does not describe it. */
+export const TITLE_MAX = 80;
+
+/** The longest message dek gives that quotes someone else's text, such as Bun's on their source. */
+export const MESSAGE_MAX = 200;
+
+/** The longest name a list shows: a deck's folder names a deck, it does not describe one. */
+const NAME_MAX = 40;
+
+/** How many names a list shows before it counts the rest. */
+const LIST_MAX = 10;
+
+/** Names someone else chose, each a foreignLine of NAME_MAX, the first LIST_MAX and a count of the rest. */
+export function foreignList(names: string[]): string {
+  const shown = names.slice(0, LIST_MAX).map((name) => foreignLine(name, NAME_MAX));
+  const rest = names.length - shown.length;
+  return rest > 0 ? `${shown.join(", ")}, and ${rest} more` : shown.join(", ");
+}

package/src/core/github.ts

@@ -93,6 +93,7 @@ async function request(
   const auth = authorization(base);
   let response: Response;
   try {
+    // biome-ignore lint/style/noRestrictedGlobals: the deadline's signal bounds the request, and readBody cancels a read that outlasts it.
     response = await fetch(`${base}${path}`, {
       headers: {
         accept,