@metaobjectsdev/render 0.7.0-rc.9 → 0.8.0-rc.1

package/src/recover/coerce.ts

@@ -0,0 +1,141 @@
+// Stage 7: canonicalize a raw scalar string per its FieldSpec. Returns the MALFORMED
+// sentinel when present-but-uncoercible. Mirrors Java Coerce.
+//
+// Tier-2 divergence (documented, parity with the C# port's KNOWN_GAPS): JS has one
+// number type. INT/LONG both truncate toward zero via Math.trunc and return `number`.
+// Coercion uses Number(...) + Number.isFinite, NOT Java's Double.parseDouble — so JS
+// does NOT accept Java's numeric suffixes ("42d"/"42f") or hex-float literals. The
+// load-bearing contract (finite-only acceptance; NaN/±Infinity → MALFORMED; numeric
+// classification) is identical across ports.
+
+import { FieldKind, Tolerance } from "./types.js";
+import type { FieldSpec, RecoverOptions, RecoveryReport } from "./types.js";
+
+/** Sentinel: the value was present but could not be coerced to the declared kind/vocabulary. */
+export const MALFORMED: unique symbol = Symbol("recover.coerce.MALFORMED");
+
+export function coerceValue(
+  raw: string | null,
+  spec: FieldSpec,
+  opts: RecoverOptions,
+  fieldPath: string,
+  report: RecoveryReport,
+): unknown | typeof MALFORMED {
+  if (raw == null) return MALFORMED;
+
+  if (opts.onField != null) {
+    const hooked = opts.onField(fieldPath, raw, spec);
+    if (hooked != null) {
+      report.addCoercion({ fieldPath, from: raw, to: stringify(hooked), kind: "onField" });
+      return hooked;
+    }
+  }
+
+  // Per-field runtime normalizer (bounded 20% surface). Keyed by field path, then simple name.
+  const norm = opts.normalizers[fieldPath] ?? opts.normalizers[spec.name];
+  if (norm != null) {
+    const normalized = norm(raw);
+    if (normalized != null) {
+      report.addCoercion({ fieldPath, from: raw, to: stringify(normalized), kind: "normalizer" });
+      return normalized;
+    }
+  }
+
+  const ci = opts.tolerance !== Tolerance.STRICT;
+  switch (spec.kind) {
+    case FieldKind.ENUM:
+      return coerceEnum(raw, spec, opts, fieldPath, report, ci);
+    case FieldKind.INT:
+    case FieldKind.LONG:
+      return coerceInt(raw, spec, fieldPath, report);
+    case FieldKind.DOUBLE:
+      return coerceDouble(raw, spec, fieldPath, report);
+    case FieldKind.BOOLEAN:
+      return coerceBool(raw, ci);
+    default:
+      return raw;
+  }
+}
+
+function coerceEnum(
+  raw: string,
+  spec: FieldSpec,
+  opts: RecoverOptions,
+  path: string,
+  report: RecoveryReport,
+  ci: boolean,
+): unknown | typeof MALFORMED {
+  if (spec.enumValues != null) {
+    for (const v of spec.enumValues) {
+      if (v === raw) return v;
+      if (ci && v.toLowerCase() === raw.toLowerCase()) {
+        report.addCoercion({ fieldPath: path, from: raw, to: v, kind: "case" });
+        return v;
+      }
+    }
+  }
+  const schemaTarget = spec.enumAlias == null ? undefined : spec.enumAlias[raw];
+  const runtimeTarget = opts.aliases[raw];
+  if (runtimeTarget != null) {
+    const kind = schemaTarget != null && schemaTarget !== runtimeTarget ? "runtime-alias-override" : "alias";
+    report.addCoercion({ fieldPath: path, from: raw, to: runtimeTarget, kind });
+    return runtimeTarget;
+  }
+  if (schemaTarget != null) {
+    report.addCoercion({ fieldPath: path, from: raw, to: schemaTarget, kind: "alias" });
+    return schemaTarget;
+  }
+  return MALFORMED;
+}
+
+function coerceInt(raw: string, spec: FieldSpec, path: string, report: RecoveryReport): unknown | typeof MALFORMED {
+  const n = parseFiniteNumber(raw);
+  if (n === null) return MALFORMED;
+  return clamp(Math.trunc(n), spec, path, report);
+}
+
+function coerceDouble(raw: string, spec: FieldSpec, path: string, report: RecoveryReport): unknown | typeof MALFORMED {
+  const n = parseFiniteNumber(raw);
+  if (n === null) return MALFORMED;
+  return clamp(n, spec, path, report);
+}
+
+/** Parse a trimmed numeric string; null if empty, non-numeric, or non-finite (NaN/±Infinity). */
+function parseFiniteNumber(raw: string): number | null {
+  const t = raw.trim();
+  if (t.length === 0) return null;
+  // Reject JS-only radix-prefixed literals (0x.., 0b.., 0o..) that Number() would
+  // accept but Java/C# numeric parsing rejects → MALFORMED. Keeps cross-port parity.
+  if (/^[+-]?0[xXbBoO]/.test(t)) return null;
+  const n = Number(t); // Number("") === 0, hence the empty guard above
+  return Number.isFinite(n) ? n : null;
+}
+
+function clamp(n: number, spec: FieldSpec, path: string, report: RecoveryReport): number {
+  let c = n;
+  if (spec.min != null && c < spec.min) c = spec.min;
+  if (spec.max != null && c > spec.max) c = spec.max;
+  if (c !== n) report.addCoercion({ fieldPath: path, from: stringify(n), to: stringify(c), kind: "clamp" });
+  return c;
+}
+
+function coerceBool(raw: string, ci: boolean): boolean | typeof MALFORMED {
+  const t = ci ? raw.trim().toLowerCase() : raw.trim();
+  switch (t) {
+    case "true":
+    case "yes":
+    case "1":
+      return true;
+    case "false":
+    case "no":
+    case "0":
+      return false;
+    default:
+      return MALFORMED;
+  }
+}
+
+/** Canonical string form (locale-independent), mirroring Java String.valueOf for the corpus. */
+function stringify(v: unknown): string {
+  return String(v);
+}

