@jxsuite/schema 1.5.0 → 1.8.0

package/src/ijson.ts

@@ -0,0 +1,205 @@
+/**
+ * I-JSON (RFC 7493): the two ways a JSON document can parse cleanly and still mean something other
+ * than what it says.
+ *
+ * Both matter here more than they would elsewhere, because a Jx document does not stay JSON. It
+ * round-trips through markdown frontmatter and through a Yjs CRDT, and each crossing rebuilds the
+ * object from the parsed value — so anything `JSON.parse` quietly discarded is discarded for good,
+ * and the file the author reopens is not the file they wrote.
+ *
+ * - **Duplicate names** (§2.3). `JSON.parse` keeps the last and says nothing. In a hand-edited
+ *   document — two `state` keys after a bad merge, say — the first one's contents simply vanish.
+ * - **Numbers outside the IEEE 754 double range** (§2.2). `9007199254740993` parses to
+ *   `9007199254740992`, and the next serialization writes the wrong number back to disk.
+ *
+ * Implemented as a scan of the source text rather than a `JSON.parse` reviver, because by the time
+ * a reviver runs the duplicate is already gone. The scanner is deliberately small: it only needs to
+ * know where strings and object keys are, so it does not build a tree or validate the grammar —
+ * `JSON.parse` has already done that by the time this is called.
+ *
+ * @docs framework/agents/authoring-rules
+ */
+
+/** One I-JSON violation, located by the path of the object that contains it. */
+export interface IJsonProblem {
+  kind: "duplicate-key" | "unsafe-number";
+  /** Dotted path to the containing object, `""` at the root. */
+  path: string;
+  /** The duplicated key, or the number literal as written. */
+  detail: string;
+}
+
+const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
+
+/**
+ * Find I-JSON violations in already-valid JSON text.
+ *
+ * @param {string} text - JSON source that `JSON.parse` accepts
+ * @returns {IJsonProblem[]} Empty when the document is I-JSON
+ */
+export function findIJsonProblems(text: string): IJsonProblem[] {
+  const problems: IJsonProblem[] = [];
+  /**
+   * One frame per open `{` or `[`. Arrays carry a path too, so an object inside one is reported
+   * under the key that names the array rather than under whatever enclosed it.
+   */
+  const stack: { kind: "object" | "array"; path: string; keys?: Set<string> }[] = [];
+  /** The key most recently read, naming the value that follows it. */
+  let pendingKey: string | null = null;
+  let index = 0;
+
+  const currentPath = () => stack.at(-1)?.path ?? "";
+  const childPath = () =>
+    pendingKey === null ? currentPath() : joinPath(currentPath(), pendingKey);
+
+  const readString = (): string => {
+    // Assumes text[index] === '"'; returns the decoded value and leaves index past the closer.
+    index += 1;
+    let out = "";
+    while (index < text.length) {
+      const char = text[index]!;
+      if (char === "\\") {
+        const next = text[index + 1] ?? "";
+        // Only `\uXXXX` needs decoding to compare keys correctly; the rest map one-to-one.
+        if (next === "u") {
+          out += String.fromCodePoint(Number.parseInt(text.slice(index + 2, index + 6), 16));
+          index += 6;
+        } else {
+          out += ESCAPES[next] ?? next;
+          index += 2;
+        }
+        continue;
+      }
+      if (char === '"') {
+        index += 1;
+        return out;
+      }
+      out += char;
+      index += 1;
+    }
+    return out;
+  };
+
+  while (index < text.length) {
+    const char = text[index]!;
+
+    if (WHITESPACE.has(char) || char === "," || char === ":") {
+      index += 1;
+      continue;
+    }
+
+    if (char === "{" || char === "[") {
+      stack.push(
+        char === "{"
+          ? { keys: new Set(), kind: "object", path: childPath() }
+          : { kind: "array", path: childPath() },
+      );
+      pendingKey = null;
+      index += 1;
+      continue;
+    }
+    if (char === "}" || char === "]") {
+      stack.pop();
+      pendingKey = null;
+      index += 1;
+      continue;
+    }
+
+    if (char === '"') {
+      const value = readString();
+      /*
+       * A string is a key when it sits directly inside an object and a `:` follows. Inside an
+       * array it is an element, and the same text on the right of a `:` is a value.
+       */
+      const frame = stack.at(-1);
+      if (frame?.kind === "object" && nextMeaningful(text, index) === ":") {
+        if (frame.keys!.has(value)) {
+          problems.push({ detail: value, kind: "duplicate-key", path: frame.path });
+        }
+        frame.keys!.add(value);
+        pendingKey = value;
+      } else {
+        pendingKey = null;
+      }
+      continue;
+    }
+
+    if (char === "-" || (char >= "0" && char <= "9")) {
+      const start = index;
+      while (index < text.length && /[\d+.eE-]/.test(text[index]!)) {
+        index += 1;
+      }
+      const literal = text.slice(start, index);
+      if (!isSafeJsonNumber(literal)) {
+        problems.push({ detail: literal, kind: "unsafe-number", path: childPath() });
+      }
+      pendingKey = null;
+      continue;
+    }
+
+    // `true`, `false`, `null`. The grammar is already known good, so a run of letters is enough.
+    const before = index;
+    while (index < text.length && /[A-Za-z]/.test(text[index]!)) {
+      index += 1;
+    }
+    if (index === before) {
+      index += 1;
+    }
+    pendingKey = null;
+  }
+
+  return problems;
+}
+
+const ESCAPES: Record<string, string> = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "\t",
+};
+
+/** The next non-whitespace character at or after `from`, or "" at the end. */
+function nextMeaningful(text: string, from: number): string {
+  let index = from;
+  while (index < text.length && WHITESPACE.has(text[index]!)) {
+    index += 1;
+  }
+  return text[index] ?? "";
+}
+
+function joinPath(parent: string, key: string): string {
+  return parent === "" ? key : `${parent}.${key}`;
+}
+
+/**
+ * True when a number literal survives a round trip through a double.
+ *
+ * Only integers are judged. A fractional literal is _always_ approximate in binary floating point —
+ * `0.1` is not representable either — so flagging those would flag most real documents and say
+ * nothing about whether the author's value survived.
+ *
+ * @param {string} literal
+ * @returns {boolean}
+ */
+export function isSafeJsonNumber(literal: string): boolean {
+  if (/[.eE]/.test(literal)) {
+    return true;
+  }
+  const value = Number(literal);
+  if (!Number.isFinite(value)) {
+    return false;
+  }
+  // The literal is an integer, so `String(Number(x))` reproduces it exactly when nothing was lost.
+  return String(value) === literal.replace(/^\+/, "");
+}
+
+/** A one-line description of a problem, for a build error or a warning. */
+export function describeIJsonProblem(problem: IJsonProblem): string {
+  const where = problem.path === "" ? "the document root" : `"${problem.path}"`;
+  return problem.kind === "duplicate-key"
+    ? `duplicate key "${problem.detail}" in ${where} — JSON.parse keeps the last one and ` +
+        "silently discards the first (RFC 7493 §2.3)"
+    : `number ${problem.detail} in ${where} cannot be represented exactly and will change when ` +
+        "the document is written back (RFC 7493 §2.2)";
+}

