@bendyline/squisq 1.5.1 → 2.0.0

package/src/internal/immutable.ts

@@ -0,0 +1,58 @@
+/**
+ * Clone JSON-shaped runtime configuration without relying on structuredClone
+ * (which is unavailable in some of the ES2020/browser runtimes core supports).
+ * Data objects are recreated with safe own-property definitions so even a key
+ * named `__proto__` remains ordinary data.
+ */
+export function cloneData<T>(value: T, seen: WeakMap<object, unknown> = new WeakMap()): T {
+  if (value === null || typeof value !== 'object') return value;
+
+  const existing = seen.get(value);
+  if (existing !== undefined) return existing as T;
+
+  const tag = Object.prototype.toString.call(value);
+  if (tag === '[object ArrayBuffer]') {
+    const source = new Uint8Array(value as unknown as ArrayBuffer);
+    const copy = new Uint8Array(source.byteLength);
+    copy.set(source);
+    return copy.buffer as T;
+  }
+  if (tag === '[object Date]') {
+    return new Date(Date.prototype.getTime.call(value)) as T;
+  }
+
+  if (Array.isArray(value)) {
+    const copy: unknown[] = [];
+    seen.set(value, copy);
+    for (const item of value) copy.push(cloneData(item, seen));
+    return copy as T;
+  }
+
+  const source = value as Record<string, unknown>;
+  const copy: Record<string, unknown> = {};
+  seen.set(value, copy);
+  for (const key of Object.keys(source)) {
+    Object.defineProperty(copy, key, {
+      value: cloneData(source[key], seen),
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return copy as T;
+}
+
+/** Recursively freeze a data graph. Cycles are supported. */
+export function deepFreezeData<T>(value: T, seen: WeakSet<object> = new WeakSet()): T {
+  if (value === null || typeof value !== 'object' || seen.has(value)) return value;
+  seen.add(value);
+  for (const key of Object.keys(value)) {
+    deepFreezeData((value as Record<string, unknown>)[key], seen);
+  }
+  return Object.freeze(value);
+}
+
+/** Take an immutable snapshot suitable for storing in a process registry. */
+export function cloneAndFreezeData<T>(value: T): T {
+  return deepFreezeData(cloneData(value));
+}

package/src/jsonForm/index.ts

@@ -17,7 +17,15 @@ export type {
 
 export { chooseControl, primaryType, arrayItemKind } from './chooseControl.js';
 export { evaluateWhen, resolveFlag } from './evaluateWhen.js';
-export { toPointer, pointerSegments, getByPointer, setByPointer, resolveRef } from './pointer.js';
+export {
+  escapePointerSegment,
+  appendPointer,
+  toPointer,
+  pointerSegments,
+  getByPointer,
+  setByPointer,
+  resolveRef,
+} from './pointer.js';
 export { inferSchema } from './inferSchema.js';
 export type { InferSchemaOptions } from './inferSchema.js';
 export { buildJsonFormTokens, resolveJsonFormTheme } from './tokens.js';

package/src/jsonForm/pointer.ts

@@ -6,27 +6,67 @@
 
 import type { SquisqAnnotatedSchema } from './types.js';
 
+/** Escape one object-member name for use as an RFC 6901 pointer segment. */
+export function escapePointerSegment(segment: string): string {
+  return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
 /** Normalize a path to a JSON Pointer string. Accepts both forms. */
 export function toPointer(path: string): string {
-  if (path === '' || path === '/') return '';
+  if (path === '') return '';
   if (path.startsWith('/')) return path;
   // Dotted form: split on `.` and escape per RFC 6901.
-  return (
-    '/' +
-    path
-      .split('.')
-      .map((seg) => seg.replace(/~/g, '~0').replace(/\//g, '~1'))
-      .join('/')
-  );
+  return '/' + path.split('.').map(escapePointerSegment).join('/');
+}
+
+/** Append one member name to a dotted path or validated JSON Pointer. */
+export function appendPointer(base: string, segment: string): string {
+  const pointer = toPointer(base);
+  pointerSegments(pointer); // validate explicit pointer syntax before composing
+  return `${pointer}/${escapePointerSegment(segment)}`;
 }
 
 /** Split a JSON Pointer into decoded segments. Empty string → []. */
 export function pointerSegments(pointer: string): string[] {
   if (pointer === '') return [];
+  if (!pointer.startsWith('/')) {
+    throw new TypeError(`Invalid JSON Pointer ${JSON.stringify(pointer)}: expected "" or "/..."`);
+  }
   return pointer
     .slice(1)
     .split('/')
-    .map((seg) => seg.replace(/~1/g, '/').replace(/~0/g, '~'));
+    .map((seg) => {
+      if (/~(?:[^01]|$)/.test(seg)) {
+        throw new TypeError(
+          `Invalid JSON Pointer ${JSON.stringify(pointer)}: "~" must be escaped as "~0"`,
+        );
+      }
+      return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+    });
+}
+
+/** Parse the canonical array-index spelling used by JSON Pointer consumers. */
+function arrayIndex(segment: string): number | undefined {
+  if (!/^(?:0|[1-9]\d*)$/.test(segment)) return undefined;
+  const index = Number(segment);
+  // 2^32 - 1 is the Array length sentinel, not an element index.
+  return Number.isSafeInteger(index) && index <= 0xffff_fffe ? index : undefined;
+}
+
+function ownValue(object: object, key: string): unknown {
+  return Object.prototype.hasOwnProperty.call(object, key)
+    ? (object as Record<string, unknown>)[key]
+    : undefined;
+}
+
+/** Define a data member without invoking Object.prototype.__proto__'s setter. */
+function setOwn(object: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(object, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
 }
 
 /** Read a value from data by path (dotted or pointer). Returns undefined if missing. */
@@ -36,11 +76,11 @@ export function getByPointer(data: unknown, path: string): unknown {
   for (const seg of segments) {
     if (cur === null || cur === undefined) return undefined;
     if (Array.isArray(cur)) {
-      const idx = Number(seg);
-      if (!Number.isInteger(idx) || idx < 0 || idx >= cur.length) return undefined;
+      const idx = arrayIndex(seg);
+      if (idx === undefined || idx >= cur.length) return undefined;
       cur = cur[idx];
     } else if (typeof cur === 'object') {
-      cur = (cur as Record<string, unknown>)[seg];
+      cur = ownValue(cur, seg);
     } else {
       return undefined;
     }
@@ -65,10 +105,13 @@ function setRec(node: unknown, segments: string[], i: number, value: unknown): u
 
   // Decide whether the slot we're about to write into is an array index.
   const nextSeg = isLast ? undefined : segments[i + 1];
-  const writingArrayChild = nextSeg !== undefined && /^\d+$/.test(nextSeg);
+  const writingArrayChild = nextSeg !== undefined && arrayIndex(nextSeg) !== undefined;
 
   if (Array.isArray(node)) {
-    const idx = Number(seg);
+    const idx = arrayIndex(seg);
+    if (idx === undefined) {
+      throw new TypeError(`Invalid array index ${JSON.stringify(seg)} in JSON Pointer`);
+    }
     const next = node.slice();
     next[idx] = isLast
       ? value
@@ -80,9 +123,12 @@ function setRec(node: unknown, segments: string[], i: number, value: unknown): u
     string,
     unknown
   >;
-  obj[seg] = isLast
-    ? value
-    : setRec(obj[seg] ?? (writingArrayChild ? [] : {}), segments, i + 1, value);
+  const previous = ownValue(obj, seg);
+  setOwn(
+    obj,
+    seg,
+    isLast ? value : setRec(previous ?? (writingArrayChild ? [] : {}), segments, i + 1, value),
+  );
   return obj;
 }
 
@@ -98,12 +144,11 @@ export function resolveRef(
 ): SquisqAnnotatedSchema | undefined {
   if (!schema.$ref) return schema;
   const ref = schema.$ref;
+  if (ref === '#') return root;
   if (!ref.startsWith('#/')) return undefined;
-  const segments = pointerSegments(ref.slice(1));
-  let cur: unknown = root;
-  for (const seg of segments) {
-    if (cur === null || cur === undefined || typeof cur !== 'object') return undefined;
-    cur = (cur as Record<string, unknown>)[seg];
+  try {
+    return getByPointer(root, ref.slice(1)) as SquisqAnnotatedSchema | undefined;
+  } catch {
+    return undefined;
   }
-  return (cur as SquisqAnnotatedSchema | undefined) ?? undefined;
 }

package/src/markdown/attrTokens.ts

@@ -38,19 +38,21 @@ const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
 /**
  * Quote-aware match for a trailing `{[…]}` annotation: the interior is any
  * mix of quoted runs and characters other than `]` and quotes, so quoted
- * values may contain `]`. The trailing `[\s\]}]*` tolerates an accidental
- * doubled `]}` that users sometimes type when learning the syntax.
+ * values may contain `]`. An empty interior is valid so `{[]}` can remain
+ * lossless metadata instead of visible heading text. The trailing
+ * `[\s\]}]*` tolerates an accidental doubled `]}` that users sometimes type
+ * when learning the syntax.
  */
 const TEMPLATE_STRICT_RE = new RegExp(
-  `\\s*\\{\\[((?:[^\\]"']|${DQ_RUN}|${SQ_RUN})+)\\]\\}[\\s\\]}]*$`,
+  `\\s*\\{\\[((?:[^\\]"']|${DQ_RUN}|${SQ_RUN})*)\\]\\}[\\s\\]}]*$`,
 );
 
 /**
- * Legacy fallback matching the pre-quote-aware grammar (`[^\]]+` interior).
+ * Legacy fallback matching the pre-quote-aware grammar (`[^\]]*` interior).
  * Tried after the strict form so inputs with unbalanced quotes keep parsing
  * exactly as they did before quote support landed.
  */
-const TEMPLATE_LEGACY_RE = /\s*\{\[([^\]]+)\]\}[\s\]}]*$/;
+const TEMPLATE_LEGACY_RE = /\s*\{\[([^\]]*)\]\}[\s\]}]*$/;
 
 /**
  * Quote-aware match for a trailing Pandoc `{…}` block. The negative

package/src/markdown/convert.ts

@@ -376,6 +376,14 @@ export function serializePandocAttributes(attrs: HeadingAttributes): string | nu
   return `{${parts.join(' ')}}`;
 }
 
+function hasPrintablePandocAttributes(attrs: HeadingAttributes): boolean {
+  return Boolean(
+    attrs.id ||
+    (attrs.classes && attrs.classes.length > 0) ||
+    (attrs.params && Object.keys(attrs.params).length > 0),
+  );
+}
+
 /**
  * Serialize a HeadingTemplateAnnotation back to `{[templateName key=value …]}` text.
  * Values are quoted via the shared {@link quoteAttrValue} rule (same as
@@ -977,7 +985,9 @@ function blockToMdast(node: MarkdownBlockNode): MdastNode {
       const suffixes: string[] = [];
       if (node.attributes) {
         const pandoc = serializePandocAttributes(node.attributes);
-        if (pandoc != null) suffixes.push(pandoc);
+        if (pandoc != null && (pandoc !== '{}' || hasPrintablePandocAttributes(node.attributes))) {
+          suffixes.push(pandoc);
+        }
       }
       if (node.templateAnnotation) {
         suffixes.push(serializeTemplateAnnotation(node.templateAnnotation));

package/src/markdown/index.ts

@@ -144,6 +144,7 @@ export {
   createDocument,
   parseFrontmatter,
   formatBlockScalar,
+  formatFrontmatterValue,
   setFrontmatterValues,
   inferDocumentTitle,
   readFrontmatterThemeId,

package/src/markdown/stringify.ts

@@ -12,7 +12,7 @@ import remarkMath from 'remark-math';
 import remarkDirective from 'remark-directive';
 import type { MarkdownDocument, StringifyOptions } from './types.js';
 import { toMdast } from './convert.js';
-import { formatBlockScalar } from './utils.js';
+import { formatFrontmatterValue } from './utils.js';
 
 // Cache the default processor (all extensions, default formatting) to avoid rebuilding on every call.
 let defaultProcessor: any;
@@ -33,7 +33,7 @@ const SQ_RUN = `'(?:[^'\\\\]|\\\\.)*'`;
  * and quoted runs (which may themselves contain `]`).
  */
 const ESCAPED_TEMPLATE_SPAN_RE = new RegExp(
-  `\\{\\\\\\[((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^\\]\\\\])+)\\]\\}`,
+  `\\{\\\\\\[((?:${DQ_RUN}|${SQ_RUN}|\\\\.|[^\\]\\\\])*)\\]\\}`,
   'g',
 );
 
@@ -195,13 +195,8 @@ export function stringifyMarkdown(doc: MarkdownDocument, options?: StringifyOpti
   // Prepend YAML frontmatter if present
   if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {
     const yamlLines = Object.entries(doc.frontmatter).map(([k, v]) => {
-      if (typeof v === 'string') {
-        // Multi-line strings emit as a YAML literal block scalar, matching
-        // `formatFrontmatterValue` / `setFrontmatterValues` so both paths
-        // agree; single-line strings stay verbatim as before.
-        return /[\r\n]/.test(v)
-          ? `${k}: ${formatBlockScalar(v.replace(/\r\n?/g, '\n'))}`
-          : `${k}: ${v}`;
+      if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+        return `${k}: ${formatFrontmatterValue(v)}`;
       }
       return `${k}: ${JSON.stringify(v)}`;
     });

package/src/markdown/utils.ts

@@ -126,6 +126,17 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
   const result: Record<string, unknown> = {};
   const lines = yaml.split('\n');
 
+  // Define keys as data properties so a frontmatter key named `__proto__`
+  // cannot invoke Object.prototype's legacy setter.
+  const assign = (key: string, value: unknown): void => {
+    Object.defineProperty(result, key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  };
+
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const trimmed = line.trim();
@@ -135,7 +146,7 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
     if (colonIdx < 1) continue;
 
     const key = trimmed.slice(0, colonIdx).trim();
-    let value: string | boolean | number = trimmed.slice(colonIdx + 1).trim();
+    const value = trimmed.slice(colonIdx + 1).trim();
 
     // YAML literal block scalar: `key: |` or `key: |-`. Subsequent lines
     // that are more-indented than the key belong to the scalar; they are
@@ -172,27 +183,37 @@ export function parseFrontmatter(yaml: string): Record<string, unknown> | null {
         commonIndent = Math.min(commonIndent, bl.length - bl.trimStart().length);
       }
       if (!isFinite(commonIndent)) commonIndent = 0;
-      result[key] = blockLines.map((bl) => (bl === '' ? '' : bl.slice(commonIndent))).join('\n');
+      assign(key, blockLines.map((bl) => (bl === '' ? '' : bl.slice(commonIndent))).join('\n'));
       continue;
     }
 
-    // Remove surrounding quotes
-    if (
-      (value.startsWith('"') && value.endsWith('"')) ||
-      (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
+    // Quoted scalars are always strings, even when their contents look like a
+    // number or boolean. Double-quoted values emitted by
+    // formatFrontmatterValue use JSON-compatible escaping; single-quoted YAML
+    // represents a literal quote as two consecutive quotes.
+    if (value.startsWith('"') && value.endsWith('"')) {
+      try {
+        assign(key, JSON.parse(value));
+      } catch {
+        // Be permissive for hand-authored YAML outside our formatter's subset.
+        assign(key, value.slice(1, -1));
+      }
+      continue;
+    }
+    if (value.startsWith("'") && value.endsWith("'")) {
+      assign(key, value.slice(1, -1).replace(/''/g, "'"));
+      continue;
     }
 
     // Parse booleans and numbers
     if (value === 'true') {
-      result[key] = true;
+      assign(key, true);
     } else if (value === 'false') {
-      result[key] = false;
+      assign(key, false);
     } else if (value !== '' && !isNaN(Number(value))) {
-      result[key] = Number(value);
+      assign(key, Number(value));
     } else {
-      result[key] = value;
+      assign(key, value);
     }
   }
 
@@ -217,7 +238,7 @@ export function formatBlockScalar(value: string): string {
 const FRONTMATTER_BLOCK_RE = /^---\r?\n([\s\S]*?)\r?\n---(\r?\n)?/;
 
 /** Quote a frontmatter scalar so it round-trips cleanly through `parseFrontmatter`. */
-function formatFrontmatterValue(value: string | number | boolean): string {
+export function formatFrontmatterValue(value: string | number | boolean): string {
   if (typeof value === 'boolean' || typeof value === 'number') return String(value);
   // Multi-line strings can't live on one line — emit a YAML literal block
   // scalar (`|-`) that `parseFrontmatter` reads back. This carries pretty-
@@ -239,7 +260,8 @@ function formatFrontmatterValue(value: string | number | boolean): string {
     value === '' ||
     value === 'true' ||
     value === 'false' ||
-    /^-?\d+(\.\d+)?$/.test(value);
+    (value !== '' && !Number.isNaN(Number(value))) ||
+    (/^["']/.test(value) && /["']$/.test(value));
   if (!needsQuote) return value;
   // Prefer double quotes; escape any embedded double-quote / backslash.
   const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');