package/src/recover/json-forgiving-reader.ts

@@ -0,0 +1,167 @@
+// Stage-4 tolerant JSON reader for the bounded corpus malformation set. Never throws.
+// Mirrors Java JsonForgivingReader. The no-hang + TRUNCATED contracts are load-bearing.
+
+/** Sentinel: a key appeared in the text but its value was empty/cut-off (present-but-garbled). */
+export const TRUNCATED: unique symbol = Symbol("recover.json.TRUNCATED");
+
+/** A character is JSON-insignificant whitespace. Mirrors Java Character.isWhitespace closely enough for the corpus. */
+function isWhitespace(c: string): boolean {
+  return c === " " || c === "\t" || c === "\n" || c === "\r" || c === "\f" || c === "\v" || /\s/.test(c);
+}
+
+function isLetterOrDigitOrUnderscore(c: string): boolean {
+  return /[A-Za-z0-9_]/.test(c);
+}
+
+class Reader {
+  private s = "";
+  private i = 0;
+
+  read(span: string | null | undefined): Record<string, unknown> {
+    this.s = span ?? "";
+    this.i = 0;
+    this.ws();
+    if (this.i >= this.s.length || this.s.charAt(this.i) !== "{") return {};
+    const o = this.readValue();
+    return isPlainObject(o) ? (o as Record<string, unknown>) : {};
+  }
+
+  private readValue(): unknown {
+    this.ws();
+    if (this.i >= this.s.length) return null;
+    const c = this.s.charAt(this.i);
+    if (c === "{") return this.readObject();
+    if (c === "[") return this.readArray();
+    if (c === '"' || c === "'") return this.readString(c);
+    return this.readBareScalar();
+  }
+
+  private readObject(): Record<string, unknown> {
+    const m: Record<string, unknown> = {};
+    this.i++; // consume '{'
+    for (;;) {
+      this.ws();
+      if (this.i >= this.s.length) return m; // truncation
+      if (this.s.charAt(this.i) === "}") {
+        this.i++;
+        return m;
+      }
+      const key = this.readKey();
+      if (key === null) return m; // truncation mid-key
+      this.ws();
+      if (this.i >= this.s.length || this.s.charAt(this.i) !== ":") return m; // truncation before value
+      this.i++; // consume ':'
+      this.ws();
+      if (this.i >= this.s.length) {
+        m[key] = TRUNCATED; // value cut off at EOF → present-but-garbled
+        return m;
+      }
+      const v = this.readValue();
+      if (v === null) {
+        // present key, empty/zero-width value → present-but-garbled
+        m[key] = TRUNCATED;
+        this.ws();
+        if (this.i < this.s.length && this.s.charAt(this.i) === ",") {
+          this.i++;
+          continue;
+        }
+        if (this.i < this.s.length && this.s.charAt(this.i) === "}") this.i++;
+        return m;
+      }
+      m[key] = v;
+      this.ws();
+      if (this.i < this.s.length && this.s.charAt(this.i) === ",") this.i++; // optional/trailing comma
+    }
+  }
+
+  private readArray(): unknown[] {
+    const xs: unknown[] = [];
+    this.i++; // consume '['
+    for (;;) {
+      this.ws();
+      if (this.i >= this.s.length) return xs;
+      if (this.s.charAt(this.i) === "]") {
+        this.i++;
+        return xs;
+      }
+      if (this.s.charAt(this.i) === "}") {
+        this.i++;
+        return xs;
+      } // malformed brace-close terminates array
+      const v = this.readValue();
+      if (v === null) {
+        // zero-width / no value → stop (no spin)
+        this.ws();
+        if (this.i < this.s.length && (this.s.charAt(this.i) === "]" || this.s.charAt(this.i) === "}")) this.i++;
+        return xs;
+      }
+      xs.push(v);
+      this.ws();
+      if (this.i < this.s.length && this.s.charAt(this.i) === ",") this.i++;
+      else if (this.i < this.s.length && this.s.charAt(this.i) === "]") {
+        this.i++;
+        return xs;
+      } else if (this.i >= this.s.length) return xs;
+      else return xs; // any other non-separator char → stop
+    }
+  }
+
+  private readKey(): string | null {
+    this.ws();
+    if (this.i >= this.s.length) return null;
+    const c = this.s.charAt(this.i);
+    if (c === '"' || c === "'") return this.readString(c);
+    const start = this.i;
+    while (this.i < this.s.length && isLetterOrDigitOrUnderscore(this.s.charAt(this.i))) this.i++;
+    return this.i > start ? this.s.substring(start, this.i) : null;
+  }
+
+  private readString(quoteChar: string): string {
+    this.i++; // opening quote
+    let sb = "";
+    let esc = false;
+    while (this.i < this.s.length) {
+      const c = this.s.charAt(this.i++);
+      if (esc) {
+        sb += unescape(c);
+        esc = false;
+      } else if (c === "\\") esc = true;
+      else if (c === quoteChar) return sb;
+      else sb += c;
+    }
+    return sb; // unterminated string → return what we have
+  }
+
+  private readBareScalar(): string | null {
+    const start = this.i;
+    while (this.i < this.s.length && ",}]".indexOf(this.s.charAt(this.i)) < 0) this.i++;
+    const result = this.s.substring(start, this.i).trim();
+    return result.length === 0 ? null : result; // null = no token read (zero-width)
+  }
+
+  private ws(): void {
+    while (this.i < this.s.length && isWhitespace(this.s.charAt(this.i))) this.i++;
+  }
+}
+
+function unescape(c: string): string {
+  switch (c) {
+    case "n":
+      return "\n";
+    case "t":
+      return "\t";
+    case "r":
+      return "\r";
+    default:
+      return c;
+  }
+}
+
+function isPlainObject(o: unknown): boolean {
+  return typeof o === "object" && o !== null && !Array.isArray(o);
+}
+
+/** Parse a tolerant JSON object span into a forgiving record. Never throws. */
+export function readJson(span: string | null | undefined): Record<string, unknown> {
+  return new Reader().read(span);
+}

