@ball-lang/compiler 1.66.2 → 1.67.0

package/README.md

@@ -58,6 +58,10 @@ console.log(tsSource); // emitted TypeScript
 ## API
 
 - `compile(program: Program, options?: CompileOptions): string` — compile a whole program to TypeScript source.
+- `compileLibrary(program: Program, options?: CompileLibraryOptions): string` —
+  compile a whole Program as a **library**: no assumed entry point, no
+  synthesized invocation, every top-level declaration exported. The analog of
+  `compile_library`/`CompileLibrary` in the Rust/Go/Python compilers.
 - `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.

package/dist/compiler.d.ts

@@ -5,6 +5,13 @@ export interface CompileOptions {
     /** Output file path hint (affects ts-morph's internal resolution). */
     fileName?: string;
 }
+/** Options for {@link BallCompiler.compileLibrary}. */
+export interface CompileLibraryOptions {
+    /** 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;
+}
 export declare class BallCompiler {
     private readonly program;
     /** Buffer that _emit* functions write into. */
@@ -86,6 +93,59 @@ export declare class BallCompiler {
     constructor(program: Program);
     /** Compile to TS source. */
     compile(options?: CompileOptions): string;
+    /**
+     * Compile the whole Program to a TypeScript LIBRARY — no assumed entry
+     * point, no synthesized invocation, every top-level declaration exported.
+     *
+     * The TS sibling of `rust/compiler`'s `compile_library`, `go/compiler`'s
+     * `CompileLibrary`, `python/compiler`'s `compile_library`, C#'s
+     * entry-optional `Compile` and Dart's `DartCompiler.compileModule`. Use it
+     * for code that was never written to be run as a program — the third-party
+     * library files the coverage study measures (issue #536), or any Ball
+     * Program consumed as a module.
+     *
+     * Three things it deliberately does differently from `compile()`:
+     *
+     * 1. It NEVER looks up `program.entryFunction`. `@ball-lang/encoder`
+     *    defaults that field to `"main"` for every file it encodes, so
+     *    `compile()` appends a zero-arg `main();` to any library that merely
+     *    happens to declare `main(argv: string[])` — a wrong-arity call that
+     *    throws at run time. Here such a declaration is an ordinary function.
+     * 2. It does not require an entry module to exist. "No entry" is the normal
+     *    case for a library, not an error, so every non-base module present is
+     *    compiled.
+     * 3. It exports STRUCTURALLY, through ts-morph's `isExported`, never by
+     *    rewriting the formatted output text afterwards the way `compileModule`
+     *    does. A regex matched against emitted source rots silently the moment
+     *    the emitter's formatting shifts (see the #489/#499 note further down
+     *    this file for a pass that did exactly that).
+     *
+     * It also emits none of `compile()`'s engine-specific post-processing — not
+     * the `__isUnknownFnError` helper, not the `_evalCall`/`_Scope` patches.
+     * Those exist to repair the ONE self-hosted engine `compile()` produces; a
+     * library compile of somebody else's code must not gain declarations its
+     * source never had, or a round-trip can never reach a fixpoint.
+     */
+    compileLibrary(options?: CompileLibraryOptions): string;
+    /**
+     * Emit every declaration of the program's non-base modules into `sf`.
+     *
+     * Shared verbatim by `compile()` (whole-program, `library = false`) and
+     * `compileLibrary()` (`library = true`). The two differ in exactly two
+     * places, both threaded through `library`:
+     *
+     *  - the entry function is skipped here in program mode (`compile()`
+     *    emits it last, renamed to `main`, followed by its invocation) but is
+     *    an ordinary declaration in library mode;
+     *  - top-level functions and variables carry `export` in library mode.
+     *    Classes, enum classes and type aliases are already exported in both.
+     *
+     * Everything else — module collection, the linear-memory preamble, the
+     * name/typeDef lookup tables, class/mixin grouping, typedefs, enums,
+     * top-level variables and free functions — is ONE implementation, so a
+     * fix to either caller lands in both.
+     */
+    private emitDeclarations;
     private emitFreeFunction;
     /** Wrap captured statements in an IIFE, choosing the right kind:
      *  - yield present → `yield* (function* () { ... })()`
@@ -295,6 +355,14 @@ export declare class BallCompiler {
 }
 /** Convenience: compile a Program directly. */
 export declare function compile(program: Program, options?: CompileOptions): string;
+/**
+ * Convenience: compile a Program as a LIBRARY — no assumed entry point, no
+ * synthesized invocation, every top-level declaration exported.
+ *
+ * See {@link BallCompiler.compileLibrary} for why this is a separate primitive
+ * rather than a flag on `compile()`.
+ */
+export declare function compileLibrary(program: Program, options?: CompileLibraryOptions): string;
 export interface CompileModuleOptions {
     /** Include the runtime preamble at the top of the output. Default true. */
     includePreamble?: boolean;

package/dist/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"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"}

package/dist/compiler.js

@@ -107,145 +107,7 @@ export class BallCompiler {
         if (!entryMod) {
             throw new Error(`Entry module "${this.program.entryModule}" not found`);
         }
-        // Collect ALL non-base modules (entry + user library modules).
-        const userModules = [];
-        let usesStdMemory = false;
-        for (const mod of this.program.modules ?? []) {
-            const fns = mod.functions ?? [];
-            const allBase = fns.length > 0 && fns.every((f) => f.isBase);
-            if (allBase) {
-                if (mod.name === "std_memory")
-                    usesStdMemory = true;
-                continue;
-            }
-            userModules.push(mod);
-        }
-        // ── Linear memory runtime preamble ──
-        // If the program imports `std_memory` (linear memory simulation), inject
-        // the runtime variables backing the `ByteData`/`Endian` shims already
-        // defined in the (always-included) runtime preamble. Mirrors the Dart
-        // compiler's conditional injection (dart/compiler/lib/compiler.dart,
-        // "Linear memory runtime preamble") — only emitted when actually used.
-        if (usesStdMemory) {
-            sf.addStatements("// Ball linear memory runtime\n" +
-                "const _ballMemory = new ByteData(65536);\n" +
-                "let _ballHeapPtr = 0;\n" +
-                "const _ballStackFrames: number[] = [];\n" +
-                "let _ballStackPtr = 65536;\n");
-        }
-        // Seed the function-name + typeDef lookup tables from ALL user modules.
-        this.allFunctionNames = new Set(userModules.flatMap((m) => (m.functions ?? []).map((f) => f.name)));
-        this.asyncFnNames = new Set(userModules.flatMap((m) => (m.functions ?? [])
-            .filter((f) => f.metadata?.["is_async"] === true)
-            .map((f) => f.name)));
-        this.typeDefByName = new Map(userModules.flatMap((m) => (m.typeDefs ?? []).map((td) => [td.name, td])));
-        // Group functions by their enclosing class (if any) — matches the
-        // `<typeDef.name>.<member>` naming convention from the encoder.
-        const classMembers = new Map();
-        const freeFunctions = [];
-        for (const mod of userModules) {
-            for (const fn of mod.functions ?? []) {
-                if (fn.isBase)
-                    continue;
-                if (fn.name === this.program.entryFunction)
-                    continue;
-                const enclosing = this.enclosingTypeName(fn.name);
-                if (enclosing) {
-                    const list = classMembers.get(enclosing) ?? [];
-                    list.push(fn);
-                    classMembers.set(enclosing, list);
-                }
-                else {
-                    freeFunctions.push(fn);
-                }
-            }
-        }
-        // Typedefs → TsTypeAlias (from all user modules).
-        for (const mod of userModules) {
-            for (const ta of mod.typeAliases ?? []) {
-                sf.addTypeAlias({
-                    name: ta.name,
-                    type: this.dartTypeToTs(ta.targetType),
-                    isExported: true,
-                });
-            }
-        }
-        // Classes.
-        // BallObject / BallMap / BallList are runtime container types supplied by
-        // the preamble (a Ball instance is a plain-object-like BallObject, a map a
-        // plain object, a list a plain array). Skip emitting their class bodies —
-        // the encoder's versions reference the inherited `entries` field via bare
-        // identifiers and take named ctor args the emitter can't reproduce; the
-        // hand-written preamble versions are the source of truth.
-        const _runtimeContainerTypes = new Set(["BallObject", "BallMap", "BallList"]);
-        const allTypeDefs = userModules.flatMap((m) => m.typeDefs ?? []);
-        for (const td of allTypeDefs) {
-            if (_runtimeContainerTypes.has(classTsName(td.name)))
-                continue;
-            // Collect members for this class, including mixin members.
-            let members = [...(classMembers.get(td.name) ?? [])];
-            const tdMeta = td.metadata ?? {};
-            const mixins = Array.isArray(tdMeta["mixins"]) ? tdMeta["mixins"] : [];
-            if (mixins.length > 0) {
-                // Collect the set of method short names already defined on this class
-                const ownShortNames = new Set(members.map((m) => memberShortName(m.name)));
-                for (const mixinName of mixins) {
-                    // Find the mixin typeDef name — try both plain and module-qualified
-                    let mixinTdName;
-                    for (const [tdName] of this.typeDefByName) {
-                        if (classTsName(tdName) === mixinName || tdName === mixinName || tdName.endsWith(":" + mixinName)) {
-                            mixinTdName = tdName;
-                            break;
-                        }
-                    }
-                    if (!mixinTdName)
-                        continue;
-                    const mixinMembers = classMembers.get(mixinTdName) ?? [];
-                    for (const mm of mixinMembers) {
-                        const shortName = memberShortName(mm.name);
-                        // Only include mixin methods not already defined on this class
-                        if (!ownShortNames.has(shortName)) {
-                            members.push(mm);
-                            ownShortNames.add(shortName);
-                        }
-                    }
-                }
-            }
-            this.emitClass(sf, td, members);
-        }
-        // Enums declared in Module.enums[] (google.protobuf.EnumDescriptorProto,
-        // proto3 JSON: `{name, value: [{name, number}]}`). Both encoders emit
-        // enum declarations here (the Dart encoder with module-qualified names
-        // like "main:Color"); dropping them left `Color.red` references dangling
-        // in the compiled output (#120).
-        const emittedTypeNames = new Set(allTypeDefs.map((td) => classTsName(td.name)));
-        for (const mod of userModules) {
-            for (const en of mod.enums ?? []) {
-                const tsName = classTsName(en.name);
-                // A typeDef of the same name already produced a class declaration.
-                if (emittedTypeNames.has(tsName))
-                    continue;
-                emittedTypeNames.add(tsName);
-                const entries = (en.value ?? []).map((v, i) => ({
-                    name: v.name,
-                    index: typeof v.number === "number" ? v.number : i,
-                }));
-                this.emitEnumClass(sf, tsName, entries);
-            }
-        }
-        // Top-level variables (kind == 'top_level_variable') emit as
-        // `const <name> = <body>;` before free functions.
-        for (const fn of freeFunctions.filter((f) => f.metadata?.kind === "top_level_variable")) {
-            const name = sanitize(fn.name);
-            const body = fn.body ? this.captureInto(() => {
-                this.writeln(`return ${this.expr(fn.body)};`);
-            }) : "undefined";
-            sf.addStatements(`let ${name} = (() => { ${body} })();`);
-        }
-        // Free top-level functions (exclude top-level variables).
-        for (const fn of freeFunctions.filter((f) => f.metadata?.kind !== "top_level_variable")) {
-            this.emitFreeFunction(sf, fn);
-        }
+        this.emitDeclarations(sf, false);
         // Entry function as `main()` + immediate call.
         const entryFn = entryMod.functions.find((f) => f.name === this.program.entryFunction);
         if (entryFn) {
@@ -1956,8 +1818,218 @@ function __isUnknownFnError(e: any): boolean {
         body = unknownFnHelper + body;
         return includePreamble ? TS_RUNTIME_PREAMBLE + "\n" + body : body;
     }
+    /**
+     * Compile the whole Program to a TypeScript LIBRARY — no assumed entry
+     * point, no synthesized invocation, every top-level declaration exported.
+     *
+     * The TS sibling of `rust/compiler`'s `compile_library`, `go/compiler`'s
+     * `CompileLibrary`, `python/compiler`'s `compile_library`, C#'s
+     * entry-optional `Compile` and Dart's `DartCompiler.compileModule`. Use it
+     * for code that was never written to be run as a program — the third-party
+     * library files the coverage study measures (issue #536), or any Ball
+     * Program consumed as a module.
+     *
+     * Three things it deliberately does differently from `compile()`:
+     *
+     * 1. It NEVER looks up `program.entryFunction`. `@ball-lang/encoder`
+     *    defaults that field to `"main"` for every file it encodes, so
+     *    `compile()` appends a zero-arg `main();` to any library that merely
+     *    happens to declare `main(argv: string[])` — a wrong-arity call that
+     *    throws at run time. Here such a declaration is an ordinary function.
+     * 2. It does not require an entry module to exist. "No entry" is the normal
+     *    case for a library, not an error, so every non-base module present is
+     *    compiled.
+     * 3. It exports STRUCTURALLY, through ts-morph's `isExported`, never by
+     *    rewriting the formatted output text afterwards the way `compileModule`
+     *    does. A regex matched against emitted source rots silently the moment
+     *    the emitter's formatting shifts (see the #489/#499 note further down
+     *    this file for a pass that did exactly that).
+     *
+     * It also emits none of `compile()`'s engine-specific post-processing — not
+     * the `__isUnknownFnError` helper, not the `_evalCall`/`_Scope` patches.
+     * Those exist to repair the ONE self-hosted engine `compile()` produces; a
+     * library compile of somebody else's code must not gain declarations its
+     * source never had, or a round-trip can never reach a fixpoint.
+     */
+    compileLibrary(options = {}) {
+        const { includePreamble = true, fileName = "library.ts" } = options;
+        const project = new Project({
+            useInMemoryFileSystem: true,
+            compilerOptions: { target: 99 /* ESNext */ },
+        });
+        const sf = project.createSourceFile(fileName, "", { overwrite: true });
+        this.emitDeclarations(sf, true);
+        sf.formatText({ indentSize: 2, convertTabsToSpaces: true });
+        const body = sf.getFullText();
+        return includePreamble ? TS_RUNTIME_PREAMBLE + "\n" + body : body;
+    }
     // ───────────────────────── Declarations ────────────────────────────
-    emitFreeFunction(sf, fn, forceName, forceAsync) {
+    /**
+     * Emit every declaration of the program's non-base modules into `sf`.
+     *
+     * Shared verbatim by `compile()` (whole-program, `library = false`) and
+     * `compileLibrary()` (`library = true`). The two differ in exactly two
+     * places, both threaded through `library`:
+     *
+     *  - the entry function is skipped here in program mode (`compile()`
+     *    emits it last, renamed to `main`, followed by its invocation) but is
+     *    an ordinary declaration in library mode;
+     *  - top-level functions and variables carry `export` in library mode.
+     *    Classes, enum classes and type aliases are already exported in both.
+     *
+     * Everything else — module collection, the linear-memory preamble, the
+     * name/typeDef lookup tables, class/mixin grouping, typedefs, enums,
+     * top-level variables and free functions — is ONE implementation, so a
+     * fix to either caller lands in both.
+     */
+    emitDeclarations(sf, library) {
+        // Collect ALL non-base modules (entry + user library modules).
+        const userModules = [];
+        let usesStdMemory = false;
+        for (const mod of this.program.modules ?? []) {
+            const fns = mod.functions ?? [];
+            const allBase = fns.length > 0 && fns.every((f) => f.isBase);
+            if (allBase) {
+                if (mod.name === "std_memory")
+                    usesStdMemory = true;
+                continue;
+            }
+            userModules.push(mod);
+        }
+        // ── Linear memory runtime preamble ──
+        // If the program imports `std_memory` (linear memory simulation), inject
+        // the runtime variables backing the `ByteData`/`Endian` shims already
+        // defined in the (always-included) runtime preamble. Mirrors the Dart
+        // compiler's conditional injection (dart/compiler/lib/compiler.dart,
+        // "Linear memory runtime preamble") — only emitted when actually used.
+        if (usesStdMemory) {
+            sf.addStatements("// Ball linear memory runtime\n" +
+                "const _ballMemory = new ByteData(65536);\n" +
+                "let _ballHeapPtr = 0;\n" +
+                "const _ballStackFrames: number[] = [];\n" +
+                "let _ballStackPtr = 65536;\n");
+        }
+        // Seed the function-name + typeDef lookup tables from ALL user modules.
+        this.allFunctionNames = new Set(userModules.flatMap((m) => (m.functions ?? []).map((f) => f.name)));
+        this.asyncFnNames = new Set(userModules.flatMap((m) => (m.functions ?? [])
+            .filter((f) => f.metadata?.["is_async"] === true)
+            .map((f) => f.name)));
+        this.typeDefByName = new Map(userModules.flatMap((m) => (m.typeDefs ?? []).map((td) => [td.name, td])));
+        // Group functions by their enclosing class (if any) — matches the
+        // `<typeDef.name>.<member>` naming convention from the encoder.
+        const classMembers = new Map();
+        const freeFunctions = [];
+        for (const mod of userModules) {
+            for (const fn of mod.functions ?? []) {
+                if (fn.isBase)
+                    continue;
+                // In library mode the entry function is NOT special: a top-level
+                // declaration that merely SHARES program.entryFunction's name (the
+                // ts/encoder default is literally "main") compiles as an ordinary
+                // function, and nothing invokes it.
+                if (!library && fn.name === this.program.entryFunction)
+                    continue;
+                const enclosing = this.enclosingTypeName(fn.name);
+                if (enclosing) {
+                    const list = classMembers.get(enclosing) ?? [];
+                    list.push(fn);
+                    classMembers.set(enclosing, list);
+                }
+                else {
+                    freeFunctions.push(fn);
+                }
+            }
+        }
+        // Typedefs → TsTypeAlias (from all user modules).
+        for (const mod of userModules) {
+            for (const ta of mod.typeAliases ?? []) {
+                sf.addTypeAlias({
+                    name: ta.name,
+                    type: this.dartTypeToTs(ta.targetType),
+                    isExported: true,
+                });
+            }
+        }
+        // Classes.
+        // BallObject / BallMap / BallList are runtime container types supplied by
+        // the preamble (a Ball instance is a plain-object-like BallObject, a map a
+        // plain object, a list a plain array). Skip emitting their class bodies —
+        // the encoder's versions reference the inherited `entries` field via bare
+        // identifiers and take named ctor args the emitter can't reproduce; the
+        // hand-written preamble versions are the source of truth.
+        const _runtimeContainerTypes = new Set(["BallObject", "BallMap", "BallList"]);
+        const allTypeDefs = userModules.flatMap((m) => m.typeDefs ?? []);
+        for (const td of allTypeDefs) {
+            if (_runtimeContainerTypes.has(classTsName(td.name)))
+                continue;
+            // Collect members for this class, including mixin members.
+            let members = [...(classMembers.get(td.name) ?? [])];
+            const tdMeta = td.metadata ?? {};
+            const mixins = Array.isArray(tdMeta["mixins"]) ? tdMeta["mixins"] : [];
+            if (mixins.length > 0) {
+                // Collect the set of method short names already defined on this class
+                const ownShortNames = new Set(members.map((m) => memberShortName(m.name)));
+                for (const mixinName of mixins) {
+                    // Find the mixin typeDef name — try both plain and module-qualified
+                    let mixinTdName;
+                    for (const [tdName] of this.typeDefByName) {
+                        if (classTsName(tdName) === mixinName || tdName === mixinName || tdName.endsWith(":" + mixinName)) {
+                            mixinTdName = tdName;
+                            break;
+                        }
+                    }
+                    if (!mixinTdName)
+                        continue;
+                    const mixinMembers = classMembers.get(mixinTdName) ?? [];
+                    for (const mm of mixinMembers) {
+                        const shortName = memberShortName(mm.name);
+                        // Only include mixin methods not already defined on this class
+                        if (!ownShortNames.has(shortName)) {
+                            members.push(mm);
+                            ownShortNames.add(shortName);
+                        }
+                    }
+                }
+            }
+            this.emitClass(sf, td, members);
+        }
+        // Enums declared in Module.enums[] (google.protobuf.EnumDescriptorProto,
+        // proto3 JSON: `{name, value: [{name, number}]}`). Both encoders emit
+        // enum declarations here (the Dart encoder with module-qualified names
+        // like "main:Color"); dropping them left `Color.red` references dangling
+        // in the compiled output (#120).
+        const emittedTypeNames = new Set(allTypeDefs.map((td) => classTsName(td.name)));
+        for (const mod of userModules) {
+            for (const en of mod.enums ?? []) {
+                const tsName = classTsName(en.name);
+                // A typeDef of the same name already produced a class declaration.
+                if (emittedTypeNames.has(tsName))
+                    continue;
+                emittedTypeNames.add(tsName);
+                const entries = (en.value ?? []).map((v, i) => ({
+                    name: v.name,
+                    index: typeof v.number === "number" ? v.number : i,
+                }));
+                this.emitEnumClass(sf, tsName, entries);
+            }
+        }
+        // Top-level variables (kind == 'top_level_variable') emit as
+        // `const <name> = <body>;` before free functions.
+        for (const fn of freeFunctions.filter((f) => f.metadata?.kind === "top_level_variable")) {
+            const name = sanitize(fn.name);
+            const body = fn.body ? this.captureInto(() => {
+                this.writeln(`return ${this.expr(fn.body)};`);
+            }) : "undefined";
+            sf.addStatements(`${library ? "export " : ""}let ${name} = (() => { ${body} })();`);
+        }
+        // Free top-level functions (exclude top-level variables).
+        for (const fn of freeFunctions.filter((f) => f.metadata?.kind !== "top_level_variable")) {
+            this.emitFreeFunction(sf, fn, undefined, undefined, library);
+        }
+    }
+    emitFreeFunction(sf, fn, forceName, forceAsync, 
+    /** Emit `export function …` (library mode). Default false. */
+    isExported = false) {
         const params = extractParams(fn);
         const name = forceName ?? sanitize(fn.name);
         const needsInputAlias = params.length === 1 && params[0] !== "input";
@@ -1982,6 +2054,7 @@ function __isUnknownFnError(e: any): boolean {
             sf.addFunction({
                 kind: StructureKind.Function,
                 name,
+                isExported,
                 isAsync: false,
                 isGenerator: false,
                 parameters: params.map((p) => ({ name: sanitize(p), type: "any" })),
@@ -1993,6 +2066,7 @@ function __isUnknownFnError(e: any): boolean {
             sf.addFunction({
                 kind: StructureKind.Function,
                 name,
+                isExported,
                 isAsync: isAsync && !isGenerator,
                 isGenerator,
                 parameters: params.map((p) => ({ name: sanitize(p), type: "any" })),
@@ -6662,6 +6736,16 @@ function sanitize(name) {
 export function compile(program, options) {
     return new BallCompiler(program).compile(options);
 }
+/**
+ * Convenience: compile a Program as a LIBRARY — no assumed entry point, no
+ * synthesized invocation, every top-level declaration exported.
+ *
+ * See {@link BallCompiler.compileLibrary} for why this is a separate primitive
+ * rather than a flag on `compile()`.
+ */
+export function compileLibrary(program, options) {
+    return new BallCompiler(program).compileLibrary(options);
+}
 /**
  * Compile a Ball Module (not a Program) to a TypeScript ESM library.
  *