@json-schema-engine/compiler 0.0.1

package/dist/standalone.js

@@ -0,0 +1,166 @@
+// Standalone source emission (D10 build-time mode): a self-contained ES
+// module with zero imports and zero code generation — deployable under a
+// strict CSP (`node --disallow-code-generation-from-strings`, workers,
+// serverless cold start).
+//
+// Scope (M6.5 design call, DESIGN §7): fully static plans only. A schema
+// with dynamic islands or fallback units needs the interpreter at runtime,
+// and the interpreter IS the CSP-safe tier (D10) — under CSP, evaluate such
+// schemas with @json-schema-engine/core directly; where code generation is allowed, use
+// the runtime mode. Emitting a core-importing hybrid module buys nothing
+// over those two paths.
+//
+// The preamble duplicates core's helper semantics by necessity (a
+// self-contained module cannot import them). Drift is guarded twice:
+// standalone.test.ts compares every helper against its core original over a
+// vector corpus, and the CSP check re-runs the official suite through
+// emitted modules.
+import { DEFAULT_MAX_DEPTH } from "@json-schema-engine/core";
+import { buildPlan } from "./plan.js";
+import { serializePlan } from "./serialize/index.js";
+/** Thrown when a plan needs the interpreter at runtime (islands/fallbacks). */
+export class StandaloneUnsupportedError extends Error {
+}
+// Helper preamble: compiler-controlled structural code (never
+// schema-derived), semantics mirrored 1:1 from @json-schema-engine/core — see the drift
+// guards above. h_rx mirrors core's schemaRegExp (u-flag with fallback).
+/**
+ * The standalone helper preamble, exported so standalone.test.ts can compare
+ * each helper against its core original over a vector corpus (the drift
+ * guard the header describes). Not part of the public API surface.
+ */
+export const STANDALONE_PREAMBLE = `// Generated by @json-schema-engine/compiler (standalone mode). Self-contained; no imports.
+const h_obj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const h_int = (v) => typeof v === "number" && Number.isInteger(v);
+const h_hop = Object.prototype.hasOwnProperty;
+const h_s0 = [];
+// Mirrors core's MaxDepthExceededError, which the interpreter and every
+// runtime-compiled artifact throw for this bound. Self-contained emission
+// cannot share core's class object, so \`instanceof\` against it is false
+// here by construction; \`constructor.name\` is the discriminator a
+// standalone consumer has. Throwing RangeError instead would be worse than
+// imprecise: core converts a native stack RangeError INTO this class so a
+// depth failure is never uncatchable by type, and reusing RangeError for
+// the bound makes "schema too deep" and "blew the native stack"
+// indistinguishable.
+class MaxDepthExceededError extends Error {}
+const h_rx = (source) => {
+  try {
+    return new RegExp(source, "u");
+  } catch {
+    return new RegExp(source);
+  }
+};
+const h_eq = (a, b) => {
+  if (a === b) return true;
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) if (!h_eq(a[i], b[i])) return false;
+    return true;
+  }
+  if (h_obj(a)) {
+    if (!h_obj(b)) return false;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length) return false;
+    for (const k of keys) {
+      if (!h_hop.call(b, k) || !h_eq(a[k], b[k])) return false;
+    }
+    return true;
+  }
+  return false;
+};
+const h_ck = (v) => {
+  if (v === null || typeof v !== "object") return JSON.stringify(v);
+  if (Array.isArray(v)) return "[" + v.map(h_ck).join(",") + "]";
+  const keys = Object.keys(v).sort();
+  return (
+    "{" +
+    keys.map((k) => JSON.stringify(k) + ":" + h_ck(v[k])).join(",") +
+    "}"
+  );
+};
+const h_dup = (items) => {
+  const seen = new Map();
+  for (let i = 0; i < items.length; i++) {
+    const key = h_ck(items[i]);
+    const bucket = seen.get(key);
+    if (bucket === undefined) {
+      seen.set(key, [i]);
+      continue;
+    }
+    for (const j of bucket) if (h_eq(items[j], items[i])) return true;
+    bucket.push(i);
+  }
+  return false;
+};
+const h_cpl = (s) => {
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    n++;
+    const c = s.charCodeAt(i);
+    if (c >= 0xd800 && c <= 0xdbff) i++;
+  }
+  return n;
+};
+const h_esc = (s) => s.replace(/~/g, "~0").replace(/\\//g, "~1");
+const h_digits = (n) => {
+  if (!Number.isFinite(n)) return 0;
+  const s = Math.abs(n).toString();
+  const eIndex = s.indexOf("e");
+  if (eIndex !== -1) {
+    const mantissa = s.slice(0, eIndex);
+    const exponent = Number(s.slice(eIndex + 1));
+    const dot = mantissa.indexOf(".");
+    const mantissaDigits = dot === -1 ? 0 : mantissa.length - dot - 1;
+    return Math.max(0, mantissaDigits - exponent);
+  }
+  const dot = s.indexOf(".");
+  return dot === -1 ? 0 : s.length - dot - 1;
+};
+const h_mof = (instance, divisor) => {
+  const scale = 10 ** Math.max(h_digits(instance), h_digits(divisor));
+  const scaledInstance = instance * scale;
+  const scaledDivisor = divisor * scale;
+  if (Number.isFinite(scaledInstance) && Number.isFinite(scaledDivisor)) {
+    return Math.round(scaledInstance) % Math.round(scaledDivisor) === 0;
+  }
+  const quotient = instance / divisor;
+  return Number.isFinite(quotient) && Number.isInteger(quotient);
+};
+`;
+/**
+ * Emit a self-contained ES module validating against one registered,
+ * fully-static schema. The module's default export is
+ * `validate(instance): boolean`.
+ * @throws StandaloneUnsupportedError when the plan contains interpreted
+ * units — use the interpreter (CSP) or runtime compilation (no CSP).
+ */
+export function emitStandalone(engine, schemaUri, options = {}) {
+    const plan = buildPlan(engine, schemaUri);
+    if (plan.targets.length > 0) {
+        const causes = [...new Set(plan.targets.map((t) => t.cause))].join(", ");
+        throw new StandaloneUnsupportedError(`schema '${schemaUri}' needs the interpreter at runtime (${causes}); ` +
+            "standalone emission covers fully static schemas only");
+    }
+    // Format assertions resolve through the engine's format table (predicates
+    // like IDNA that a zero-import module cannot duplicate); a format-bearing
+    // schema stays on the interpreter (CSP) or runtime compilation (no CSP).
+    if (plan.formats.length > 0) {
+        throw new StandaloneUnsupportedError(`schema '${schemaUri}' asserts formats (${plan.formats.join(", ")}); ` +
+            "standalone emission cannot carry the engine's format predicates");
+    }
+    // A tracked consumer's runtime coverage channel binds the harvest/fold
+    // helpers the standalone preamble deliberately omits (phase B is runtime
+    // mode only); the interpreter is the CSP-safe tier for these schemas.
+    if ([...plan.units.values()].some((u) => u.tracking)) {
+        throw new StandaloneUnsupportedError(`schema '${schemaUri}' has a dynamic-coverage consumer needing runtime ` +
+            "tracking; standalone emission covers static-coverage schemas only");
+    }
+    const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const depthPreamble = `const h_maxd = ${String(maxDepth)};\n` +
+        `const h_deep = () => { throw new MaxDepthExceededError("compiled evaluation exceeds maxDepth (${String(maxDepth)})"); };\n`;
+    return (STANDALONE_PREAMBLE +
+        depthPreamble +
+        serializePlan(plan, engine.registry, { mode: "standalone" }));
+}
+//# sourceMappingURL=standalone.js.map

