@ball-lang/encoder 0.1.0 → 1.3.4

package/dist/encoder.js

@@ -8,16 +8,16 @@ const BINARY_OPS = {
     [ts.SyntaxKind.AmpersandToken]: { module: "std", function: "bitwise_and" },
     [ts.SyntaxKind.BarToken]: { module: "std", function: "bitwise_or" },
     [ts.SyntaxKind.CaretToken]: { module: "std", function: "bitwise_xor" },
-    [ts.SyntaxKind.LessThanLessThanToken]: { module: "std", function: "shift_left" },
-    [ts.SyntaxKind.GreaterThanGreaterThanToken]: { module: "std", function: "shift_right" },
+    [ts.SyntaxKind.LessThanLessThanToken]: { module: "std", function: "left_shift" },
+    [ts.SyntaxKind.GreaterThanGreaterThanToken]: { module: "std", function: "right_shift" },
     [ts.SyntaxKind.EqualsEqualsEqualsToken]: { module: "std", function: "equals" },
     [ts.SyntaxKind.ExclamationEqualsEqualsToken]: { module: "std", function: "not_equals" },
     [ts.SyntaxKind.EqualsEqualsToken]: { module: "std", function: "equals" },
     [ts.SyntaxKind.ExclamationEqualsToken]: { module: "std", function: "not_equals" },
     [ts.SyntaxKind.LessThanToken]: { module: "std", function: "less_than" },
     [ts.SyntaxKind.GreaterThanToken]: { module: "std", function: "greater_than" },
-    [ts.SyntaxKind.LessThanEqualsToken]: { module: "std", function: "less_than_or_equal" },
-    [ts.SyntaxKind.GreaterThanEqualsToken]: { module: "std", function: "greater_than_or_equal" },
+    [ts.SyntaxKind.LessThanEqualsToken]: { module: "std", function: "lte" },
+    [ts.SyntaxKind.GreaterThanEqualsToken]: { module: "std", function: "gte" },
     [ts.SyntaxKind.AmpersandAmpersandToken]: { module: "std", function: "and" },
     [ts.SyntaxKind.BarBarToken]: { module: "std", function: "or" },
     [ts.SyntaxKind.QuestionQuestionToken]: { module: "std", function: "null_coalesce" },
@@ -39,9 +39,11 @@ const COMPOUND_OPS = {
 export class TsEncoder {
     stdFunctions = new Set();
     warnings = [];
+    strict = false;
     encode(source, options = {}) {
         const modName = options.moduleName ?? "main";
         const entryFn = options.entryFunction ?? "main";
+        this.strict = options.strict ?? false;
         const sourceFile = ts.createSourceFile("input.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
         const functions = [];
         const typeDefs = [];
@@ -68,7 +70,7 @@ export class TsEncoder {
                     if (ts.isIdentifier(decl.name)) {
                         functions.push({
                             name: decl.name.text,
-                            body: decl.initializer ? this.encodeExpr(decl.initializer) : { literal: { stringValue: "" } },
+                            body: decl.initializer ? this.encodeExpr(decl.initializer) : this.nullLiteral(),
                             metadata: { kind: "top_level_variable" },
                         });
                     }
@@ -110,8 +112,8 @@ export class TsEncoder {
                 });
             }
         }
-        const stdModule = this.buildStdModule();
-        const modules = [stdModule];
+        const baseModules = this.buildBaseModules();
+        const modules = [...baseModules];
         const userModule = {
             name: modName,
             functions,
@@ -132,28 +134,31 @@ export class TsEncoder {
         const name = node.name ? (ts.isIdentifier(node.name) ? node.name.text : node.name.getText()) : "";
         const params = node.parameters.map(p => ts.isIdentifier(p.name) ? p.name.text : p.name.getText());
         const metadata = {};
-        if (params.length > 0)
-            metadata["params"] = params;
+        if (params.length > 0) {
+            // Emit params as an array of structs with a `name` field (and optional
+            // `type`, `default`, `is_rest` etc.), matching the Dart encoder format.
+            // The engine's _extractParams filters for structValue entries and reads
+            // each entry's `.structValue.fields.name.stringValue`.
+            const paramStructs = [];
+            for (const p of node.parameters) {
+                const pName = ts.isIdentifier(p.name) ? p.name.text : p.name.getText();
+                const pm = { name: pName };
+                if (p.type)
+                    pm["type"] = p.type.getText();
+                if (p.initializer)
+                    pm["default"] = p.initializer.getText();
+                if (p.dotDotDotToken)
+                    pm["is_rest"] = true;
+                paramStructs.push(pm);
+            }
+            metadata["params"] = paramStructs;
+        }
         if (node.type)
             metadata["returnType"] = node.type.getText();
         // Async functions
         if (node.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
             metadata["is_async"] = true;
         }
-        // Rest parameters
-        const lastParam = node.parameters[node.parameters.length - 1];
-        if (lastParam?.dotDotDotToken) {
-            metadata["rest_param"] = ts.isIdentifier(lastParam.name) ? lastParam.name.text : lastParam.name.getText();
-        }
-        // Default parameter values
-        const defaults = {};
-        for (const p of node.parameters) {
-            if (p.initializer && ts.isIdentifier(p.name)) {
-                defaults[p.name.text] = p.initializer.getText();
-            }
-        }
-        if (Object.keys(defaults).length > 0)
-            metadata["param_defaults"] = defaults;
         const body = node.body ? this.encodeBody(node.body) : undefined;
         const fn = { name };
         if (body)
@@ -286,6 +291,22 @@ export class TsEncoder {
         if (ts.isBlock(node)) {
             return [{ expression: this.encodeBlock(node) }];
         }
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            // Inner function declaration: encode as a let binding with a lambda.
+            const fnDef = this.encodeFunction(node);
+            return [{
+                    let: {
+                        name: fnDef.name,
+                        value: {
+                            lambda: {
+                                name: fnDef.name,
+                                body: fnDef.body,
+                                metadata: fnDef.metadata,
+                            },
+                        },
+                    },
+                }];
+        }
         this.warn(`Unhandled statement kind: ${ts.SyntaxKind[node.kind]}`);
         return [{ expression: { literal: { stringValue: `/* unhandled: ${ts.SyntaxKind[node.kind]} */` } } }];
     }
@@ -307,9 +328,16 @@ export class TsEncoder {
             return { literal: { boolValue: false } };
         }
         if (node.kind === ts.SyntaxKind.NullKeyword || node.kind === ts.SyntaxKind.UndefinedKeyword) {
-            return { literal: { stringValue: "" } };
+            return this.nullLiteral();
         }
         if (ts.isIdentifier(node)) {
+            // `undefined` is parsed as an identifier in expression position, not as
+            // a keyword. Encode it as the canonical null literal so it round-trips
+            // to `null` rather than an unbound reference. (NaN/Infinity stay as
+            // references — they resolve to real globals.)
+            if (node.text === "undefined") {
+                return this.nullLiteral();
+            }
             return { reference: { name: node.text } };
         }
         if (ts.isBinaryExpression(node)) {
@@ -329,7 +357,7 @@ export class TsEncoder {
                 return this.stdCall("optional_access", [
                     { name: "object", value: this.encodeExpr(node.expression) },
                     { name: "field", value: { literal: { stringValue: node.name.text } } },
-                ], "ts_std");
+                ]);
             }
             return { fieldAccess: { object: this.encodeExpr(node.expression), field: node.name.text } };
         }
@@ -338,7 +366,7 @@ export class TsEncoder {
                 return this.stdCall("optional_access", [
                     { name: "object", value: this.encodeExpr(node.expression) },
                     { name: "field", value: this.encodeExpr(node.argumentExpression) },
-                ], "ts_std");
+                ]);
             }
             return this.stdCall("index", [
                 { name: "target", value: this.encodeExpr(node.expression) },
@@ -369,7 +397,7 @@ export class TsEncoder {
                             value: this.stdCall("computed_property", [
                                 { name: "key", value: this.encodeExpr(prop.name.expression) },
                                 { name: "value", value: this.encodeExpr(prop.initializer) },
-                            ], "ts_std"),
+                            ]),
                         });
                     }
                     else {
@@ -387,7 +415,7 @@ export class TsEncoder {
                         name: "__spread",
                         value: this.stdCall("spread", [
                             { name: "value", value: this.encodeExpr(prop.expression) },
-                        ], "ts_std"),
+                        ]),
                     });
                 }
             }
