@ball-lang/compiler 0.1.0 → 1.3.4

package/README.md

@@ -0,0 +1,74 @@
+[![npm version](https://img.shields.io/npm/v/@ball-lang/compiler.svg)](https://www.npmjs.com/package/@ball-lang/compiler)
+
+# @ball-lang/compiler
+
+Compiles [Ball programs](https://github.com/ball-lang/ball) (proto3 JSON / `Program` objects) into idiomatic **TypeScript** source. Runs entirely in-process using [`ts-morph`](https://ts-morph.com) — no Dart subprocess. The Dart compiler (`dart/compiler/`) is the canonical reference implementation; this package mirrors its semantics.
+
+## Install
+
+```bash
+npm install @ball-lang/compiler
+```
+
+## Usage
+
+```ts
+import { compile } from '@ball-lang/compiler';
+
+// `program` is a Ball Program — a proto3 JSON object (or a parsed equivalent).
+const program = {
+  name: 'hello',
+  version: '1.0.0',
+  entryModule: 'main',
+  entryFunction: 'main',
+  modules: [
+    {
+      name: 'std',
+      functions: [{ name: 'print', isBase: true }],
+    },
+    {
+      name: 'main',
+      moduleImports: [{ name: 'std' }],
+      functions: [
+        {
+          name: 'main',
+          body: {
+            call: {
+              module: 'std',
+              function: 'print',
+              input: {
+                messageCreation: {
+                  fields: [
+                    { name: 'value', value: { literal: { stringValue: 'Hello, World!' } } },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      ],
+    },
+  ],
+};
+
+const tsSource: string = compile(program);
+console.log(tsSource); // emitted TypeScript
+```
+
+## API
+
+- `compile(program: Program, options?: CompileOptions): string` — compile a whole program to TypeScript source.
+- `compileModule(module: Module, options?: CompileModuleOptions): string` — compile a single module.
+- `BallCompiler` — the underlying class, if you need finer control.
+- `TS_RUNTIME_PREAMBLE` — the Dart-flavored runtime polyfill preamble injected at the top of compiled output.
+
+`CompileOptions`:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `includePreamble` | `boolean` | Prepend `TS_RUNTIME_PREAMBLE` to the output. Default `true`. |
+| `fileName` | `string` | Output file path hint (affects `ts-morph`'s internal resolution). |
+
+## License
+
+MIT

package/bin/ball-ts-compile.mjs

@@ -39,6 +39,20 @@ function parseArgs(argv) {
 const args = parseArgs(process.argv.slice(2));
 const ext = extname(args.input).toLowerCase();
 
+// Ball files are self-describing google.protobuf.Any envelopes; strip the
+// "@type" key (if present) to recover the bare proto3-JSON Program.
+function unwrapBallFile(json) {
+  if (json === null || typeof json !== "object" || Array.isArray(json)) return json;
+  const type = json["@type"];
+  if (type === undefined) return json;
+  const ok = typeof type === "string" &&
+    (type.endsWith("/ball.v1.Program") || type.endsWith("/ball.v1.Module"));
+  if (!ok) die(`unknown ball file @type: ${JSON.stringify(type)}`);
+  const body = {};
+  for (const [k, v] of Object.entries(json)) { if (k !== "@type") body[k] = v; }
+  return body;
+}
+
 let program;
 if (ext === ".pb") {
   die("binary .ball.pb not yet supported in @ball-lang/compiler (use .ball.json)");
@@ -46,6 +60,7 @@ if (ext === ".pb") {
   const text = readFileSync(args.input, "utf8");
   try { program = JSON.parse(text); }
   catch (e) { die(`invalid JSON: ${e.message}`); }
+  program = unwrapBallFile(program);
 }
 
 const ts = compile(program, { includePreamble: args.includePreamble });

package/dist/compiler.d.ts

@@ -1,4 +1,4 @@
-import type { Program } from "./types.ts";
+import type { Module, Program } from "./types.ts";
 export interface CompileOptions {
     /** Include the runtime preamble at the top of the output. Default true. */
     includePreamble?: boolean;
@@ -12,22 +12,70 @@ export declare class BallCompiler {
     private depth;
     /** Catch-bound variables currently in scope — subject to bracket access. */
     private readonly catchVars;
+    /** Names of user-defined async functions (from metadata is_async). */
+    private asyncFnNames;
     /** Fields of the class currently being emitted (method bodies). */
     private currentClassFields;
     /** Parameters of the currently-emitting method (shadow fields). */
     private currentMethodParams;
     /** Short method names of the current class (for `this.foo()` routing). */
     private currentClassMethodNames;
+    /** Short names of GETTER accessors. Getters are properties, not methods,
+     *  so bare references emit `this.name` not `this.name.bind(this)`. */
+    private currentClassGetterNames;
+    /**
+     * Short names of STATIC methods of the current class. Static members are
+     * not on `this` in JS, so unqualified same-class calls/tear-offs to these
+     * must be emitted as `<ClassName>.<name>` rather than `this.<name>`.
+     */
+    private currentClassStaticNames;
+    /** TS name of the class currently being emitted (for static-call routing). */
+    private currentClassName;
+    /** Type parameters of the class currently being emitted (erased to `any`). */
+    private currentClassTypeParams;
     /** All function names in the entry module (function vs ctor routing). */
     private allFunctionNames;
     /** typeDefs in the entry module (typeName → definition). */
     private typeDefByName;
+    /**
+     * Variable names declared (via `let`) in the current function scope.
+     * Used to detect shadowing conflicts when hoisting block statements.
+     */
+    private scopeDeclaredVars;
+    /**
+     * Stack of rename maps for shadow-renamed variables. When a hoisted
+     * block declares a variable that conflicts with an already-declared
+     * name, we push a map entry (original → renamed) before emitting
+     * the block's statements and pop it afterward.
+     */
+    private renameStack;
     constructor(program: Program);
     /** Compile to TS source. */
     compile(options?: CompileOptions): string;
     private emitFreeFunction;
+    /** Wrap captured statements in an IIFE, choosing the right kind:
+     *  - yield present → `yield* (function* () { ... })()`
+     *  - await present → `await (async () => { ... })()`
+     *  - neither → `(() => { ... })()`
+     */
+    private wrapIIFE;
+    /** Check if an expression tree references any name in the given set. */
+    private bodyReferencesAny;
     private emitClass;
     private buildCtor;
+    /**
+     * Filters a constructor body to remove encoder-generated boilerplate:
+     * - `let self = new ClassName()` (self-recursive construction)
+     * - `return self` (returning the self variable)
+     * - Bare `input;` or `paramName;` statements (no-op expressions)
+     */
+    private filterCtorBody;
+    /**
+     * Builds a named constructor as a static factory method.
+     * Named constructors (e.g., Point.origin, Point.fromList) create instances
+     * from field initializers in metadata.
+     */
+    private buildNamedCtor;
     private buildMethod;
     private buildGetter;
     private buildSetter;
@@ -37,6 +85,18 @@ export declare class BallCompiler {
     private withMethodContext;
     private emitStatementOrExpression;
     private emitBlock;
+    /**
+     * Resolve a variable name through the active rename stack.
+     * If a rename exists for the sanitized name, return the renamed version.
+     */
+    private resolveVarName;
+    /**
+     * Recursively collect all `let`-declared variable names from a block's
+     * statements that would be hoisted into the enclosing scope. This includes
+     * direct `let` statements and `let` statements inside nested
+     * block-expression-as-statement nodes (since those are also hoisted flat).
+     */
+    private collectHoistedLetNames;
     private emitStatement;
     private isControlFlow;
     private emitControlFlowStatement;
@@ -47,9 +107,59 @@ export declare class BallCompiler {
     private emitDoWhileStmt;
     private emitTryStmt;
     private emitAssignStmt;
+    /**
+     * Detects `list_concat(list: X, value: Y)` where X is the same reference as
+     * [target] and emits in-place `X.push(...Y)` instead of `X = [...X, ...Y]`.
+     * Returns the expression string or undefined if the pattern doesn't match.
+     */
+    private tryEmitInPlaceListMutation;
+    /**
+     * Like {@link expr}, but produces a valid assignment target (lvalue).
+     *
+     * The `index` operator (`a[i]`) normally compiles to the bounds-checked
+     * `__ball_index(a, i)` runtime helper so out-of-bounds list reads throw a
+     * Dart-style RangeError. A function-call expression can't be the left side
+     * of an assignment, so when an `index` call is the target of an `assign`
+     * (e.g. `map[key] = value`) we emit the raw `a[i]` bracket form instead.
+     */
+    private lvalueExpr;
     private typedCatchCondition;
+    /**
+     * Qualifier for an unqualified same-class member reference. Static members
+     * are not on `this` in JS, so they must be addressed via the class name
+     * (`<ClassName>.m`); instance members use `this.m`.
+     */
+    private memberQualifier;
     private expr;
     private compileLiteral;
+    private isCollectionControlElement;
+    /** Build a TS list expression from collection elements. */
+    private compileListElements;
+    /** Build a TS Set expression from collection elements. */
+    private compileSetElements;
+    /**
+     * Build a TS plain-object map expression from collection map-entry
+     * elements. Each element is either an `entry` (key/value messageCreation),
+     * a spread/null_spread of another map, or a collection_if/collection_for
+     * whose leaves are key/value entries.
+     */
+    private compileMapElements;
+    /** Render a single non-control map entry as `key: value`, or undefined. */
+    private mapEntryPair;
+    /**
+     * Emit statements that push/add/assign one collection element into the
+     * accumulator `sink`. `kind` selects the sink operation:
+     *   list → `sink.push(v)`   set → `sink.add(v)`   map → `sink[k] = v`.
+     */
+    private emitCollectionElement;
+    /**
+     * Render a C-style for-init `block` (a single-let, no-result block) as an
+     * inline declaration string like `var i = 0` — NOT an IIFE, so the loop
+     * variable stays in scope for the condition/update. Mirrors the Dart
+     * compiler's `_renderForInit`. Uses `var` to match Dart's shared-variable
+     * loop-capture semantics. Returns "" on an unrecognized shape.
+     */
+    private renderForInit;
     private compileFieldAccess;
     private compileMessageCreation;
     private extractPositionalAndNamed;
@@ -58,13 +168,49 @@ export declare class BallCompiler {
     private compileLambda;
     private compileCall;
     private compileStdCall;
+    private typeRefMetaToString;
+    private wrapWithTypeArgs;
     private emitIsCheck;
     private wrapIfNeeded;
     private compileSwitchExpr;
+    /**
+     * Fold one switch-expression branch into the ternary chain.
+     *  - No guard: `(cond ? bindBody : rest)`.
+     *  - With guard: the guard references the pattern's bindings, so bind ONCE in
+     *    an IIFE and gate the body on the guard, falling through to `rest` when
+     *    the guard is false: `(cond ? ((binds) => (guard ? body : rest))(args) : rest)`.
+     */
+    private foldSwitchBranch;
     private compileThrowValue;
     private enclosingTypeName;
     private dartTypeToTs;
 }
 /** Convenience: compile a Program directly. */
 export declare function compile(program: Program, options?: CompileOptions): string;
+export interface CompileModuleOptions {
+    /** Include the runtime preamble at the top of the output. Default true. */
+    includePreamble?: boolean;
+    /** Output file path hint (affects ts-morph's internal resolution). */
+    fileName?: string;
+    /**
+     * Namespace/module name for the output (used in header comments).
+     * Defaults to the Module's name.
+     */
+    moduleName?: string;
+}
+/**
+ * Compile a Ball Module (not a Program) to a TypeScript ESM library.
+ *
+ * This handles the ball_protobuf use case: the input is a Module facade
+ * with `moduleImports[].inline.json` containing sub-modules. The output
+ * is a single TypeScript file with:
+ * - No main() function or top-level invocation
+ * - All public functions exported via `export function`
+ * - All types/classes exported via `export class`
+ *
+ * @param module - A Ball Module (with optional inline sub-modules)
+ * @param options - Compilation options
+ * @returns TypeScript source string with ESM exports
+ */
+export declare function compileModule(module: Module, options?: CompileModuleOptions): string;
 //# sourceMappingURL=compiler.d.ts.map

package/dist/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAOV,OAAO,EAIR,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAQD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAElC,+CAA+C;IAC/C,OAAO,CAAC,GAAG,CAAM;IACjB,OAAO,CAAC,KAAK,CAAK;IAElB,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAE/C,mEAAmE;IACnE,OAAO,CAAC,kBAAkB,CAA0B;IAEpD,mEAAmE;IACnE,OAAO,CAAC,mBAAmB,CAA0B;IAErD,0EAA0E;IAC1E,OAAO,CAAC,uBAAuB,CAA0B;IAEzD,yEAAyE;IACzE,OAAO,CAAC,gBAAgB,CAA0B;IAElD,4DAA4D;IAC5D,OAAO,CAAC,aAAa,CAA0C;gBAEnD,OAAO,EAAE,OAAO;IAI5B,4BAA4B;IAC5B,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,MAAM;IAyF7C,OAAO,CAAC,gBAAgB;IAwBxB,OAAO,CAAC,SAAS;IAqJjB,OAAO,CAAC,SAAS;IAsDjB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,OAAO;IAIf,OAAO,KAAK,GAAG,GAEd;IAED,OAAO,CAAC,iBAAiB;IAmBzB,OAAO,CAAC,yBAAyB;IAoBjC,OAAO,CAAC,SAAS;IAmBjB,OAAO,CAAC,aAAa;IAmCrB,OAAO,CAAC,aAAa;IAYrB,OAAO,CAAC,wBAAwB;IAyHhC,OAAO,CAAC,UAAU;IAiBlB,OAAO,CAAC,WAAW;IAsBnB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,WAAW;IAmFnB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,IAAI;IA0BZ,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,sBAAsB;IAuD9B,OAAO,CAAC,yBAAyB;IAqBjC,OAAO,CAAC,sBAAsB;IAI9B,OAAO,CAAC,sBAAsB;IAe9B,OAAO,CAAC,aAAa;IAoBrB,OAAO,CAAC,WAAW;IA2CnB,OAAO,CAAC,cAAc;IAoRtB,OAAO,CAAC,WAAW;IAuBnB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,iBAAiB;IA6CzB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,YAAY;CA8CrB;AAqOD,+CAA+C;AAC/C,wBAAgB,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,MAAM,CAE1E"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}