package/dist/standalone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.js","sourceRoot":"","sources":["../src/standalone.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,yEAAyE;AACzE,uEAAuE;AACvE,0BAA0B;AAC1B,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,4EAA4E;AAC5E,wFAAwF;AACxF,yEAAyE;AACzE,wBAAwB;AACxB,EAAE;AACF,kEAAkE;AAClE,qEAAqE;AACrE,4EAA4E;AAC5E,sEAAsE;AACtE,mBAAmB;AAEnB,OAAO,EAAE,iBAAiB,EAAe,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,+EAA+E;AAC/E,MAAM,OAAO,0BAA2B,SAAQ,KAAK;CAAG;AAExD,8DAA8D;AAC9D,wFAAwF;AACxF,yEAAyE;AACzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkGlC,CAAC;AAQF;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,SAAiB,EACjB,UAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,SAAS,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC1C,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACzE,MAAM,IAAI,0BAA0B,CAClC,WAAW,SAAS,uCAAuC,MAAM,KAAK;YACpE,sDAAsD,CACzD,CAAC;IACJ,CAAC;IACD,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,0BAA0B,CAClC,WAAW,SAAS,sBAAsB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YACpE,iEAAiE,CACpE,CAAC;IACJ,CAAC;IACD,uEAAuE;IACvE,yEAAyE;IACzE,sEAAsE;IACtE,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,0BAA0B,CAClC,WAAW,SAAS,oDAAoD;YACtE,mEAAmE,CACtE,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,MAAM,aAAa,GACjB,kBAAkB,MAAM,CAAC,QAAQ,CAAC,KAAK;QACvC,iGAAiG,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC;IAC/H,OAAO,CACL,mBAAmB;QACnB,aAAa;QACb,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAC7D,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@json-schema-engine/compiler",
+  "version": "0.0.1",
+  "description": "Compiler tier: emits specialized validators from @json-schema-engine/core registrations, trampolining to the interpreter for dynamic islands (DESIGN.md M6)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "jse-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@json-schema-engine/core": "^0.0.1"
+  },
+  "devDependencies": {
+    "@json-schema-engine/formats": "^0.0.1"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/handrews/json-schema-engine.git",
+    "directory": "packages/compiler"
+  }
+}