@@ -396,8 +424,8 @@ export class TsEncoder {
         if (ts.isConditionalExpression(node)) {
             return this.stdCall("if", [
                 { name: "condition", value: this.encodeExpr(node.condition) },
-                { name: "then", value: { lambda: { name: "", body: this.encodeExpr(node.whenTrue) } } },
-                { name: "else", value: { lambda: { name: "", body: this.encodeExpr(node.whenFalse) } } },
+                { name: "then", value: this.encodeExpr(node.whenTrue) },
+                { name: "else", value: this.encodeExpr(node.whenFalse) },
             ]);
         }
         if (ts.isTemplateExpression(node)) {
@@ -427,10 +455,13 @@ export class TsEncoder {
         if (ts.isSpreadElement(node)) {
             return this.stdCall("spread", [
                 { name: "value", value: this.encodeExpr(node.expression) },
-            ], "ts_std");
+            ]);
         }
         if (ts.isVoidExpression(node)) {
-            return { literal: { stringValue: "" } };
+            // `void <expr>` always evaluates to `undefined`; encode as null.
+            // (The operand's side effects are dropped — matching how the engine
+            // treats a discarded value; this mirrors the prior behaviour.)
+            return this.nullLiteral();
         }
         if (ts.isTaggedTemplateExpression(node)) {
             return this.encodeTaggedTemplate(node);
@@ -454,7 +485,7 @@ export class TsEncoder {
                 { name: "op", value: { literal: { stringValue: compound } } },
             ]);
         }
