@ball-lang/compiler 0.1.0

package/src/index.ts

@@ -0,0 +1,4 @@
+export { BallCompiler, compile } from "./compiler.ts";
+export type { CompileOptions } from "./compiler.ts";
+export { TS_RUNTIME_PREAMBLE } from "./preamble.ts";
+export type * from "./types.ts";

package/src/preamble.ts

@@ -0,0 +1,473 @@
+/**
+ * Runtime preamble prepended to every compiled TS output.
+ *
+ * Contains:
+ *   - Helpers for Dart-flavored string conversion / parsing
+ *   - Polyfills for Dart-flavored Array / Map / String methods that
+ *     don't exist on JS prototypes (containsKey, addAll, removeLast,
+ *     isEmpty/isNotEmpty/first/last, etc.)
+ *   - A `__ball_active_error` module-level binding used by `rethrow`
+ *
+ * Node strips the TS type annotations at runtime via
+ * `--experimental-strip-types`, so the `any` annotations and interface
+ * declarations below are type-check only — they have no runtime cost.
+ */
+export const TS_RUNTIME_PREAMBLE = String.raw`// ── Ball runtime preamble (generated by @ball-lang/compiler) ────────
+
+function __ball_to_string(v: any): string {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') {
+    if (Number.isInteger(v)) return v.toString();
+    const s = v.toString();
+    return s.includes('.') || s.includes('e') ? s : s + '.0';
+  }
+  if (typeof v === 'string') return v;
+  if (Array.isArray(v)) {
+    return '[' + v.map(__ball_to_string).join(', ') + ']';
+  }
+  if (v instanceof Map) {
+    const parts: string[] = [];
+    for (const [k, val] of v.entries()) {
+      parts.push(__ball_to_string(k) + ': ' + __ball_to_string(val));
+    }
+    return '{' + parts.join(', ') + '}';
+  }
+  return String(v);
+}
+
+function __ball_parse_int(s: string): number {
+  const trimmed = s.trim();
+  if (!/^-?\d+$/.test(trimmed)) {
+    throw new Error('FormatException: ' + s);
+  }
+  return parseInt(trimmed, 10);
+}
+
+function __ball_parse_double(s: string): number {
+  const n = parseFloat(s);
+  if (Number.isNaN(n)) throw new Error('FormatException: ' + s);
+  return n;
+}
+
+function __ball_double_to_string(n: number): string {
+  if (Number.isInteger(n)) return n.toFixed(1);
+  return n.toString();
+}
+
+// Active exception for rethrow. Catch bodies shadow with a local.
+let __ball_active_error: any = undefined;
+
+// Dart type shims — provide static methods for Dart built-in types
+// that don't exist in JS (int, double, num, bool).
+const int = {
+  parse: (s: any) => { const n = parseInt(String(s), 10); if (isNaN(n)) throw new Error('FormatException: ' + s); return n; },
+  tryParse: (s: any) => { const n = parseInt(String(s), 10); return isNaN(n) ? null : n; },
+};
+const double = {
+  parse: (s: any) => { const n = parseFloat(String(s)); if (isNaN(n)) throw new Error('FormatException: ' + s); return n; },
+  tryParse: (s: any) => { const n = parseFloat(String(s)); return isNaN(n) ? null : n; },
+  infinity: Infinity,
+  nan: NaN,
+  negativeInfinity: -Infinity,
+};
+const num = {
+  parse: (s: any) => { const n = Number(s); if (isNaN(n)) throw new Error('FormatException: ' + s); return n; },
+  tryParse: (s: any) => { const n = Number(s); return isNaN(n) ? null : n; },
+};
+const bool = {
+  parse: (s: any) => { if (s === 'true') return true; if (s === 'false') return false; throw new Error('FormatException: ' + s); },
+  tryParse: (s: any) => { if (s === 'true') return true; if (s === 'false') return false; return null; },
+};
+
+// Sentinel for "not yet initialized" — used by the Dart engine for
+// late-initialized variables and block-scoped flow tracking.
+const __no_init__: unique symbol = Symbol('__no_init__');
+
+// ── Dart \u2192 JS method-name polyfills ────────────────────────────────
+//
+// Idempotent: guarded so multiple preamble inclusions don't double-install.
+(function installBallPolyfills() {
+  const mp: any = Map.prototype;
+  if (!mp.containsKey) mp.containsKey = function (k: any) { return this.has(k); };
+  if (!mp.putIfAbsent) {
+    mp.putIfAbsent = function (k: any, supplier: any) {
+      if (!this.has(k)) this.set(k, supplier());
+      return this.get(k);
+    };
+  }
+  if (!mp.addAll) {
+    mp.addAll = function (other: any) {
+      if (other instanceof Map) {
+        for (const [k, v] of other.entries()) this.set(k, v);
+      } else if (other && typeof other === 'object') {
+        for (const k of Object.keys(other)) this.set(k, other[k]);
+      }
+    };
+  }
+  Object.defineProperty(mp, 'isEmpty', {
+    configurable: true, get() { return this.size === 0; },
+  });
+  Object.defineProperty(mp, 'isNotEmpty', {
+    configurable: true, get() { return this.size !== 0; },
+  });
+
+  const ap: any = Array.prototype;
+  if (!ap.add) ap.add = function (v: any) { this.push(v); };
+  if (!ap.addAll) ap.addAll = function (iter: any) {
+    for (const v of iter) this.push(v);
+  };
+  if (!ap.removeLast) ap.removeLast = function () { return this.pop(); };
+  if (!ap.where) ap.where = Array.prototype.filter;
+  if (!ap.toList) ap.toList = function () { return this.slice(); };
+  if (!ap.toSet) ap.toSet = function () { return new Set(this); };
+  if (!ap.contains) ap.contains = function (v: any) { return this.indexOf(v) >= 0; };
+
+  // Dart Set polyfills — Set.contains → Set.has, etc.
+  const setp: any = Set.prototype;
+  if (!setp.contains) setp.contains = function (v: any) { return this.has(v); };
+  if (!setp.toList) setp.toList = function () { return [...this]; };
+  if (!setp.add) { /* Set already has .add */ }
+  if (!setp.remove) setp.remove = function (v: any) { return this.delete(v); };
+  Object.defineProperty(ap, 'isEmpty', {
+    configurable: true, get() { return this.length === 0; },
+  });
+  Object.defineProperty(ap, 'isNotEmpty', {
+    configurable: true, get() { return this.length !== 0; },
+  });
+  Object.defineProperty(ap, 'first', {
+    configurable: true, get() { return this[0]; },
+  });
+  Object.defineProperty(ap, 'last', {
+    configurable: true, get() { return this[this.length - 1]; },
+  });
+
+  const sp: any = String.prototype;
+  Object.defineProperty(sp, 'isEmpty', {
+    configurable: true, get() { return this.length === 0; },
+  });
+  Object.defineProperty(sp, 'isNotEmpty', {
+    configurable: true, get() { return this.length !== 0; },
+  });
+  // Dart String methods not on JS String.
+  if (!sp.contains) sp.contains = function (s: any) { return this.includes(s); };
+  if (!sp.replaceFirst) sp.replaceFirst = function (from: any, to: any) {
+    return this.replace(from instanceof RegExp ? from : String(from), to);
+  };
+  if (!sp.codeUnitAt) sp.codeUnitAt = function (i: any) { return this.charCodeAt(i); };
+  if (!sp.compareTo) sp.compareTo = function (other: any) {
+    return this < other ? -1 : this > other ? 1 : 0;
+  };
+  if (!sp.allMatches) sp.allMatches = function (pattern: any, start: any) {
+    const s = typeof start === 'number' ? this.substring(start) : this;
+    if (typeof pattern === 'string') {
+      return Array.from(s.matchAll(new RegExp(pattern, 'g')));
+    }
+    const flags = pattern.flags.includes('g') ? pattern.flags : pattern.flags + 'g';
+    return Array.from(s.matchAll(new RegExp(pattern.source, flags)));
+  };
+
+  // Dart RegExp polyfills.
+  const rp: any = RegExp.prototype;
+  if (!rp.firstMatch) rp.firstMatch = function (s: any) {
+    const m = this.exec(s);
+    if (m) m.group = (i: any) => m[i];
+    return m;
+  };
+  if (!rp.allMatches) rp.allMatches = function (s: any) {
+    const flags = this.flags.includes('g') ? this.flags : this.flags + 'g';
+    return [...s.matchAll(new RegExp(this.source, flags))];
+  };
+  if (!rp.hasMatch) rp.hasMatch = function (s: any) { return this.test(s); };
+
+  // Object.prototype polyfills — used by the compiled engine when
+  // checking Ball program inputs (plain objects, not Maps).
+  const op2: any = Object.prototype;
+  if (!op2.containsKey) {
+    Object.defineProperty(op2, 'containsKey', {
+      configurable: true, writable: true, enumerable: false,
+      value: function (k: any) {
+        if (this instanceof Map) return this.has(k);
+        if (this == null || typeof this !== 'object') return false;
+        return k in this;
+      },
+    });
+  }
+  // putIfAbsent — Dart Map.putIfAbsent. Works on plain objects too.
+  if (!op2.putIfAbsent) {
+    Object.defineProperty(op2, 'putIfAbsent', {
+      configurable: true, writable: true, enumerable: false,
+      value: function (k: any, supplier: any) {
+        if (this instanceof Map) {
+          if (!this.has(k)) this.set(k, supplier());
+          return this.get(k);
+        }
+        if (!(k in this)) this[k] = supplier();
+        return this[k];
+      },
+    });
+  }
+  // remove — Dart Map.remove.
+  if (!op2.remove) {
+    Object.defineProperty(op2, 'remove', {
+      configurable: true, writable: true, enumerable: false,
+      value: function (k: any) {
+        if (this instanceof Map) { const v = this.get(k); this.delete(k); return v; }
+        const v = this[k]; delete this[k]; return v;
+      },
+    });
+  }
+  // Dart Map has .entries / .keys / .values as GETTERS (no parens).
+  // JS Map has them as METHODS (need parens). The compiled engine
+  // accesses map.entries as a getter. Shadow BOTH Map.prototype AND
+  // Object.prototype so Map and plain-object dispatch tables work.
+  const _nativeMapEntries = Map.prototype.entries;
+  const _nativeMapKeys = Map.prototype.keys;
+  const _nativeMapValues = Map.prototype.values;
+  // Shadow Map.prototype.entries with a getter (Dart uses it as a getter).
+  Object.defineProperty(Map.prototype, 'entries', {
+    configurable: true, enumerable: false,
+    get() {
+      return [..._nativeMapEntries.call(this)].map(([k, v]: any) => ({ key: k, value: v }));
+    },
+  });
+  Object.defineProperty(Map.prototype, 'keys', {
+    configurable: true, enumerable: false,
+    get() { return [..._nativeMapKeys.call(this)]; },
+  });
+  Object.defineProperty(Map.prototype, 'values', {
+    configurable: true, enumerable: false,
+    get() { return [..._nativeMapValues.call(this)]; },
+  });
+  // For plain objects — same getters on Object.prototype.
+  Object.defineProperty(op2, 'entries', {
+    configurable: true, enumerable: false,
+    get() {
+      if (this instanceof Map) return [..._nativeMapEntries.call(this)].map(([k, v]: any) => ({ key: k, value: v }));
+      if (this == null || typeof this !== 'object') return [];
+      return Object.entries(this).map(([k, v]: any) => ({ key: k, value: v }));
+    },
+  });
+  Object.defineProperty(op2, 'keys', {
+    configurable: true, enumerable: false,
+    get() {
+      if (this instanceof Map) return [..._nativeMapKeys.call(this)];
+      if (this == null || typeof this !== 'object') return [];
+      return Object.keys(this);
+    },
+  });
+  Object.defineProperty(op2, 'values', {
+    configurable: true, enumerable: false,
+    get() {
+      if (this instanceof Map) return [..._nativeMapValues.call(this)];
+      if (this == null || typeof this !== 'object') return [];
+      return Object.values(this);
+    },
+  });
+
+  // Number polyfills for Dart-style methods.
+  const np: any = Number.prototype;
+  if (!np.toInt) np.toInt = function () { return Math.trunc(this); };
+  if (!np.toDouble) np.toDouble = function () { return this + 0.0; };
+  if (!np.compareTo) np.compareTo = function (other: any) {
+    return this < other ? -1 : this > other ? 1 : 0;
+  };
+  if (!np.clamp) np.clamp = function (lo: any, hi: any) {
+    return Math.min(Math.max(this, lo), hi);
+  };
+})();
+
+// ── Protobuf Struct/Value compatibility ─────────────────────────
+//
+// Dart's protobuf runtime wraps google.protobuf.Struct as a class
+// with .fields (Map<String, Value>) and Value as .whichKind() +
+// .stringValue / .boolValue / .numberValue / .listValue / .structValue.
+// In proto3 JSON, these serialize as plain objects and values.
+//
+// This shim makes plain JSON objects behave like Struct/Value so the
+// compiled engine.dart can call .fields['key'].whichKind() etc.
+//
+// Strategy: Object.prototype gets a .fields getter that returns a
+// Proxy wrapping the object as a Map-like. Accessing [key] on the
+// proxy returns a Value-like wrapper with .whichKind() / typed
+// accessors (.stringValue, .boolValue, .numberValue, .listValue,
+// .structValue).
+
+const structpb_Value_Kind = {
+  nullValue: 'nullValue',
+  numberValue: 'numberValue',
+  stringValue: 'stringValue',
+  boolValue: 'boolValue',
+  structValue: 'structValue',
+  listValue: 'listValue',
+} as const;
+
+class __BallValueWrapper {
+  private _raw: any;
+  constructor(raw: any) { this._raw = raw; }
+  whichKind(): string {
+    const v = this._raw;
+    if (v === null || v === undefined) return 'nullValue';
+    if (typeof v === 'string') return 'stringValue';
+    if (typeof v === 'boolean') return 'boolValue';
+    if (typeof v === 'number') return 'numberValue';
+    if (Array.isArray(v)) return 'listValue';
+    if (typeof v === 'object') return 'structValue';
+    return 'nullValue';
+  }
+  get stringValue(): string { return typeof this._raw === 'string' ? this._raw : String(this._raw ?? ''); }
+  get boolValue(): boolean { return !!this._raw; }
+  get numberValue(): number { return Number(this._raw); }
+  get nullValue(): null { return null; }
+  get listValue(): { values: __BallValueWrapper[] } {
+    const arr = Array.isArray(this._raw) ? this._raw : [];
+    return { values: arr.map((v: any) => new __BallValueWrapper(v)) };
+  }
+  get structValue(): { fields: Record<string, __BallValueWrapper> } {
+    const obj = (typeof this._raw === 'object' && this._raw !== null) ? this._raw : {};
+    const fields: Record<string, __BallValueWrapper> = {};
+    for (const [k, v] of Object.entries(obj)) fields[k] = new __BallValueWrapper(v);
+    return { fields };
+  }
+  // Also proxy hasXxx for sub-values.
+  hasNullValue(): boolean { return this._raw == null; }
+  hasStringValue(): boolean { return typeof this._raw === 'string'; }
+  hasBoolValue(): boolean { return typeof this._raw === 'boolean'; }
+  hasNumberValue(): boolean { return typeof this._raw === 'number'; }
+  hasListValue(): boolean { return Array.isArray(this._raw); }
+  hasStructValue(): boolean { return typeof this._raw === 'object' && this._raw !== null && !Array.isArray(this._raw); }
+  // Pass-through for when the wrapper is used in expressions.
+  toString(): string { return String(this._raw); }
+  valueOf(): any { return this._raw; }
+}
+
+// Struct.fields shimming is done via a metadata-specific wrapper.
+// We do NOT add .fields to Object.prototype because it conflicts
+// with data properties named "fields" on MessageCreation / TypeDef.
+// Instead, the compiled engine accesses metadata.fields['key'] —
+// in proto3 JSON, metadata IS the fields directly, so we add a
+// .fields getter only when the object is a metadata Struct (i.e.,
+// it has string/bool/number/array/object values and no proto-shape
+// keys like "call"/"literal"/"block").
+//
+// The protoWrap normalizer in the test harness is responsible for
+// converting metadata objects to have the right shape.
+
+// ── Protobuf compatibility shims ────────────────────────────────
+//
+// The Dart encoder produces code that uses Dart's protobuf runtime
+// API (.whichExpr(), Expression_Expr.call, .hasInput(), .toInt(), etc.)
+// on what are really plain JSON objects at runtime. These shims make
+// the proto-style method calls work on plain objects so the compiled
+// engine.dart can execute on Node.
+
+// Oneof discriminator enums — string-valued constants that match the
+// field names the Dart protobuf codegen uses.
+const Expression_Expr = {
+  call: 'call', literal: 'literal', reference: 'reference',
+  fieldAccess: 'fieldAccess', messageCreation: 'messageCreation',
+  block: 'block', lambda: 'lambda', notSet: 'notSet',
+} as const;
+
+const Literal_Value = {
+  intValue: 'intValue', doubleValue: 'doubleValue',
+  stringValue: 'stringValue', boolValue: 'boolValue',
+  listValue: 'listValue', bytesValue: 'bytesValue', notSet: 'notSet',
+} as const;
+
+const Statement_Stmt = {
+  let: 'let', expression: 'expression', notSet: 'notSet',
+} as const;
+
+const ModuleImport_Source = {
+  http: 'http', file: 'file', inline: 'inline',
+  git: 'git', registry: 'registry', notSet: 'notSet',
+} as const;
+
+// Object.prototype shims for .whichXxx() / .hasXxx() / .toInt() —
+// these match the Dart protobuf generated API. Each is configurable
+// and non-enumerable so it doesn't pollute for-in loops.
+(function installProtoShims() {
+  const op: any = Object.prototype;
+
+  function defMethod(name: string, fn: Function) {
+    if (op[name]) return;
+    Object.defineProperty(op, name, {
+      configurable: true, writable: true, enumerable: false, value: fn,
+    });
+  }
+
+  // whichExpr / whichValue / whichStmt / whichSource — return which
+  // oneof field is set on this object.
+  defMethod('whichExpr', function (this: any) {
+    for (const k of ['call','literal','reference','fieldAccess','messageCreation','block','lambda']) {
+      if (this[k] !== undefined && this[k] !== null) return k;
+    }
+    return 'notSet';
+  });
+  defMethod('whichValue', function (this: any) {
+    for (const k of ['intValue','doubleValue','stringValue','boolValue','listValue','bytesValue']) {
+      if (this[k] !== undefined && this[k] !== null) return k;
+    }
+    return 'notSet';
+  });
+  defMethod('whichStmt', function (this: any) {
+    if (this['let'] !== undefined && this['let'] !== null) return 'let';
+    if (this['expression'] !== undefined && this['expression'] !== null) return 'expression';
+    return 'notSet';
+  });
+  defMethod('whichSource', function (this: any) {
+    for (const k of ['http','file','inline','git','registry']) {
+      if (this[k] !== undefined && this[k] !== null) return k;
+    }
+    return 'notSet';
+  });
+
+  // Presence checks — .hasXxx() returns true if the field is set.
+  for (const field of [
+    'input','body','result','metadata','value','name','module',
+    'left','right','condition','then','else','finally',
+    'subject','cases','catches','init','update','iterable',
+    'target','index','field','object','key','message',
+    'stringValue','boolValue','intValue','doubleValue','listValue',
+    'call','literal','reference','fieldAccess','messageCreation',
+    'block','lambda','let','expression','descriptor',
+  ]) {
+    const methodName = 'has' + field[0].toUpperCase() + field.slice(1);
+    defMethod(methodName, function (this: any) {
+      return this[field] !== undefined && this[field] !== null;
+    });
+  }
+
+  // Proto field-name aliases — Dart's protobuf codegen renames some
+  // fields to avoid keyword collisions (field → field_2, etc.) but
+  // proto3 JSON uses the original names. Add getters so both work.
+  Object.defineProperty(op, 'field_2', {
+    configurable: true, enumerable: false,
+    get() { return this.field; },
+    set(v: any) { this.field = v; },
+  });
+  // descriptor_ → descriptor (same issue)
+  Object.defineProperty(op, 'descriptor_', {
+    configurable: true, enumerable: false,
+    get() { return this.descriptor; },
+    set(v: any) { this.descriptor = v; },
+  });
+
+  // .toInt() — Dart's Int64/fixnum returns int from string. In proto3
+  // JSON, int64 fields are serialized as strings ("42" not 42).
+  defMethod('toInt', function (this: any) {
+    if (typeof this === 'number') return this;
+    if (typeof this === 'string') return parseInt(this, 10);
+    if (typeof this.valueOf === 'function') return parseInt(String(this.valueOf()), 10);
+    return 0;
+  });
+
+  // .toList() on Uint8Array (bytesValue)
+  defMethod('toList', function (this: any) {
+    if (this instanceof Uint8Array) return Array.from(this);
+    if (Array.isArray(this)) return this.slice();
+    return [];
+  });
+})();
+`;