package/src/emit.ts

@@ -0,0 +1,196 @@
+// The gated code serializer (D20/M6): the ONLY module that assembles
+// JavaScript source text. Every value that reaches emitted code passes
+// through a typed wrapper here, so schema-derived data is escaped by
+// construction — raw string concatenation of untrusted input is impossible.
+//
+// The `js` tag accepts only CodeChunk arguments (the branded outputs of the
+// wrappers below); a bare string throws. Template static parts are literals
+// by grammar. Downstream modules traffic in CodeChunk, never string, so the
+// type system carries the guarantee and ESLint fences the one escape hatch.
+
+import type { JsonValue } from "@json-schema-engine/core";
+
+const BRAND = Symbol("CodeChunk");
+
+/** An opaque, already-escaped fragment of emitted JavaScript. */
+export interface CodeChunk {
+  readonly [BRAND]: true;
+  readonly text: string;
+}
+
+const chunk = (text: string): CodeChunk => ({ [BRAND]: true, text });
+
+const isChunk = (v: unknown): v is CodeChunk =>
+  typeof v === "object" && v !== null && BRAND in v;
+
+/**
+ * Tagged template for emitted code. Interpolations MUST be CodeChunks (from
+ * {@link id}/{@link str}/{@link num}/{@link json}/{@link regexTest}/{@link raw}/
+ * {@link frag}); anything else throws, so a stray schema string can never be
+ * spliced verbatim.
+ */
+export function js(
+  strings: TemplateStringsArray,
+  ...parts: readonly CodeChunk[]
+): CodeChunk {
+  let out = strings[0]!;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!isChunk(part)) {
+      throw new TypeError(
+        `js\`\` interpolation ${i} is not a CodeChunk; wrap it (id/str/num/json/…)`,
+      );
+    }
+    out += part.text + strings[i + 1]!;
+  }
+  return chunk(out);
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const RESERVED = new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "export",
+  "extends",
+  "false",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "null",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "true",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+  "let",
+  "static",
+  "enum",
+  "await",
+  "implements",
+  "package",
+  "protected",
+  "interface",
+  "private",
+  "public",
+]);
+
+/**
+ * A machine-generated identifier. NEVER pass schema-derived text here —
+ * identifiers come from the compiler's own counters and a fixed helper
+ * vocabulary. Rejects anything that is not a plain identifier or is reserved.
+ */
+export function id(name: string): CodeChunk {
+  if (!IDENT.test(name) || RESERVED.has(name)) {
+    throw new TypeError(`unsafe identifier '${name}'`);
+  }
+  return chunk(name);
+}
+
+/** A JavaScript string literal, escaped for embedding (incl. U+2028/U+2029). */
+export function str(value: string): CodeChunk {
+  const json = JSON.stringify(value);
+  // JSON.stringify leaves U+2028/U+2029 literal; they are valid in JSON but
+  // were line terminators in pre-ES2019 JS and still trip some tooling.
+  return chunk(
+    json.replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"),
+  );
+}
+
+/** A numeric literal, JSON-sourced (finite), with an explicit -0 branch. */
+export function num(value: number): CodeChunk {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`non-finite numeric constant ${String(value)}`);
+  }
+  if (Object.is(value, -0)) return chunk("-0");
+  return chunk(String(value));
+}
+
+/** True when `value` or any nested value is an object with a "__proto__" own key. */
+function hasProtoKey(value: JsonValue): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some(hasProtoKey);
+  if (Object.hasOwn(value, "__proto__")) return true;
+  return Object.values(value).some(hasProtoKey);
+}
+
+/**
+ * A JSON constant. Emits an object/array literal only when no nested own key
+ * is `__proto__` (a literal `{"__proto__": …}` sets the prototype in source,
+ * unlike JSON.parse); otherwise routes through a JSON.parse call so the
+ * prototype is never touched.
+ */
+export function json(value: JsonValue): CodeChunk {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "number") return num(value);
+    if (typeof value === "string") return str(value);
+    return chunk(String(value)); // boolean
+  }
+  if (hasProtoKey(value)) {
+    return chunk(`JSON.parse(${str(JSON.stringify(value)).text})`);
+  }
+  if (Array.isArray(value)) {
+    return chunk(`[${value.map((v) => json(v).text).join(",")}]`);
+  }
+  const members = Object.entries(value).map(
+    ([k, v]) => `${str(k).text}:${json(v).text}`,
+  );
+  return chunk(`{${members.join(",")}}`);
+}
+
+/**
+ * A regex membership test against a hoisted, pre-compiled pattern. The
+ * pattern source is escaped as a string literal; the compiled RegExp is
+ * supplied at runtime through the artifact's regex table (never
+ * `RegExp.prototype.toString`, never inline `/…/`).
+ */
+export function regexTest(
+  tableRef: CodeChunk,
+  source: string,
+  target: CodeChunk,
+): CodeChunk {
+  return chunk(`${tableRef.text}[${str(source).text}].test(${target.text})`);
+}
+
+/** Splice previously built chunks (already escaped). */
+export function frag(...chunks: readonly CodeChunk[]): CodeChunk {
+  return chunk(chunks.map((c) => c.text).join(""));
+}
+
+/** Join chunks with a separator (both already escaped). */
+export function join(sep: string, chunks: readonly CodeChunk[]): CodeChunk {
+  return chunk(chunks.map((c) => c.text).join(sep));
+}
+
+/**
+ * Internal escape hatch for structural code the compiler itself controls
+ * (keywords, operators) — NOT for schema-derived data. Guarded by ESLint so
+ * only emit-internal call sites use it. Kept explicit so audits grep one name.
+ */
+export function raw(controlledSource: string): CodeChunk {
+  return chunk(controlledSource);
+}
+
+/** The assembled source text of a chunk. */
+export const render = (c: CodeChunk): string => c.text;