-        if (op === ts.SyntaxKind.PlusToken && this.looksLikeStringConcat(node)) {
+        if (op === ts.SyntaxKind.PlusToken && this.isProvablyString(node.left, node.right)) {
             return this.stdCall("concat", [
                 { name: "left", value: this.encodeExpr(node.left) },
                 { name: "right", value: this.encodeExpr(node.right) },
@@ -476,9 +507,35 @@ export class TsEncoder {
         this.warn(`Unhandled binary operator: ${ts.SyntaxKind[op]}`);
         return { literal: { stringValue: `/* binary: ${ts.SyntaxKind[op]} */` } };
     }
-    looksLikeStringConcat(node) {
-        return ts.isStringLiteral(node.left) || ts.isStringLiteral(node.right) ||
-            ts.isTemplateExpression(node.left) || ts.isNoSubstitutionTemplateLiteral(node.left);
+    /// Decide how to encode a `+` whose operands aren't both provable strings.
+    ///
+    /// `std.add` is runtime-polymorphic — the engine concatenates when either
+    /// operand is a string and adds numerically otherwise (see
+    /// `compiled_engine.ts:_stdAdd`). `std.concat`, by contrast, *always*
+    /// stringifies both sides, so emitting it for `1 + 2` would yield `"12"`.
+    ///
+    /// We therefore only emit the dedicated `concat` when at least one operand
+    /// is *provably* a string (a string literal/template, or a nested `+` that
+    /// is itself provably a concat). For every other shape — including
+    /// `strVar + strVar`, where the static type is unknown — we fall through to
+    /// the polymorphic `std.add`, letting the engine coerce at runtime instead
+    /// of guessing from literal shape. This avoids both the false-numeric and
+    /// false-concat hazards.
+    isProvablyString(left, right) {
+        return this.isStringExpr(left) || this.isStringExpr(right);
+    }
+    isStringExpr(node) {
+        if (ts.isParenthesizedExpression(node))
+            return this.isStringExpr(node.expression);
+        if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ||
+            ts.isTemplateExpression(node)) {
+            return true;
+        }
+        // A nested `a + b` that is itself a provable concat produces a string.
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
+            return this.isProvablyString(node.left, node.right);
+        }
+        return false;
     }
     encodePrefixUnary(node) {
         const op = node.operator;
@@ -526,15 +583,61 @@ export class TsEncoder {
             value: this.encodeExpr(a),
         }));
         if (ts.isPropertyAccessExpression(node.expression)) {
-            const obj = this.encodeExpr(node.expression.expression);
             const method = node.expression.name.text;
+            // console.log(x) / console.log(x, y, ...) → std.print per argument.
+            // console.error(x) → std.print_error(x).
+            // This ensures that TS programs using the idiomatic console API are
+            // faithfully represented in Ball IR using the universal std module, so
+            // the Ball engine can execute them without a "console" module.
+            if (ts.isIdentifier(node.expression.expression) &&
+                node.expression.expression.text === "console") {
+                if (method === "log" || method === "info" || method === "warn") {
+                    if (args.length === 0) {
+                        return this.stdCall("print", [
+                            { name: "message", value: { literal: { stringValue: "" } } },
+                        ]);
+                    }
+                    if (args.length === 1) {
+                        return this.stdCall("print", [
+                            { name: "message", value: args[0].value },
+                        ]);
+                    }
+                    // Multiple arguments: emit one std.print per arg inside a block.
+                    const stmts = args.map(a => ({
+                        expression: this.stdCall("print", [
+                            { name: "message", value: a.value },
+                        ]),
+                    }));
+                    return { block: { statements: stmts } };
+                }
+                if (method === "error") {
+                    if (args.length >= 1) {
+                        return this.stdCall("print_error", [
+                            { name: "message", value: args[0].value },
+                        ]);
+                    }
+                    return this.stdCall("print_error", [
+                        { name: "message", value: { literal: { stringValue: "" } } },
+                    ]);
+                }
+            }
+            const obj = this.encodeExpr(node.expression.expression);
+            // Map common JS/TS method calls to their Ball std equivalents.
+            // The engine's std module uses snake_case names with type prefixes.
+            const stdMethod = this.mapMethodToStd(method, args);
+            if (stdMethod) {
+                return this.stdCall(stdMethod.fn, [
+                    { name: stdMethod.selfName ?? "value", value: obj },
+                    ...stdMethod.extraFields(args),
+                ], stdMethod.module ?? "std");
+            }
             // Optional chaining call: obj?.method()
             if (node.expression.questionDotToken || node.questionDotToken) {
                 return this.stdCall("optional_call", [
                     { name: "object", value: obj },
                     { name: "method", value: { literal: { stringValue: method } } },
                     ...args,
-                ], "ts_std");
+                ]);
             }
             return {
                 call: {
@@ -579,25 +682,26 @@ export class TsEncoder {
         const params = node.parameters.map(p => ts.isIdentifier(p.name) ? p.name.text : p.name.getText());
         const body = node.body ? this.encodeBody(ts.isBlock(node.body) ? node.body : node.body) : undefined;
         const metadata = {};
-        if (params.length > 0)
-            metadata["params"] = params;
+        if (params.length > 0) {
+            // Emit params as structs with a `name` field, matching the Dart encoder
+            // format and the engine's _extractParams expectations.
+            const paramStructs = [];
+            for (const p of node.parameters) {
+                const pName = ts.isIdentifier(p.name) ? p.name.text : p.name.getText();
+                const pm = { name: pName };
+                if (p.type)
+                    pm["type"] = p.type.getText();
+                if (p.initializer)
+                    pm["default"] = p.initializer.getText();
+                if (p.dotDotDotToken)
+                    pm["is_rest"] = true;
+                paramStructs.push(pm);
+            }
+            metadata["params"] = paramStructs;
+        }
         if (node.modifiers?.some(m => m.kind === ts.SyntaxKind.AsyncKeyword)) {
             metadata["is_async"] = true;
         }
-        // Rest parameters
-        const lastParam = node.parameters[node.parameters.length - 1];
-        if (lastParam?.dotDotDotToken) {
-            metadata["rest_param"] = ts.isIdentifier(lastParam.name) ? lastParam.name.text : lastParam.name.getText();
-        }
-        // Default parameter values
-        const defaults = {};
-        for (const p of node.parameters) {
-            if (p.initializer && ts.isIdentifier(p.name)) {
-                defaults[p.name.text] = p.initializer.getText();
-            }
-        }
-        if (Object.keys(defaults).length > 0)
-            metadata["param_defaults"] = defaults;
         // Destructured parameters
         const destructured = {};
         for (const p of node.parameters) {
@@ -617,43 +721,56 @@ export class TsEncoder {
         };
     }
     encodeIf(node) {
+        // Control flow fields (then, else) are direct expressions — NOT lambdas.
+        // The engine evaluates them lazily (Ball invariant #4).  Wrapping in a
+        // lambda would eat flow signals like std.return/break/continue.
         const fields = [
             { name: "condition", value: this.encodeExpr(node.expression) },
-            { name: "then", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.thenStatement) ? node.thenStatement : ts.factory.createBlock([node.thenStatement])) } } },
+            { name: "then", value: this.encodeBody(ts.isBlock(node.thenStatement) ? node.thenStatement : ts.factory.createBlock([node.thenStatement])) },
         ];
         if (node.elseStatement) {
             if (ts.isIfStatement(node.elseStatement)) {
-                fields.push({ name: "else", value: { lambda: { name: "", body: this.encodeIf(node.elseStatement) } } });
+                fields.push({ name: "else", value: this.encodeIf(node.elseStatement) });
             }
             else {
-                fields.push({ name: "else", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.elseStatement) ? node.elseStatement : ts.factory.createBlock([node.elseStatement])) } } });
+                fields.push({ name: "else", value: this.encodeBody(ts.isBlock(node.elseStatement) ? node.elseStatement : ts.factory.createBlock([node.elseStatement])) });
             }
         }
         return this.stdCall("if", fields);
     }
     encodeFor(node) {
+        // Control flow fields are direct expressions — the engine evaluates them
+        // lazily. No lambda wrappers (see encodeIf comment).
+        //
+        // The engine's _evalLazyFor reads `init` (not `variable`/`start`).
+        // For a variable declaration `let i = 0`, emit a block with a let binding.
+        // For a bare expression initializer, emit the expression directly.
         const fields = [];
         if (node.initializer) {
             if (ts.isVariableDeclarationList(node.initializer)) {
-                const decls = node.initializer.declarations;
-                if (decls.length > 0) {
-                    const d = decls[0];
-                    fields.push({ name: "variable", value: { literal: { stringValue: ts.isIdentifier(d.name) ? d.name.text : d.name.getText() } } });
-                    if (d.initializer)
-                        fields.push({ name: "start", value: this.encodeExpr(d.initializer) });
+                const stmts = [];
+                for (const d of node.initializer.declarations) {
+                    const varName = ts.isIdentifier(d.name) ? d.name.text : d.name.getText();
+                    stmts.push({
+                        let: {
+                            name: varName,
+                            value: d.initializer ? this.encodeExpr(d.initializer) : undefined,
+                        },
+                    });
                 }
+                fields.push({ name: "init", value: { block: { statements: stmts } } });
             }
             else {
-                fields.push({ name: "init", value: { lambda: { name: "", body: this.encodeExpr(node.initializer) } } });
+                fields.push({ name: "init", value: this.encodeExpr(node.initializer) });
             }
         }
         if (node.condition) {
-            fields.push({ name: "condition", value: { lambda: { name: "", body: this.encodeExpr(node.condition) } } });
+            fields.push({ name: "condition", value: this.encodeExpr(node.condition) });
         }
         if (node.incrementor) {
-            fields.push({ name: "update", value: { lambda: { name: "", body: this.encodeExpr(node.incrementor) } } });
+            fields.push({ name: "update", value: this.encodeExpr(node.incrementor) });
         }
-        fields.push({ name: "body", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) } } });
+        fields.push({ name: "body", value: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) });
         return this.stdCall("for", fields);
     }
     encodeForOf(node) {
@@ -666,39 +783,44 @@ export class TsEncoder {
         return this.stdCall(fnName, [
             { name: "variable", value: { literal: { stringValue: varName } } },
             { name: "iterable", value: this.encodeExpr(node.expression) },
-            { name: "body", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) } } },
+            { name: "body", value: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) },
         ]);
     }
     encodeWhile(node) {
         return this.stdCall("while", [
-            { name: "condition", value: { lambda: { name: "", body: this.encodeExpr(node.expression) } } },
-            { name: "body", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) } } },
+            { name: "condition", value: this.encodeExpr(node.expression) },
+            { name: "body", value: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) },
         ]);
     }
     encodeDoWhile(node) {
         return this.stdCall("do_while", [
-            { name: "condition", value: { lambda: { name: "", body: this.encodeExpr(node.expression) } } },
-            { name: "body", value: { lambda: { name: "", body: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) } } },
+            { name: "condition", value: this.encodeExpr(node.expression) },
+            { name: "body", value: this.encodeBody(ts.isBlock(node.statement) ? node.statement : ts.factory.createBlock([node.statement])) },
         ]);
     }
     encodeTry(node) {
+        // try body is a direct block expression (not a lambda).
         const fields = [
-            { name: "body", value: { lambda: { name: "", body: this.encodeBlock(node.tryBlock) } } },
+            { name: "body", value: this.encodeBlock(node.tryBlock) },
         ];
         if (node.catchClause) {
             const cc = node.catchClause;
+            // The Dart encoder emits catches as a listValue of catch entries, each
+            // with optional `type`, `variable`, and `body` fields.  TS catch clauses
+            // are untyped, so we omit the `type` field.
             const catchFields = [];
             if (cc.variableDeclaration && ts.isIdentifier(cc.variableDeclaration.name)) {
                 catchFields.push({ name: "variable", value: { literal: { stringValue: cc.variableDeclaration.name.text } } });
             }
-            catchFields.push({ name: "body", value: { lambda: { name: "", body: this.encodeBlock(cc.block) } } });
+            catchFields.push({ name: "body", value: this.encodeBlock(cc.block) });
+            const catchEntry = { messageCreation: { typeName: "", fields: catchFields } };
             fields.push({
-                name: "catch",
-                value: { messageCreation: { typeName: "", fields: catchFields } },
+                name: "catches",
+                value: { literal: { listValue: { elements: [catchEntry] } } },
             });
         }
         if (node.finallyBlock) {
-            fields.push({ name: "finally", value: { lambda: { name: "", body: this.encodeBlock(node.finallyBlock) } } });
+            fields.push({ name: "finally", value: this.encodeBlock(node.finallyBlock) });
         }
         return this.stdCall("try", fields);
     }
