rip-lang 3.15.4 → 3.16.1

package/src/sourcemaps.js

@@ -198,4 +198,280 @@ function buildLineMap(reverseMap, mapJSON, headerLines) {
   return { srcToGen, genToSrc, srcColToGen };
 }
 
-export { SourceMapGenerator, vlqEncode, vlqDecode, parseSourceMap, buildLineMap };
+// =============================================================================
+// Multi-chunk merger.
+//
+// Concatenates N JS chunks (each with its own inline source map) into one
+// JS string + one merged source map. Used by `processRipScripts` in
+// browser.js to produce a single eval'd chunk that DevTools can map back
+// to multiple original `.rip` files.
+//
+// Why this exists: DevTools only honours the LAST `//# sourceMappingURL`
+// inside one eval'd chunk. So when N chunks share lexical scope (concat
+// + single eval, the bundle-no-router execution model), we must produce
+// ONE map that covers all N sources. Source Map V3 supports this natively
+// via a multi-entry `sources` / `sourcesContent` array and source-index
+// fields in the VLQ mappings — every production JS bundler does this.
+//
+// Algorithm:
+//   1. Strip per-chunk `//# sourceMappingURL=` pragmas from each chunk's JS
+//   2. Decode each chunk's `mappings` to absolute coordinates
+//   3. Concatenate JS with `\n;\n` separators (statement-safe, +2 newlines
+//      between chunks)
+//   4. Offset each chunk's generated line numbers by the cumulative line
+//      count of preceding chunks + separators
+//   5. Dedupe `sources`, `sourcesContent`, `names` into merged arrays;
+//      remap each chunk's source-index / name-index fields
+//   6. Re-encode as relative VLQ across the full concatenated mapping
+// =============================================================================
+
+// `\n;\n` is statement-safe between chunks (the `;` ensures the previous
+// line's expression is terminated). Counts as 2 newlines for line-offset.
+const MERGE_SEPARATOR = '\n;\n';
+const MERGE_SEPARATOR_LINES = 2;
+
+// Strip a trailing `//# sourceMappingURL=...` pragma from a JS string so
+// concatenated chunks don't carry stray maps that DevTools would honor
+// in unexpected order. Returns { js, mapJSON } where mapJSON is the
+// JSON string extracted from the inline data URL (or null if no pragma).
+function extractInlineMap(js) {
+  const re = /\n?\/\/# sourceMappingURL=data:application\/json(?:;charset=[^;,]+)?;base64,([A-Za-z0-9+/=]+)\s*$/;
+  const m = js.match(re);
+  if (!m) return { js, mapJSON: null };
+  let mapJSON;
+  try {
+    // UTF-8-safe decode (counterpart of the encode in compiler.js).
+    const bin = atob(m[1]);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    mapJSON = new TextDecoder().decode(bytes);
+  } catch {
+    return { js: js.slice(0, m.index), mapJSON: null };
+  }
+  return { js: js.slice(0, m.index), mapJSON };
+}
+
+// Count the number of newline characters in a string. Used for line-offset
+// math when concatenating chunks.
+function countNewlines(str) {
+  let n = 0;
+  for (let i = 0; i < str.length; i++) if (str.charCodeAt(i) === 10) n++;
+  return n;
+}
+
+// Decode a Source Map V3 `mappings` field into an array of arrays of
+// absolute-coordinate segments. Each segment is one of:
+//   { genCol }                              — unmapped (1 field)
+//   { genCol, src, origLine, origCol }      — mapped (4 fields)
+//   { genCol, src, origLine, origCol, name } — mapped + name (5 fields)
+function decodeMappings(mappingsStr) {
+  const lines = mappingsStr.split(';');
+  const result = [];
+  let src = 0, origLine = 0, origCol = 0, nameIdx = 0;
+  for (const line of lines) {
+    const segs = [];
+    let genCol = 0;
+    if (line.length > 0) {
+      for (const segStr of line.split(',')) {
+        if (segStr.length === 0) continue;
+        const fields = vlqDecode(segStr);
+        genCol += fields[0];
+        if (fields.length === 1) {
+          segs.push({ genCol });
+        } else {
+          src += fields[1];
+          origLine += fields[2];
+          origCol += fields[3];
+          const seg = { genCol, src, origLine, origCol };
+          if (fields.length >= 5) {
+            nameIdx += fields[4];
+            seg.name = nameIdx;
+          }
+          segs.push(seg);
+        }
+      }
+    }
+    result.push(segs);
+  }
+  return result;
+}
+
+// Re-encode an array of arrays of absolute-coordinate segments back to
+// V3 `mappings` string. Counterpart of decodeMappings.
+function encodeMappings(perLineSegs) {
+  let prevGenCol = 0; // resets per line
+  let prevSrc = 0, prevOrigLine = 0, prevOrigCol = 0, prevNameIdx = 0;
+  const out = [];
+  for (const segs of perLineSegs) {
+    prevGenCol = 0;
+    const lineParts = [];
+    for (const seg of segs) {
+      if (seg.src == null) {
+        lineParts.push(vlqEncode(seg.genCol - prevGenCol));
+      } else {
+        let s = vlqEncode(seg.genCol - prevGenCol);
+        s += vlqEncode(seg.src - prevSrc);
+        s += vlqEncode(seg.origLine - prevOrigLine);
+        s += vlqEncode(seg.origCol - prevOrigCol);
+        if (seg.name != null) {
+          s += vlqEncode(seg.name - prevNameIdx);
+          prevNameIdx = seg.name;
+        }
+        prevSrc = seg.src;
+        prevOrigLine = seg.origLine;
+        prevOrigCol = seg.origCol;
+        lineParts.push(s);
+      }
+      prevGenCol = seg.genCol;
+    }
+    out.push(lineParts.join(','));
+  }
+  return out.join(';');
+}
+
+// Given an array of `{js, mapJSON}` chunks (where mapJSON is the source-map
+// V3 JSON string for that chunk, or null/undefined if the chunk has no
+// map), produce a single merged result.
+//
+// Returns:
+//   {
+//     js,        // concatenated JS, with all per-chunk sourceMappingURL
+//                // pragmas stripped — caller appends ONE merged pragma
+//     mapJSON,   // V3 source-map JSON string covering all chunks, or
+//                // null if no chunk had a map
+//   }
+//
+// The chunks must be in the order they should be eval'd. Each chunk's JS
+// is treated as opaque — we don't parse it, we only count newlines for
+// line-offset math.
+function mergeChunks(chunks) {
+  // Strip per-chunk pragmas first; we'll append exactly one at the end.
+  const stripped = chunks.map((c) => {
+    if (c.mapJSON !== undefined) return { js: c.js, mapJSON: c.mapJSON };
+    return extractInlineMap(c.js);
+  });
+
+  // If no chunk has a map, the merged JS is just concatenated; no map.
+  const anyMap = stripped.some((c) => c.mapJSON);
+  const mergedJS = stripped.map((c) => c.js).join(MERGE_SEPARATOR);
+  if (!anyMap) return { js: mergedJS, mapJSON: null };
+
+  // Build merged sources / sourcesContent / names with deduplication
+  // by string identity. Per-chunk remap tables let us rewrite each
+  // chunk's source-index / name-index fields into the merged arrays.
+  const mergedSources = [];
+  const mergedSourcesContent = [];
+  const sourceIndexByName = new Map();
+  const mergedNames = [];
+  const nameIndexByName = new Map();
+
+  function addSource(name, content) {
+    if (sourceIndexByName.has(name)) return sourceIndexByName.get(name);
+    const idx = mergedSources.length;
+    mergedSources.push(name);
+    mergedSourcesContent.push(content ?? null);
+    sourceIndexByName.set(name, idx);
+    return idx;
+  }
+  function addName(name) {
+    if (nameIndexByName.has(name)) return nameIndexByName.get(name);
+    const idx = mergedNames.length;
+    mergedNames.push(name);
+    nameIndexByName.set(name, idx);
+    return idx;
+  }
+
+  // Per-chunk: line offset (cumulative gen-line shift), source-index
+  // remap, name-index remap, decoded segments.
+  const chunkInfos = [];
+  let lineOffset = 0;
+  for (let i = 0; i < stripped.length; i++) {
+    const c = stripped[i];
+    const info = { lineOffset, srcRemap: [], nameRemap: [], perLineSegs: null };
+
+    if (c.mapJSON) {
+      let map;
+      try { map = JSON.parse(c.mapJSON); }
+      catch { map = null; }
+      if (map && typeof map.mappings === 'string') {
+        const sources = map.sources || [];
+        const sourcesContent = map.sourcesContent || [];
+        info.srcRemap = sources.map((s, idx) => addSource(s, sourcesContent[idx]));
+        const names = map.names || [];
+        info.nameRemap = names.map((n) => addName(n));
+        info.perLineSegs = decodeMappings(map.mappings);
+      }
+    }
+
+    chunkInfos.push(info);
+
+    // Advance lineOffset by this chunk's line count + separator (except
+    // after the last chunk).
+    const chunkLines = countNewlines(c.js);
+    const sepLines = (i < stripped.length - 1) ? MERGE_SEPARATOR_LINES : 0;
+    lineOffset += chunkLines + sepLines;
+  }
+
+  // Walk all chunks and emit their segments into the merged per-line
+  // segment array, with each chunk's gen-line indices shifted by the
+  // chunk's lineOffset and source/name indices remapped.
+  const totalLines = lineOffset + 1;
+  const mergedPerLineSegs = new Array(totalLines).fill(null).map(() => []);
+
+  for (const info of chunkInfos) {
+    if (!info.perLineSegs) continue;
+    for (let li = 0; li < info.perLineSegs.length; li++) {
+      const target = info.lineOffset + li;
+      if (target >= mergedPerLineSegs.length) {
+        while (mergedPerLineSegs.length <= target) mergedPerLineSegs.push([]);
+      }
+      for (const seg of info.perLineSegs[li]) {
+        if (seg.src == null) {
+          mergedPerLineSegs[target].push({ genCol: seg.genCol });
+        } else {
+          const remapped = {
+            genCol: seg.genCol,
+            src: info.srcRemap[seg.src],
+            origLine: seg.origLine,
+            origCol: seg.origCol,
+          };
+          if (seg.name != null) remapped.name = info.nameRemap[seg.name];
+          mergedPerLineSegs[target].push(remapped);
+        }
+      }
+    }
+  }
+
+  const mergedMappings = encodeMappings(mergedPerLineSegs);
+  const mergedMap = {
+    version: 3,
+    sources: mergedSources,
+    sourcesContent: mergedSourcesContent,
+    names: mergedNames,
+    mappings: mergedMappings,
+  };
+  return { js: mergedJS, mapJSON: JSON.stringify(mergedMap) };
+}
+
+// UTF-8-safe base64 encode for embedding mapJSON as a data URL pragma.
+function utf8ToBase64(str) {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(str, 'utf8').toString('base64');
+  }
+  const bytes = new TextEncoder().encode(str);
+  let bin = '';
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+  return btoa(bin);
+}
+
+// Convenience: take chunks, run mergeChunks, append a single
+// `//# sourceMappingURL=` data-URL pragma to the merged JS, return it.
+// If no chunk had a map, returns the concat'd JS unchanged.
+function mergeChunksWithInlineMap(chunks) {
+  const { js, mapJSON } = mergeChunks(chunks);
+  if (!mapJSON) return js;
+  const b64 = utf8ToBase64(mapJSON);
+  return js + '\n//# sourceMappingURL=data:application/json;base64,' + b64 + '\n';
+}
+
+export { SourceMapGenerator, vlqEncode, vlqDecode, parseSourceMap, buildLineMap, mergeChunks, mergeChunksWithInlineMap };