package/src/explain.ts

@@ -0,0 +1,67 @@
+// Compilation-plan diagnostics (deferred-register item, built for the
+// plan-census gates): interpreted fallback is always CORRECT, so a
+// regression that silently flips units static→interpreted passes every
+// suite/differential/fuzz gate — only a census over these summaries
+// notices. The summarizer is pure read-only projection of plan data.
+
+import type { CompilationPlan, FallbackCause } from "./plan.js";
+
+/** Aggregate view of one {@link CompilationPlan}'s unit classification. */
+export interface CompilationExplanation {
+  /** Every planned unit, static or not. */
+  totalUnits: number;
+  staticUnits: number;
+  interpretedUnits: number;
+  /** Interpreted-unit count per fallback cause; absent cause = zero. */
+  causes: Partial<Record<FallbackCause, number>>;
+  /**
+   * Canonical `baseUri#pointer` keys of the interpreted units — for
+   * diagnosis when a census count assertion fails, not for pinning (key
+   * lists churn on suite reorganization without adding regression signal).
+   */
+  interpretedKeys: string[];
+  /** Units whose apply paths can reach an interpreted unit. */
+  reachesInterpretedCount: number;
+  /**
+   * Static consumer units compiled with runtime evaluated-set tracking (phase
+   * B) — the flag-mode alternative to interpreting a dynamic-coverage consumer.
+   */
+  trackingUnits: number;
+  /** Static units in some tracked unit's in-place coverage region (phase B). */
+  regionUnits: number;
+}
+
+/** Summarizes a plan's classification for census gates and diagnostics. */
+export function explainCompilation(
+  plan: CompilationPlan,
+): CompilationExplanation {
+  const causes: Partial<Record<FallbackCause, number>> = {};
+  const interpretedKeys: string[] = [];
+  let staticUnits = 0;
+  let reachesInterpretedCount = 0;
+  let trackingUnits = 0;
+  let regionUnits = 0;
+  for (const unit of plan.units.values()) {
+    if (unit.kind === "static") staticUnits++;
+    else {
+      interpretedKeys.push(unit.key);
+      if (unit.cause !== undefined) {
+        causes[unit.cause] = (causes[unit.cause] ?? 0) + 1;
+      }
+    }
+    if (unit.reachesInterpreted) reachesInterpretedCount++;
+    if (unit.tracking) trackingUnits++;
+    if (unit.inRegion) regionUnits++;
+  }
+  interpretedKeys.sort();
+  return {
+    totalUnits: plan.units.size,
+    staticUnits,
+    interpretedUnits: plan.units.size - staticUnits,
+    causes,
+    interpretedKeys,
+    reachesInterpretedCount,
+    trackingUnits,
+    regionUnits,
+  };
+}