package/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * Ball protobuf shapes consumed by the TS compiler.
+ *
+ * Matches the proto3 JSON form emitted by the Dart encoder's
+ * `Program.toProto3Json()` (see `proto/ball/v1/ball.proto`). Keep
+ * these in sync with the shapes in `@ball-lang/engine/src/index.ts`.
+ */
+
+export interface Program {
+  name?: string;
+  version?: string;
+  modules: Module[];
+  entryModule: string;
+  entryFunction: string;
+}
+
+export interface Module {
+  name: string;
+  functions: FunctionDef[];
+  typeDefs?: TypeDefinition[];
+  typeAliases?: TypeAlias[];
+  enums?: EnumDef[];
+  moduleImports?: ModuleImport[];
+  metadata?: Struct;
+}
+
+export interface ModuleImport {
+  name: string;
+}
+
+export interface FunctionDef {
+  name: string;
+  isBase?: boolean;
+  body?: Expression;
+  outputType?: string;
+  metadata?: Struct;
+}
+
+export interface TypeDefinition {
+  name: string;
+  descriptor?: DescriptorProto;
+  description?: string;
+  metadata?: Struct;
+}
+
+export interface TypeAlias {
+  name: string;
+  targetType: string;
+  metadata?: Struct;
+}
+
+export interface EnumDef {
+  name: string;
+  values: EnumValue[];
+}
+
+export interface EnumValue {
+  name: string;
+  intValue?: string | number;
+}
+
+export interface DescriptorProto {
+  name: string;
+  field?: FieldDescriptor[];
+}
+
+export interface FieldDescriptor {
+  name: string;
+  number?: number;
+  type?: string;
+  label?: string;
+}
+
+export interface Expression {
+  call?: FunctionCall;
+  literal?: Literal;
+  reference?: { name: string };
+  fieldAccess?: { object: Expression; field: string };
+  messageCreation?: MessageCreation;
+  block?: Block;
+  lambda?: Lambda;
+}
+
+export interface FunctionCall {
+  module?: string;
+  function: string;
+  input?: Expression;
+}
+
+export interface Literal {
+  intValue?: string | number;
+  doubleValue?: number;
+  stringValue?: string;
+  boolValue?: boolean;
+  listValue?: { elements: Expression[] };
+  bytesValue?: string;
+}
+
+export interface MessageCreation {
+  typeName?: string;
+  fields: FieldValuePair[];
+}
+
+export interface FieldValuePair {
+  name: string;
+  value: Expression;
+}
+
+export interface Block {
+  statements: Statement[];
+  result?: Expression;
+}
+
+export interface Statement {
+  let?: { name: string; value?: Expression; metadata?: Struct };
+  expression?: Expression;
+}
+
+export interface Lambda extends FunctionDef {
+  // A Lambda is just an inline FunctionDef (body + metadata.params).
+}
+
+// ── Struct (google.protobuf.Struct JSON form) ─────────────────────────────
+//
+// In proto3 JSON, Struct serializes as a plain object (no `fields` wrapper).
+// Use Struct as the metadata bag type throughout.
+export type Struct = Record<string, unknown>;