@@ -710,17 +832,17 @@ export class TsEncoder {
                 caseFields.push({ name: "value", value: this.encodeExpr(clause.expression) });
             }
             else {
-                caseFields.push({ name: "isDefault", value: { literal: { boolValue: true } } });
+                caseFields.push({ name: "is_default", value: { literal: { boolValue: true } } });
             }
             const stmts = [];
             for (const s of clause.statements) {
                 stmts.push(...this.encodeStatement(s));
             }
-            caseFields.push({ name: "body", value: { lambda: { name: "", body: { block: { statements: stmts } } } } });
+            caseFields.push({ name: "body", value: { block: { statements: stmts } } });
             cases.push({ messageCreation: { typeName: "", fields: caseFields } });
         }
         return this.stdCall("switch", [
-            { name: "value", value: this.encodeExpr(node.expression) },
+            { name: "subject", value: this.encodeExpr(node.expression) },
             { name: "cases", value: { literal: { listValue: { elements: cases } } } },
         ]);
     }
@@ -859,7 +981,87 @@ export class TsEncoder {
             { name: "tag", value: tag },
             { name: "strings", value: { literal: { listValue: { elements: parts } } } },
             { name: "expressions", value: { literal: { listValue: { elements: exprs } } } },
-        ], "ts_std");
+        ]);
+    }
+    /**
+     * Map a JS/TS method name to its Ball std function equivalent.
+     * Returns null if no mapping exists (falls through to generic method call).
+     */
+    mapMethodToStd(method, _args) {
+        // String methods
+        const STR_METHODS = {
+            toUpperCase: "string_to_upper_case",
+            toLowerCase: "string_to_lower_case",
+            trim: "string_trim",
+            trimStart: "string_trim_left",
+            trimEnd: "string_trim_right",
+            includes: "string_contains",
+            indexOf: "string_index_of",
+            startsWith: "string_starts_with",
+            endsWith: "string_ends_with",
+            split: "string_split",
+            substring: "string_substring",
+            slice: "string_substring",
+            replace: "string_replace_first",
+            replaceAll: "string_replace_all",
+            padStart: "string_pad_left",
+            padEnd: "string_pad_right",
+            repeat: "string_repeat",
+            charAt: "string_char_at",
+            charCodeAt: "string_code_unit_at",
+        };
+        if (method in STR_METHODS) {
+            return {
+                fn: STR_METHODS[method],
+                selfName: "value",
+                extraFields: (a) => a.map((x, i) => ({
+                    name: i === 0 ? "other" : `arg${i}`,
+                    value: x.value,
+                })),
+            };
+        }
+        // Array methods
+        const ARR_METHODS = {
+            push: { fn: "list_add" },
+            pop: { fn: "list_remove_last" },
+            indexOf: { fn: "list_index_of", mod: "std_collections" },
+            includes: { fn: "list_contains", mod: "std_collections" },
+            join: { fn: "list_join", mod: "std_collections" },
+            reverse: { fn: "list_reversed", mod: "std_collections" },
+            slice: { fn: "list_sublist", mod: "std_collections" },
+            splice: { fn: "list_remove_at" },
+            sort: { fn: "list_sort", mod: "std_collections" },
+            map: { fn: "list_map", mod: "std_collections" },
+            filter: { fn: "list_where", mod: "std_collections" },
+            forEach: { fn: "list_for_each", mod: "std_collections" },
+            reduce: { fn: "list_fold", mod: "std_collections" },
+            find: { fn: "list_first_where", mod: "std_collections" },
+            flat: { fn: "list_flatten", mod: "std_collections" },
+            concat: { fn: "list_concat", mod: "std_collections" },
+            every: { fn: "list_every", mod: "std_collections" },
+            some: { fn: "list_any", mod: "std_collections" },
+        };
+        if (method in ARR_METHODS) {
+            const m = ARR_METHODS[method];
+            return {
+                fn: m.fn,
+                module: m.mod,
+                selfName: "list",
+                extraFields: (a) => a.map((x, i) => ({
+                    name: i === 0 ? "value" : `arg${i}`,
+                    value: x.value,
+                })),
+            };
+        }
+        // toString
+        if (method === "toString") {
+            return {
+                fn: "to_string",
+                selfName: "value",
+                extraFields: () => [],
+            };
+        }
+        return null;
     }
     stdCall(fn, fields, module = "std") {
         this.stdFunctions.add(`${module}:${fn}`);
@@ -873,23 +1075,74 @@ export class TsEncoder {
             },
         };
     }