package/src/stdlib.js

@@ -0,0 +1,253 @@
+// =============================================================================
+// stdlib.js — Rip's standard library
+//
+// One file, three concerns, all related to the small set of helpers Rip
+// makes available without an explicit import:
+//
+//   1. `getStdlibCode()`
+//      Returns a string of self-contained JavaScript that the compiler
+//      prepends to every emitted file. Defines the `globalThis.*` helpers
+//      every Rip program can rely on (p, pp, pr, pj, kind, abort, …).
+//      The string is bracketed with `// rip:stdlib:begin` / `:end` markers
+//      so tooling (test runner, source viewers) can strip the preamble
+//      cleanly even when individual helper bodies span multiple lines.
+//
+//   2. `stringify(value, opts?)`
+//      The importable, *strict* JS-value -> Rip-syntax serializer used
+//      from `import { stringify } from 'rip-lang'`. Throws on values
+//      that have no faithful Rip-literal form (Date, BigInt, Map, Set,
+//      class instances, functions, non-interned symbols), preserving the
+//      round-trip property: `compile(stringify(v))` returns `v`.
+//
+//   3. `STDLIB_TYPE_DECLS`
+//      A map from helper name to TypeScript declaration string. The
+//      typecheck pipeline injects these into shadow `.d.ts` so user code
+//      that calls `assert(x)`, `kind(v)`, etc. type-checks under the
+//      strict configuration. Co-located here so adding a stdlib helper
+//      is a one-file change — both the runtime body and the TS
+//      declaration live in this module.
+//
+// The runtime `pr` formatter inlined in `getStdlibCode()` is intentionally
+// duplicated with `stringify` rather than refactored through Function-
+// constructor indirection. Two visible function bodies in one file are
+// easier to keep in sync than one source threaded through `eval`-style
+// evaluation. If they ever diverge the diff will be local and obvious.
+// =============================================================================
+
+// -----------------------------------------------------------------------------
+// 1. Runtime stdlib injection (string-literal JS, NOT executed in this scope)
+// -----------------------------------------------------------------------------
+//
+// IMPORTANT: this string is not parsed by the JS engine here — it is
+// literally prepended to other compiled files as text. It cannot reference
+// anything from this module's scope. It must be self-contained.
+//
+// The `// rip:stdlib:begin` / `// rip:stdlib:end` markers are LOAD-BEARING.
+// `test/runner.js` strips everything between them in `normalizeCode()`
+// before comparing compiled output against expected JS in `code` tests.
+// Removing or renaming these markers without updating the runner will
+// silently break every `code` snapshot test in the suite.
+//
+// `pr` here mirrors the strict `stringify()` defined later in this file,
+// with one deliberate difference: `pr` returns null from its inner
+// formatter for any value that has no Rip-literal form (class instance,
+// Date, BigInt, Map, Set, function, non-interned Symbol) and the outer
+// wrapper falls back to `console.dir` for those values, so a debug
+// session never crashes on whatever the caller happens to hand it. The
+// strict version throws so round-trip-safe consumers can detect the
+// problem at call time. Keep the formatting logic in sync with the
+// `stringify` body below — same key/string quoting rules, same array
+// and object shapes, same symbol literal form.
+
+export function getStdlibCode() {
+  return `\
+// rip:stdlib:begin
+globalThis.abort  ??= (msg) => { if (msg) console.error(msg); process.exit(1); };
+globalThis.assert ??= (v, msg) => { if (!v) throw new Error(msg || "Assertion failed"); };
+globalThis.exit   ??= (code) => process.exit(code || 0);
+globalThis.kind   ??= (v) => v != null ? (v.constructor?.name || Object.prototype.toString.call(v).slice(8, -1)).toLowerCase() : String(v);
+globalThis.noop   ??= () => {};
+globalThis.p      ??= console.log;
+globalThis.pp     ??= (v) => { console.dir(v, { depth: null, colors: true }); return v; };
+globalThis.pj     ??= (v) => { console.log(JSON.stringify(v, null, 2)); return v; };
+globalThis.pr     ??= (() => {
+  const BARE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+  const esc = (s, q) => s.replace(/\\\\/g, "\\\\\\\\").replace(/\\n/g, "\\\\n").replace(/\\r/g, "\\\\r").replace(/\\t/g, "\\\\t").replace(new RegExp(q, 'g'), "\\\\" + q);
+  const qs = (s) => !s.includes("'") ? "'" + esc(s, "'") + "'" : !s.includes('"') ? '"' + esc(s, '"').split("#{").join("\\\\#{") + '"' : "'" + esc(s, "'") + "'";
+  const ks = (k) => { if (typeof k === 'symbol') { const n = Symbol.keyFor(k); return n && BARE.test(n) ? ':' + n : qs(String(k)); } return BARE.test(k) ? k : qs(k); };
+  const fmt = (v, d) => {
+    if (v === null) return 'null';
+    if (v === undefined) return 'undefined';
+    const t = typeof v;
+    if (t === 'number' || t === 'boolean') return String(v);
+    if (t === 'string') return qs(v);
+    if (t === 'symbol') { const n = Symbol.keyFor(v); return n && BARE.test(n) ? ':' + n : null; }
+    if (Array.isArray(v)) {
+      if (v.length === 0) return '[]';
+      const pad = '  '.repeat(d + 1), end = '  '.repeat(d);
+      return '[\\n' + pad + v.map(x => fmt(x, d + 1) ?? 'null').join('\\n' + pad) + '\\n' + end + ']';
+    }
+    if (t === 'object') {
+      const proto = Object.getPrototypeOf(v);
+      if (proto !== Object.prototype && proto !== null) return null;
+      const keys = Object.keys(v);
+      if (keys.length === 0) return '{}';
+      const pad = '  '.repeat(d + 1), end = '  '.repeat(d);
+      return '{\\n' + pad + keys.map(k => ks(k) + ': ' + (fmt(v[k], d + 1) ?? 'null')).join('\\n' + pad) + '\\n' + end + '}';
+    }
+    return null;
+  };
+  return (v) => { const s = fmt(v, 0); s !== null ? console.log(s) : console.dir(v, { depth: null, colors: true }); return v; };
+})();
+globalThis.raise  ??= (a, b) => { throw (b !== undefined ? new a(b) : new Error(a)); };
+globalThis.rand   ??= (a, b) => b !== undefined ? (a > b && ([a, b] = [b, a]), Math.floor(Math.random() * (b - a + 1) + a)) : a ? Math.floor(Math.random() * a) : Math.random();
+globalThis.sleep  ??= (ms) => new Promise(r => setTimeout(r, ms));
+globalThis.todo   ??= (msg) => { throw new Error(msg || "Not implemented"); };
+globalThis.warn   ??= console.warn;
+globalThis.zip    ??= (...a) => a[0].map((_, i) => a.map(b => b[i]));
+// rip:stdlib:end
+`;
+}
+
+// -----------------------------------------------------------------------------
+// 2. Importable, strict Rip-syntax serializer
+// -----------------------------------------------------------------------------
+//
+// Public API. `import { stringify } from 'rip-lang'` is the supported
+// surface for tools that emit `.rip` files programmatically (config
+// migrations, scaffolders, code generators).
+//
+// Round-trip property: for any value the function accepts,
+// `compile(stringify(v))` evaluates to a value structurally equal to `v`.
+// That guarantee is preserved by REJECTING values with no faithful Rip-
+// literal form rather than rendering them best-effort. The accepted set:
+//
+//   * null, undefined
+//   * number, boolean, string
+//   * interned Symbol (`Symbol.for(name)` where `name` is bare-key shape)
+//   * plain Array (any depth, any accepted element types)
+//   * plain Object (own enumerable string keys, accepted values)
+//
+// Anything else throws `StringifyError`:
+//
+//   * Date, BigInt, RegExp
+//   * Map, Set, WeakMap, WeakSet
+//   * class instances (anything with a non-Object prototype)
+//   * functions
+//   * non-interned Symbols
+//   * circular references (would already throw via stack overflow before
+//     the type check fires; explicit detection is a future enhancement)
+//
+// `opts.indent` accepts a string or a number-of-spaces; defaults to 2.
+
+const BARE_KEY_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+class StringifyError extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = 'StringifyError';
+  }
+}
+
+// Render a string. Single-quote by default; switch to double-quote when
+// the value contains an apostrophe but no double-quote, and escape any
+// `#{...}` sequences inside double-quoted output so Rip interpolation
+// can't fire on the round-trip.
+function quoteString(str) {
+  const hasSingle = str.includes("'");
+  const hasDouble = str.includes('"');
+  const escape = (s, q) =>
+    s
+      .replace(/\\/g, '\\\\')
+      .replace(/\n/g, '\\n')
+      .replace(/\r/g, '\\r')
+      .replace(/\t/g, '\\t')
+      .replace(new RegExp(q, 'g'), `\\${q}`);
+  if (!hasSingle) return `'${escape(str, "'")}'`;
+  if (!hasDouble) {
+    let body = escape(str, '"').split('#{').join('\\#{');
+    return `"${body}"`;
+  }
+  return `'${escape(str, "'")}'`;
+}
+
+function formatKey(key) {
+  if (typeof key === 'symbol') {
+    const name = Symbol.keyFor(key);
+    if (name && BARE_KEY_RE.test(name)) return `:${name}`;
+    return quoteString(String(key));
+  }
+  if (BARE_KEY_RE.test(key)) return key;
+  return quoteString(key);
+}
+
+function formatValue(value, indent, depth) {
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  const t = typeof value;
+  if (t === 'number' || t === 'boolean') return String(value);
+  if (t === 'string') return quoteString(value);
+  if (t === 'symbol') {
+    const name = Symbol.keyFor(value);
+    if (name && BARE_KEY_RE.test(name)) return `:${name}`;
+    throw new StringifyError('cannot stringify non-interned symbol');
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const pad = indent.repeat(depth + 1);
+    const closePad = indent.repeat(depth);
+    const items = value.map((v) => formatValue(v, indent, depth + 1));
+    return `[\n${pad}${items.join(`\n${pad}`)}\n${closePad}]`;
+  }
+  if (t === 'object') {
+    // Reject class instances and exotic objects — they don't round-trip.
+    if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+      throw new StringifyError(`cannot stringify ${value.constructor?.name || 'non-plain'} instance`);
+    }
+    const keys = Object.keys(value);
+    if (keys.length === 0) return '{}';
+    const pad = indent.repeat(depth + 1);
+    const closePad = indent.repeat(depth);
+    const pairs = keys.map((k) => {
+      const v = value[k];
+      return `${formatKey(k)}: ${formatValue(v, indent, depth + 1)}`;
+    });
+    return `{\n${pad}${pairs.join(`\n${pad}`)}\n${closePad}}`;
+  }
+  throw new StringifyError(`cannot stringify value of type ${t}`);
+}
+
+export function stringify(value, opts = {}) {
+  let indent = opts.indent ?? '  ';
+  if (typeof indent === 'number') indent = ' '.repeat(indent);
+  return formatValue(value, indent, 0);
+}
+
+export { StringifyError };
+
+// -----------------------------------------------------------------------------
+// 3. TypeScript declarations for stdlib helpers
+// -----------------------------------------------------------------------------
+//
+// `typecheck.js` injects these into the shadow `.d.ts` file it feeds the
+// TypeScript language service so user code that calls `assert(x)`,
+// `kind(v)`, etc. type-checks correctly. Helpers not listed here fall back
+// to a generic `(...args: any[]) => any` signature in typecheck.js.
+
+export const STDLIB_TYPE_DECLS = {
+  abort:  'declare function abort(msg?: string): never;',
+  assert: 'declare function assert(v: any, msg?: string): asserts v;',
+  exit:   'declare function exit(code?: number): never;',
+  kind:   'declare function kind(v: any): string;',
+  noop:   'declare function noop(): void;',
+  p:      'declare function p(...args: any[]): void;',
+  pp:     'declare function pp<T>(v: T): T;',
+  pr:     'declare function pr<T>(v: T): T;',
+  pj:     'declare function pj<T>(v: T): T;',
+  raise:  'declare function raise(a: any, b?: any): never;',
+  rand:   'declare function rand(a?: number, b?: number): number;',
+  sleep:  'declare function sleep(ms: number): Promise<void>;',
+  todo:   'declare function todo(msg?: string): never;',
+  warn:   'declare function warn(...args: any[]): void;',
+  zip:    'declare function zip(...arrays: any[][]): any[][];',
+};