package/src/intl.ts

@@ -0,0 +1,155 @@
+/**
+ * The blessed `Intl` helpers: one list, read by everything that needs to know them.
+ *
+ * **The list used to exist in four places** — the runtime's allow-set, the runtime's dispatch
+ * table, the compiler's emitter, and a prose JSON-Schema description enumerating them by name. The
+ * description was the dangerous one: nothing checked it, so a helper could ship and the schema go
+ * on telling authors it did not exist. The names live here; the runtime and the schema description
+ * both read them, and a test asserts the two agree.
+ *
+ * **Why helpers and not the constructors.** ECMA-402's formatters are constructors, and a formula
+ * is a pure call — `new` is not in the expression grammar and should not be. Each helper wraps
+ * construct-then-format, which is the shape a document author wants anyway.
+ *
+ * **Every helper takes an explicit locale.** `new Intl.NumberFormat(undefined)` reads the _host's_
+ * locale, so the same document compiled on two machines emits different text. A call that names no
+ * locale gets the **page's** — which is a function of the route, not of the build machine — and
+ * failing that the fixed default below; see `site-architecture.md` §13.7.
+ *
+ * Pure data and no imports, so a browser bundle, the compiler and the schema generator can all read
+ * it without pulling anything else in.
+ *
+ * @docs studio/logic/formulas
+ */
+
+/**
+ * The locale a helper uses when a formula names none **and there is no page to ask**.
+ *
+ * **Not the host's.** `new Intl.NumberFormat(undefined)` reads the machine's locale, so the same
+ * document renders `1,234.5` on one build machine and `1.234,5` on another, and a site's output
+ * stops being a function of its input.
+ *
+ * A page's own locale is the better answer where there is one — a page under `/fr/` that formats a
+ * date means French, and it already said so in `<html lang>` — so `$page.locale` is consulted first
+ * (see `INTL_LOCALE_PARAM`). That preserves the property this constant exists for, because
+ * `$page.locale` is a function of the route and the document rather than of the machine. This value
+ * is what remains for a scope with no page: a component's own state, or the runtime evaluated
+ * standalone.
+ */
+export const DEFAULT_FORMAT_LOCALE = "en-US";
+
+/**
+ * The time zone `Intl/formatDate` uses when the formula's options name none.
+ *
+ * The same determinism argument as the locale, and worse in effect: a locale changes how a date
+ * reads, a time zone can change **which day it is**. A post timestamped `2026-08-16T02:00Z` renders
+ * as the 16th in UTC and the 15th in New York, so a build machine's zone would silently move dates
+ * in published HTML. UTC is the one zone that is the same everywhere.
+ */
+export const DEFAULT_TIME_ZONE = "UTC";
+
+/** One blessed helper: its callee path (after `window#/`) and what it wraps. */
+export interface IntlHelper {
+  /** The callee path an expression names, e.g. `Intl/formatNumber`. */
+  path: string;
+  /** The ECMA-402 constructor it wraps. */
+  api: string;
+  /** Parameter names, in order, for documentation and for the compiled call. */
+  params: string[];
+  /** One line, for the formula catalogue and the schema description. */
+  summary: string;
+}
+
+/**
+ * Every blessed `Intl` helper, in the order they are documented.
+ *
+ * **`DurationFormat` is deliberately absent.** Its baseline support is not universal, and a blessed
+ * global that throws on a browser Jx claims to support is worse than one that does not exist: the
+ * author writes a formula that works on their machine and fails on a visitor's.
+ */
+export const INTL_HELPERS: readonly IntlHelper[] = [
+  {
+    api: "Intl.NumberFormat",
+    params: ["value", "locale", "options"],
+    path: "Intl/formatNumber",
+    summary: "Format a number for a locale — grouping, decimals, currency, percent, units.",
+  },
+  {
+    api: "Intl.DateTimeFormat",
+    params: ["value", "locale", "options"],
+    path: "Intl/formatDate",
+    summary: "Format a date or timestamp for a locale. Pass `timeZone` in options.",
+  },
+  {
+    api: "Intl.RelativeTimeFormat",
+    params: ["value", "unit", "locale", "options"],
+    path: "Intl/formatRelativeTime",
+    summary: 'Format a relative time — `-3, "day"` becomes "3 days ago".',
+  },
+  {
+    api: "Intl.ListFormat",
+    params: ["values", "locale", "options"],
+    path: "Intl/formatList",
+    summary: 'Join a list the way a locale does — "a, b, and c", not a hand-written comma join.',
+  },
+  {
+    api: "Intl.PluralRules",
+    params: ["value", "locale", "options"],
+    path: "Intl/plural",
+    summary:
+      'Which plural category a number falls in ("one", "few", "other") — many languages have ' +
+      "more than two, so a ternary on `n === 1` is wrong outside English.",
+  },
+  {
+    api: "Intl.Collator",
+    params: ["a", "b", "locale", "options"],
+    path: "Intl/compare",
+    summary:
+      "Compare two strings for sorting. `<` and `sort()` order by UTF-16 code unit, which puts " +
+      '"Zebra" before "apple" and sorts every accented word into the wrong place.',
+  },
+  {
+    api: "Intl.DisplayNames",
+    params: ["code", "type", "locale", "options"],
+    path: "Intl/displayName",
+    summary:
+      'The name of a language, region, script or currency in a locale — "de" as "German" or ' +
+      '"Deutsch", from CLDR rather than a hand-kept table.',
+  },
+  {
+    api: "Intl.Segmenter",
+    params: ["value", "granularity", "locale"],
+    path: "Intl/segment",
+    summary:
+      "Split text into graphemes, words or sentences (UAX #29). `[...str]` splits code points, " +
+      "so it cuts an emoji with a skin-tone modifier in half.",
+  },
+] as const;
+
+/** Just the callee paths, for the runtime's allow-set. */
+export const INTL_HELPER_PATHS: readonly string[] = INTL_HELPERS.map((helper) => helper.path);
+
+/**
+ * Where each helper's `locale` argument sits, so a call that omits it can be given the page's.
+ *
+ * Derived from `params` rather than written out, for the reason this module exists at all: a
+ * hand-kept second list is what let the schema description drift from the implementation. The
+ * position differs per helper — `formatNumber` takes it second, `formatRelativeTime` third — and a
+ * table that disagreed with the signature would pass the wrong argument silently, which reads as a
+ * formatting bug rather than a wiring one.
+ */
+export const INTL_LOCALE_PARAM: Readonly<Record<string, number>> = Object.fromEntries(
+  INTL_HELPERS.map((helper) => [helper.path, helper.params.indexOf("locale")]),
+);
+
+/**
+ * The helper names as one clause, for the `call` operator's JSON-Schema description.
+ *
+ * Generated rather than typed out, because a hand-written enumeration is what let the schema drift
+ * from the implementation in the first place.
+ *
+ * @returns {string}
+ */
+export function intlHelpersClause(): string {
+  return `the Intl helpers ${INTL_HELPER_PATHS.join(", ")}`;
+}