-    buildStdModule() {
-        const functions = [];
+    buildBaseModules() {
+        const byModule = new Map();
         for (const ref of this.stdFunctions) {
-            const [, fn] = ref.split(":");
-            functions.push({ name: fn, isBase: true });
+            const [mod, fn] = ref.split(":");
+            if (!byModule.has(mod))
+                byModule.set(mod, []);
+            byModule.get(mod).push(fn);
+        }
+        const modules = [];
+        for (const [mod, fns] of byModule) {
+            fns.sort();
+            modules.push({
+                name: mod,
+                functions: fns.map(fn => ({ name: fn, isBase: true })),
+            });
         }
-        functions.sort((a, b) => a.name.localeCompare(b.name));
-        return { name: "std", functions };
+        modules.sort((a, b) => a.name === "std" ? -1 : b.name === "std" ? 1 : a.name.localeCompare(b.name));
+        return modules;
+    }
+    /// The canonical encoding of `null`/`undefined`/`void`.
+    ///
+    /// The Dart encoder represents a null literal as an *empty* `Literal`
+    /// message with no `value` oneof field set (see
+    /// `dart/encoder/lib/encoder.dart`: `Expression()..literal = Literal()`).
+    /// We match that exactly: `{ literal: {} }`. Both engines treat an empty
+    /// literal as `null` (the TS compiler's `compileLiteral` falls through to
+    /// `return "null"` when no value field is present), so this round-trips
+    /// correctly and is no longer conflated with the empty string `""`.
+    nullLiteral() {
+        return { literal: {} };
     }
     warn(msg) {
         this.warnings.push(msg);
+        // In strict mode an unhandled node is a hard error: the encoder cannot
+        // faithfully represent the construct and would otherwise emit a
+        // `/* unhandled */` placeholder literal that silently changes semantics.
+        if (this.strict) {
+            throw new EncodeError(msg, this.getWarnings());
+        }
     }
     getWarnings() {
         return [...this.warnings];
     }
 }
+/// Thrown by `encode(..., { strict: true })` when the encoder hits a TS
+/// construct it cannot represent. Carries the full accumulated warning list.
+export class EncodeError extends Error {
+    warnings;
+    constructor(message, warnings) {
+        super(message);
+        this.name = "EncodeError";
+        this.warnings = warnings;
+    }
+}
+/// Encode `source` to a Ball `Program`.
+///
+/// The simple overload returns just the `Program` for backwards
+/// compatibility. Pass `{ strict: true }` to throw an `EncodeError` on any
+/// unhandled construct. To inspect non-fatal warnings without strict mode,
+/// use `encodeWithWarnings`.
 export function encode(source, options = {}) {
     return new TsEncoder().encode(source, options);
 }
+/// Like `encode`, but also surfaces the accumulated warnings (e.g. unhandled
+/// statement/expression kinds). Honors `options.strict` the same way.
+export function encodeWithWarnings(source, options = {}) {
+    const encoder = new TsEncoder();
+    const program = encoder.encode(source, options);
+    return { program, warnings: encoder.getWarnings() };
+}
 //# sourceMappingURL=encoder.js.map