package/src/recover/locate.ts

@@ -0,0 +1,72 @@
+// Stages 2-3: isolate and select the payload root span.
+// Selection rule: first-closed-else-first-open. Mirrors Java Locate.
+
+/** Escape regex metacharacters (equivalent of Java Pattern.quote). */
+function quote(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** First balanced {...}; if none closes, first '{' to end; null if no '{'. */
+export function locateJson(text: string | null | undefined): string | null {
+  if (text == null) return null;
+  let firstOpen = -1;
+  for (let i = 0; i < text.length; i++) {
+    if (text.charAt(i) === "{") {
+      if (firstOpen < 0) firstOpen = i;
+      const end = scanBalanced(text, i);
+      if (end >= 0) return text.substring(i, end + 1);
+    }
+  }
+  return firstOpen < 0 ? null : text.substring(firstOpen);
+}
+
+/** Returns index of the matching '}', or -1 if unterminated. String-aware. */
+function scanBalanced(s: string, open: number): number {
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = open; i < s.length; i++) {
+    const c = s.charAt(i);
+    if (inStr) {
+      if (esc) esc = false;
+      else if (c === "\\") esc = true;
+      else if (c === '"') inStr = false;
+      continue;
+    }
+    if (c === '"') inStr = true;
+    else if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+  }
+  return -1;
+}
+
+/** Span of <root>...</root>; if close absent, opener to end; null if no opener. */
+export function locateXml(
+  text: string | null | undefined,
+  rootName: string | null | undefined,
+  caseInsensitive: boolean,
+): string | null {
+  if (text == null || rootName == null) return null;
+  const flags = caseInsensitive ? "i" : "";
+  const open = new RegExp(`<${quote(rootName)}(\\s[^>]*)?>`, flags).exec(text);
+  if (open == null) return null;
+  const start = open.index;
+  const openEnd = open.index + open[0].length;
+
+  const closeRe = new RegExp(`</${quote(rootName)}\\s*>`, flags);
+  closeRe.lastIndex = openEnd;
+  // Search for the close tag at-or-after the opener's end (Java close.find(open.end())).
+  const close = matchFrom(closeRe, text, openEnd);
+  if (close != null) return text.substring(start, close.index + close[0].length);
+  return text.substring(start);
+}
+
+/** Find the first regex match at index >= `from` (emulates Java Matcher.find(int)). */
+function matchFrom(re: RegExp, text: string, from: number): RegExpExecArray | null {
+  const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+  g.lastIndex = from;
+  return g.exec(text);
+}

