create-ailk 0.31.0 → 0.32.0

package/templates/tools/mdx-braces.ts

@@ -0,0 +1,303 @@
+/**
+ * Bare `{…}` braces on mdx-body pages (#10773, spec
+ * docs/specs/10773-update-never-refreshes-0-19-spec.md D3, D4).
+ *
+ * MDX reads every `{` in body text as the start of a JavaScript expression.
+ * Under the renderer's `next-mdx-remote` defaults (`blockJS`), an expression
+ * that does not parse fails the page, and one that parses is deleted — so on
+ * an mdx-body page every `{` in text other than a `{/* … *\/}` comment is a
+ * defect. This module is the one lexical rule for that brace:
+ *
+ * - `findBareBraces` names every bare brace in a body, by offset, line and
+ *   column, in one left-to-right pass;
+ * - `escapeBareBraces` inserts one `\` before each, and keeps the result only
+ *   when the site's own MDX parser reads it with no expression left but
+ *   comments — the lexer proposes, the parser disposes.
+ *
+ * Used by `create-ailk update` and, through a byte-identical copy in the
+ * scaffold's `tools/`, by `pnpm mdx-body:check`. Pure: no filesystem and no
+ * imports. It must never contain a double open brace, which the scaffold copy
+ * substitutes as a marker.
+ */
+
+export interface BareBrace {
+  /** Offset of the `{` in the body. */
+  offset: number;
+  /** 1-based line within the body. */
+  line: number;
+  /** 1-based column within the line. */
+  column: number;
+  /** `comment-like` when the next non-whitespace character is `/`. */
+  kind: "placeholder" | "comment-like";
+}
+
+/** A minimal mdast node: what `escapeBareBraces` reads from the parser's tree. */
+export interface MdastNode {
+  type: string;
+  value?: unknown;
+  position?: { start?: { line?: number; offset?: number }; end?: { offset?: number } };
+  children?: MdastNode[];
+}
+
+/** The site's MDX parser: throws the parser's message (carrying `line` and `reason`) on failure. */
+export type MdxParse = (body: string) => MdastNode;
+
+export type EscapeResult =
+  | { kind: "clean" }
+  | { kind: "escaped"; text: string; count: number }
+  | { kind: "refused"; reason: string };
+
+const ESM_RE = /^(?:import|export)[ {*]/;
+// MDX has no indented code, so a fence opens at any indentation — and inside
+// a list item or a blockquote, after its markers.
+const FENCE_RE = /^[ \t]*(?:(?:>|[-*+]|\d{1,9}[.)])[ \t]*)*(`{3,}|~{3,})/;
+const COMMENT_CLOSE_RE = /\*\/\s*\}/g;
+const WHITESPACE_RE = /\s/;
+const TAG_START_RE = /[A-Za-z/>]/;
+
+const isBlank = (line: string): boolean => line.trim() === "";
+
+/**
+ * Every bare `{` in an MDX body. Skips, in this order of precedence: fenced
+ * code, ESM blocks, backslash escapes, inline code, JSX tags (attribute
+ * expressions included) and `{/* … *\/}` comments. Linear in the body.
+ */
+export function findBareBraces(body: string): BareBrace[] {
+  const found: Array<Omit<BareBrace, "line" | "column">> = [];
+  const lineEnd = (from: number): number => {
+    const end = body.indexOf("\n", from);
+    return end === -1 ? body.length : end;
+  };
+  // A code span or a tag never crosses a blank line: true at a `\n` that ends
+  // the body or starts a blank line.
+  const paragraphBreak = (at: number): boolean => {
+    let j = at + 1;
+    while (body[j] === " " || body[j] === "\t" || body[j] === "\r") j += 1;
+    return j >= body.length || body[j] === "\n";
+  };
+  // Memo so a failed search is never repeated over the same text.
+  const spanFailedUntil = new Map<number, number>();
+  let tagFailedUntil = -1;
+  let commentClose: { from: number; at: number } | undefined;
+
+  let i = 0;
+  while (i < body.length) {
+    if (i === 0 || body[i - 1] === "\n") {
+      const end = lineEnd(i);
+      const line = body.slice(i, end);
+      const fence = FENCE_RE.exec(line)?.[1];
+      if (fence !== undefined) {
+        // Skip to after the closing fence line, or to the end of the body.
+        let at = end;
+        while (at < body.length) {
+          const next = lineEnd(at + 1);
+          const candidate = body.slice(at + 1, next);
+          const run = FENCE_RE.exec(candidate);
+          at = next;
+          if (
+            run !== null &&
+            run[1]![0] === fence[0] &&
+            run[1]!.length >= fence.length &&
+            candidate.slice(run[0].length).trim() === ""
+          ) {
+            break;
+          }
+        }
+        i = at + 1;
+        continue;
+      }
+      if (ESM_RE.test(line)) {
+        let at = end;
+        while (at < body.length) {
+          const next = lineEnd(at + 1);
+          if (isBlank(body.slice(at + 1, next))) break;
+          at = next;
+        }
+        i = at + 1;
+        continue;
+      }
+    }
+
+    const char = body[i]!;
+    if (char === "\\") {
+      // A backslash before a line break is a hard break; the next line is read as a line.
+      i += body[i + 1] === "\n" ? 1 : 2;
+      continue;
+    }
+    if (char === "`") {
+      let run = 1;
+      while (body[i + run] === "`") run += 1;
+      const close = spanFailedUntil.get(run) ?? -1;
+      let closed = -1;
+      if (close < i) {
+        let at = i + run;
+        for (; at < body.length; at += 1) {
+          if (body[at] === "\n" && (paragraphBreak(at) || FENCE_RE.test(body.slice(at + 1, lineEnd(at + 1))))) break;
+          if (body[at] !== "`") continue;
+          let length = 1;
+          while (body[at + length] === "`") length += 1;
+          if (length === run) {
+            closed = at + length;
+            break;
+          }
+          at += length - 1;
+        }
+        if (closed === -1) spanFailedUntil.set(run, at);
+      }
+      i = closed === -1 ? i + run : closed;
+      continue;
+    }
+    if (char === "<" && TAG_START_RE.test(body[i + 1] ?? "") && i >= tagFailedUntil) {
+      let depth = 0;
+      let quote = "";
+      let closed = -1;
+      let at = i + 1;
+      for (; at < body.length; at += 1) {
+        const c = body[at]!;
+        if (c === "\n" && paragraphBreak(at)) break;
+        if (quote !== "") {
+          if (c === quote) quote = "";
+        } else if (depth > 0) {
+          if (c === "{") depth += 1;
+          else if (c === "}") depth -= 1;
+        } else if (c === '"' || c === "'") {
+          quote = c;
+        } else if (c === "{") {
+          depth = 1;
+        } else if (c === ">") {
+          closed = at + 1;
+          break;
+        }
+      }
+      if (closed !== -1) {
+        i = closed;
+        continue;
+      }
+      // An unclosed tag already breaks the page; no later `<` before `at` is
+      // read as a tag, which keeps the scan linear.
+      tagFailedUntil = at;
+      i += 1;
+      continue;
+    }
+    if (char === "{") {
+      let next = i + 1;
+      while (next < body.length && WHITESPACE_RE.test(body[next]!)) next += 1;
+      if (body[next] === "/" && body[next + 1] === "*") {
+        if (commentClose === undefined || commentClose.from > i || (commentClose.at !== -1 && commentClose.at < i)) {
+          COMMENT_CLOSE_RE.lastIndex = next + 2;
+          const match = COMMENT_CLOSE_RE.exec(body);
+          commentClose = { from: i, at: match === null ? -1 : match.index + match[0].length };
+        }
+        if (commentClose.at !== -1) {
+          i = commentClose.at;
+          continue;
+        }
+      }
+      found.push({ offset: i, kind: body[next] === "/" ? "comment-like" : "placeholder" });
+    }
+    i += 1;
+  }
+
+  // Offsets to 1-based line and column, in one pass.
+  const braces: BareBrace[] = [];
+  let line = 1;
+  let lineStart = 0;
+  let scanned = 0;
+  for (const brace of found) {
+    for (; scanned < brace.offset; scanned += 1) {
+      if (body[scanned] === "\n") {
+        line += 1;
+        lineStart = scanned + 1;
+      }
+    }
+    braces.push({ ...brace, line, column: brace.offset - lineStart + 1 });
+  }
+  return braces;
+}
+
+const COMMENT_VALUE_RE = /^\s*\/\*[\s\S]*\*\/\s*$/;
+
+/** The first expression node left in the tree that is not a comment. */
+export function firstExpression(node: MdastNode): MdastNode | undefined {
+  if (
+    (node.type === "mdxFlowExpression" || node.type === "mdxTextExpression") &&
+    !(typeof node.value === "string" && COMMENT_VALUE_RE.test(node.value))
+  ) {
+    return node;
+  }
+  for (const child of node.children ?? []) {
+    const hit = firstExpression(child);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+/** The first `code` or `inlineCode` node whose span holds one of `offsets` (sorted). */
+function codeNodeHolding(node: MdastNode, offsets: number[]): MdastNode | undefined {
+  if (node.type === "code" || node.type === "inlineCode") {
+    const start = node.position?.start?.offset;
+    const end = node.position?.end?.offset;
+    if (typeof start === "number" && typeof end === "number") {
+      let lo = 0;
+      let hi = offsets.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (offsets[mid]! < start) lo = mid + 1;
+        else hi = mid;
+      }
+      if (lo < offsets.length && offsets[lo]! < end) return node;
+    }
+  }
+  for (const child of node.children ?? []) {
+    const hit = codeNodeHolding(child, offsets);
+    if (hit !== undefined) return hit;
+  }
+  return undefined;
+}
+
+/**
+ * Escape every bare brace in `body`, all or nothing: `clean` when there is
+ * none (`parse` is not called), `refused` when a brace is a mangled comment,
+ * the escaped text does not parse, or an expression the escape did not reach
+ * remains; otherwise `escaped`.
+ */
+export function escapeBareBraces(body: string, parse: MdxParse): EscapeResult {
+  const braces = findBareBraces(body);
+  if (braces.length === 0) return { kind: "clean" };
+  const mangled = braces.find((brace) => brace.kind === "comment-like");
+  if (mangled !== undefined) {
+    return { kind: "refused", reason: `{/ at line ${mangled.line} is not a {/* … */} comment` };
+  }
+  const parts: string[] = [];
+  let from = 0;
+  for (const { offset } of braces) {
+    parts.push(body.slice(from, offset), "\\");
+    from = offset;
+  }
+  parts.push(body.slice(from));
+  const text = parts.join("");
+  let tree: MdastNode;
+  try {
+    tree = parse(text);
+  } catch (err) {
+    const { line, reason } = (err ?? {}) as { line?: unknown; reason?: unknown };
+    const why = typeof reason === "string" ? reason : err instanceof Error ? err.message : String(err);
+    return { kind: "refused", reason: `line ${typeof line === "number" ? line : "?"}: ${why}` };
+  }
+  const escapes = braces.map((brace, k) => brace.offset + k);
+  const inCode = codeNodeHolding(tree, escapes);
+  if (inCode !== undefined) {
+    return {
+      kind: "refused",
+      reason: `a brace at line ${inCode.position?.start?.line ?? "?"} is inside code the lexer did not see`,
+    };
+  }
+  const left = firstExpression(tree);
+  if (left !== undefined) {
+    return {
+      kind: "refused",
+      reason: `an expression at line ${left.position?.start?.line ?? "?"} the escape did not reach`,
+    };
+  }
+  return { kind: "escaped", text, count: braces.length };
+}

package/versions.json

@@ -1,66 +1,66 @@
 {
-  "@working-theory/admin-ui": "0.54.0",
-  "@working-theory/aeo": "0.54.0",
-  "@working-theory/agent-context": "0.54.0",
+  "@working-theory/admin-ui": "0.55.0",
+  "@working-theory/aeo": "0.55.0",
+  "@working-theory/agent-context": "0.55.0",
   "@working-theory/agent-contract": "0.1.0",
   "@working-theory/agent-memory": "0.0.0",
   "@working-theory/ai": "0.1.0",
-  "@working-theory/analytics": "0.54.0",
-  "@working-theory/api": "0.54.0",
-  "@working-theory/api-client": "0.54.0",
+  "@working-theory/analytics": "0.55.0",
+  "@working-theory/api": "0.55.0",
+  "@working-theory/api-client": "0.55.0",
   "@working-theory/cda-filesystem": "0.0.0",
-  "@working-theory/cli": "0.54.0",
-  "@working-theory/common": "0.54.0",
+  "@working-theory/cli": "0.55.0",
+  "@working-theory/common": "0.55.0",
   "@working-theory/consent": "0.1.0",
-  "@working-theory/content-adapters": "0.54.0",
-  "@working-theory/content-projection": "0.54.0",
-  "@working-theory/email": "0.54.0",
+  "@working-theory/content-adapters": "0.55.0",
+  "@working-theory/content-projection": "0.55.0",
+  "@working-theory/email": "0.55.0",
   "@working-theory/env": "0.0.0",
-  "@working-theory/eslint-config": "0.54.0",
-  "@working-theory/fumadocs-schema": "0.54.0",
+  "@working-theory/eslint-config": "0.55.0",
+  "@working-theory/fumadocs-schema": "0.55.0",
   "@working-theory/ids": "0.19.0",
-  "@working-theory/jsonld": "0.54.0",
-  "@working-theory/license": "0.54.0",
-  "@working-theory/mcp-server": "0.54.0",
-  "@working-theory/metadata": "0.54.0",
-  "@working-theory/observability": "0.54.0",
-  "@working-theory/page-renderer": "0.54.0",
+  "@working-theory/jsonld": "0.55.0",
+  "@working-theory/license": "0.55.0",
+  "@working-theory/mcp-server": "0.55.0",
+  "@working-theory/metadata": "0.55.0",
+  "@working-theory/observability": "0.55.0",
+  "@working-theory/page-renderer": "0.55.0",
   "@working-theory/plugin-mcp": "0.1.3",
-  "@working-theory/schema": "0.54.0",
-  "@working-theory/schema-pack-registry": "0.54.0",
-  "@working-theory/schema-validator": "0.54.0",
-  "@working-theory/sections-registry": "0.54.0",
-  "@working-theory/site-config": "0.54.0",
-  "@working-theory/spoke-checkout": "0.7.10",
-  "@working-theory/stripe-client": "0.54.0",
-  "@working-theory/templates": "0.54.0",
-  "@working-theory/theme": "0.54.0",
-  "@working-theory/ui": "0.54.0",
-  "@working-theory/validation": "0.54.0",
-  "@working-theory/web-i18n": "0.54.0",
-  "@working-theory/admin": "0.10.0",
-  "@working-theory/api-commerce": "0.1.8",
-  "@working-theory/api-content-write": "0.5.0",
-  "@working-theory/api-hub": "0.4.0",
-  "@working-theory/api-multi-tenant": "0.2.3",
-  "@working-theory/api-scheduling": "0.4.5",
-  "@working-theory/api-signal-collectors": "0.3.1",
-  "@working-theory/api-workspace": "0.5.0",
+  "@working-theory/schema": "0.55.0",
+  "@working-theory/schema-pack-registry": "0.55.0",
+  "@working-theory/schema-validator": "0.55.0",
+  "@working-theory/sections-registry": "0.55.0",
+  "@working-theory/site-config": "0.55.0",
+  "@working-theory/spoke-checkout": "0.7.11",
+  "@working-theory/stripe-client": "0.55.0",
+  "@working-theory/templates": "0.55.0",
+  "@working-theory/theme": "0.55.0",
+  "@working-theory/ui": "0.55.0",
+  "@working-theory/validation": "0.55.0",
+  "@working-theory/web-i18n": "0.55.0",
+  "@working-theory/admin": "0.10.1",
+  "@working-theory/api-commerce": "0.1.9",
+  "@working-theory/api-content-write": "0.5.1",
+  "@working-theory/api-hub": "0.4.1",
+  "@working-theory/api-multi-tenant": "0.2.4",
+  "@working-theory/api-scheduling": "0.4.6",
+  "@working-theory/api-signal-collectors": "0.3.2",
+  "@working-theory/api-workspace": "0.5.1",
   "@working-theory/billing-client": "0.0.0",
   "@working-theory/branding": "0.0.0",
   "@working-theory/license-client": "0.0.0",
   "@working-theory/license-manifest": "0.0.0",
-  "@working-theory/mcp-scheduling": "0.3.7",
-  "@working-theory/mcp-signal-collectors": "0.2.8",
-  "@working-theory/mcp-workspace": "0.6.0",
+  "@working-theory/mcp-scheduling": "0.3.8",
+  "@working-theory/mcp-signal-collectors": "0.2.9",
+  "@working-theory/mcp-workspace": "0.6.1",
   "@working-theory/partner-session": "0.0.0",
   "@working-theory/preview-protocol": "0.0.0",
-  "@working-theory/ui-commerce": "0.23.32",
-  "@working-theory/ui-docs-blog": "0.23.32",
-  "@working-theory/ui-scheduling": "0.25.6",
-  "@working-theory/ui-signal-collectors": "0.27.10",
+  "@working-theory/ui-commerce": "0.23.33",
+  "@working-theory/ui-docs-blog": "0.23.33",
+  "@working-theory/ui-scheduling": "0.25.7",
+  "@working-theory/ui-signal-collectors": "0.27.11",
   "@working-theory/web": "0.0.0",
   "@working-theory/app-api": "1.0.0",
   "@working-theory/mcp": "0.0.0",
-  "@working-theory/database": "0.54.0"
+  "@working-theory/database": "0.55.0"
 }