package/src/recover/recover-map.ts

@@ -0,0 +1,39 @@
+// Null-safe coercions from a RecoverOutcome data map onto typed values. Generated
+// recover(...) calls these. Mirrors Java RecoverMap.
+//
+// Tier-2 divergence: JS has one number type, so asInt/asLong both return `number | null`
+// and truncate toward zero via Math.trunc (Java intValue()/longValue() also truncate).
+// The numeric helpers gate on actual numbers (mirroring Java `instanceof Number`): a
+// non-numeric string or a boolean returns null rather than coercing.
+
+export function asString(d: Record<string, unknown>, k: string): string | null {
+  const v = d[k];
+  if (v == null) return null;
+  return typeof v === "string" ? v : String(v);
+}
+
+export function asInt(d: Record<string, unknown>, k: string): number | null {
+  const v = d[k];
+  return typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : null;
+}
+
+export function asLong(d: Record<string, unknown>, k: string): number | null {
+  const v = d[k];
+  return typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : null;
+}
+
+export function asDouble(d: Record<string, unknown>, k: string): number | null {
+  const v = d[k];
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+export function asBool(d: Record<string, unknown>, k: string): boolean | null {
+  const v = d[k];
+  return typeof v === "boolean" ? v : null;
+}
+
+export function asStringList(d: Record<string, unknown>, k: string): (string | null)[] | null {
+  const v = d[k];
+  if (!Array.isArray(v)) return null;
+  return v.map((e) => (e == null ? null : typeof e === "string" ? e : String(e)));
+}

package/src/recover/recover.ts

@@ -0,0 +1,146 @@
+// Public entry point. Runs the staged pipeline; NEVER throws. Mirrors Java Recover.
+
+import {
+  Format,
+  FieldKind,
+  FieldRecovery,
+  Tolerance,
+  normalizeOptions,
+} from "./types.js";
+import type { FieldSpec, RecoverOptions, RecoverOutcome, RecoverSchema } from "./types.js";
+import { RecoveryReport } from "./types.js";
+import { strip } from "./strip.js";
+import { locateJson, locateXml } from "./locate.js";
+import { readJson, TRUNCATED } from "./json-forgiving-reader.js";
+import { readXml } from "./xml-forgiving-reader.js";
+import { coerceValue, MALFORMED } from "./coerce.js";
+
+/** The forgiving entry point: recover dirty `text` against `schema`. Never throws. */
+export function recover(
+  text: string | null | undefined,
+  schema: RecoverSchema,
+  opts?: Partial<RecoverOptions> | null,
+): RecoverOutcome {
+  const o = normalizeOptions(opts);
+  const report = new RecoveryReport();
+  const data: Record<string, unknown> = {};
+
+  const stripped = strip(text);
+  const ci = o.tolerance !== Tolerance.STRICT;
+
+  const span =
+    schema.format === Format.JSON ? locateJson(stripped) : locateXml(stripped, schema.rootName, ci);
+
+  let raw: Record<string, unknown>;
+  if (span == null) {
+    raw = {};
+  } else if (schema.format === Format.JSON) {
+    raw = readJson(span);
+  } else {
+    raw = readXml(span, ci);
+  }
+
+  if (isEmptyRecord(raw) && (stripped.length === 0 || span == null)) {
+    report.markEmpty();
+  }
+
+  extract(schema.fields, raw, "", data, report, o, ci);
+  return { data, report };
+}
+
+function extract(
+  fields: readonly FieldSpec[],
+  raw: Record<string, unknown>,
+  prefix: string,
+  data: Record<string, unknown>,
+  report: RecoveryReport,
+  o: RecoverOptions,
+  ci: boolean,
+): void {
+  for (const f of fields) {
+    const path = prefix.length === 0 ? f.name : `${prefix}.${f.name}`;
+    const present = lookup(raw, f.name, ci);
+    if (present === undefined) {
+      report.set(path, f.required ? FieldRecovery.LOST_REQUIRED : FieldRecovery.LOST_OPTIONAL);
+      continue;
+    }
+    if (present === TRUNCATED) {
+      // present-but-garbled (empty/cut-off value)
+      report.set(path, FieldRecovery.MALFORMED);
+      continue;
+    }
+    if (f.array) {
+      // An array field: a single non-list value is treated as a one-element array
+      // (e.g. a single repeated-XML tag). Each element is coerced/recursed independently.
+      const elements: unknown[] = Array.isArray(present) ? present : [present];
+      const out: unknown[] = [];
+      let anyMalformed = false;
+      for (let idx = 0; idx < elements.length; idx++) {
+        const v = extractValue(f, elements[idx], `${path}[${idx}]`, report, o, ci);
+        if (v === MALFORMED) anyMalformed = true;
+        else out.push(v);
+      }
+      // Cross-port contract: a MALFORMED array still places its successfully-coerced
+      // elements into data (partial recovery), UNLIKE a MALFORMED scalar which is absent.
+      data[f.name] = out;
+      report.set(path, anyMalformed ? FieldRecovery.MALFORMED : FieldRecovery.RECOVERED);
+      continue;
+    }
+    if (Array.isArray(present)) {
+      // a list where a singular value was expected
+      report.set(path, FieldRecovery.MALFORMED);
+      continue;
+    }
+    const v = extractValue(f, present, path, report, o, ci);
+    if (v === MALFORMED) {
+      report.set(path, FieldRecovery.MALFORMED);
+    } else {
+      data[f.name] = v;
+      report.set(path, FieldRecovery.RECOVERED);
+    }
+  }
+}
+
+/** Coerce one (non-array) element: nested-object recursion or scalar coercion. Returns MALFORMED on failure. */
+function extractValue(
+  f: FieldSpec,
+  present: unknown,
+  path: string,
+  report: RecoveryReport,
+  o: RecoverOptions,
+  ci: boolean,
+): unknown | typeof MALFORMED {
+  if (f.kind === FieldKind.OBJECT) {
+    if (f.nested != null && isPlainObject(present)) {
+      const nestedData: Record<string, unknown> = {};
+      extract(f.nested.fields, present as Record<string, unknown>, path, nestedData, report, o, ci);
+      return nestedData;
+    }
+    return MALFORMED; // object expected but scalar/non-map present
+  }
+  const rawStr = typeof present === "string" ? present : stringifyScalar(present);
+  return coerceValue(rawStr, f, o, path, report);
+}
+
+/** Case-folding lookup honoring tolerance. Returns `undefined` for absent (mirrors Java null). */
+function lookup(raw: Record<string, unknown>, name: string, ci: boolean): unknown {
+  if (Object.prototype.hasOwnProperty.call(raw, name)) return raw[name];
+  if (ci) {
+    const lower = name.toLowerCase();
+    for (const k of Object.keys(raw)) if (k.toLowerCase() === lower) return raw[k];
+  }
+  return undefined;
+}
+
+function isPlainObject(o: unknown): boolean {
+  return typeof o === "object" && o !== null && !Array.isArray(o);
+}
+
+function isEmptyRecord(o: Record<string, unknown>): boolean {
+  return Object.keys(o).length === 0;
+}
+
+/** Mirror Java String.valueOf for non-string forgiving-reader scalars. */
+function stringifyScalar(v: unknown): string {
+  return String(v);
+}

package/src/recover/strip.ts

@@ -0,0 +1,17 @@
+// Stage 1: remove markdown code-fence markers. Prose around the payload is left for Locate.
+// Mirrors Java Strip.
+
+// Captures the body inside a fenced block; optional language tag (json/xml/etc) is dropped.
+const FENCE = /```[a-zA-Z0-9_-]*\s*\r?\n([\s\S]*?)\r?\n?```/;
+
+export function strip(raw: string | null | undefined): string {
+  if (raw == null) return "";
+  const m = FENCE.exec(raw);
+  if (m && m.index >= 0) {
+    const before = raw.substring(0, m.index);
+    const body = m[1] ?? "";
+    const after = raw.substring(m.index + m[0].length);
+    return (before + body + after).trim();
+  }
+  return raw.trim();
+}