agency-lang 0.7.2 → 0.7.3

package/dist/lib/compiler/buildSession.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The single owner of compile-pipeline caching and orchestration.
+ *
+ * Before this module, "how does compilation caching work" required reading
+ * four places: parseCache.ts (parse memo), commands.ts (three module
+ * globals + compileMany + ensureCompiledClosure), precompile.ts (config
+ * grouping + cross-config assert), and the directory branch of compile().
+ * A BuildSession now owns all of that state and logic; commands.ts keeps
+ * thin delegates for its existing exports.
+ *
+ * Contract (spec "Boundary constraints"): buildCompiledClosure remains a
+ * pure exported function — compileSource (lib/compiler/compile.ts) calls
+ * it directly for in-memory sandbox compiles and must not be affected.
+ *
+ * PR 2 adds `freshness`/the manifest here. Until then every compile is a
+ * full compile (the historical behavior).
+ */
+import { AgencyConfig } from "../config.js";
+import { SymbolTable } from "../symbolTable.js";
+import { type ImportStrategy } from "../importStrategy.js";
+export type CompileOptions = {
+    ts?: boolean;
+    symbolTable?: SymbolTable;
+    importStrategy?: ImportStrategy;
+    /** Suppress the per-file `input → output (in Nms)` progress line. */
+    quiet?: boolean;
+    /** Test-harness only. Honors `import test { … }`. Never set outside the
+     *  test runner / analysis paths — kept off AgencyConfig so agent source
+     *  cannot enable it. */
+    allowTestImports?: boolean;
+};
+/**
+ * A set of entry files sharing one effective config. The canonical config
+ * key is NOT part of this type: it is the session's own integrity
+ * mechanism (the cross-config assert compares it, and PR 2 makes it a
+ * manifest field), so the session derives it — a caller-supplied key that
+ * canonicalized differently would silently weaken the assert.
+ */
+export type CompileGroup = {
+    /** Base-config marker or the local-`agency.json` dir, for error messages. */
+    label: string;
+    config: AgencyConfig;
+    /** Absolute `.agency` entry paths. */
+    files: string[];
+};
+export declare function createBuildSession(): BuildSession;
+export declare class BuildSession {
+    private compiledFiles;
+    private currentClosure;
+    /** Compile a file or directory entry: recursive imports, per-session
+     *  dedupe. Returns the output path (null for directories). */
+    compile(config: AgencyConfig, inputFile: string, outputFile?: string, options?: CompileOptions): string | null;
+    /** Compile a set of entry files under ONE union closure, like the
+     *  directory branch of `compile()`. Closure errors THROW
+     *  (`CompileClosureError`) so programmatic callers can attach context;
+     *  parse/typecheck failures inside per-file compiles keep their exit
+     *  behavior. */
+    compileMany(config: AgencyConfig, files: string[], options?: {
+        quiet?: boolean;
+        allowTestImports?: boolean;
+    }): void;
+    /** Compile config-heterogeneous groups (one union closure each), after
+     *  asserting no module is reachable from groups whose configs differ —
+     *  compiled output is config-dependent and a sibling `.js` is a single
+     *  slot per module, so a shared module would be last-writer-wins.
+     *  Throws `CompileClosureError` naming the module and group labels. */
+    compileGroups(groups: CompileGroup[], options?: {
+        quiet?: boolean;
+        allowTestImports?: boolean;
+    }): void;
+    /** Drop all cached state (watch-mode rebuild boundary). */
+    reset(): void;
+    private setClosure;
+    /**
+     * Internal variant of compileMany keeping the prebuilt-closure handoff
+     * (`options.closure`) used by compileGroups; the public method omits it —
+     * the closure MUST cover every file, a cache-coherence contract no
+     * external caller should have to carry.
+     */
+    private compileManyImpl;
+    /**
+     * Build the import-closure analysis once per compile session — at the
+     * outermost call, before any recursive per-file compile runs. The
+     * recursive children reuse the cached closure to get per-module init
+     * plans without re-parsing.
+     *
+     * "Outermost call" = no `options.symbolTable` (passed by recursive
+     * children). When the outermost call's entry file changes (e.g. the
+     * `agency test` runner iterates several .test.json fixtures in one
+     * process), the cached closure no longer covers the new entry's
+     * imports so we rebuild and drop the stale `compiledFiles` set.
+     * Without that drop, downstream codegen would look up plans for
+     * modules that aren't in the closure and emit an empty init plan.
+     *
+     * Stdlib files compile under their own entry (e.g., when a user runs
+     * `agency compile std/...`) but most user code reaches them via
+     * `import "std::..."`, which the closure walker intentionally skips.
+     * Avoid building a closure rooted at a stdlib file — its imports are
+     * structured differently and we don't need the analysis there.
+     */
+    private ensureCompiledClosure;
+    private compileDirectory;
+    private compileEntry;
+}
+export declare function readFile(inputFile: string): string;
+export declare function findCrossConfigConflicts(groups: {
+    label: string;
+    configKey: string;
+    modules: string[];
+}[]): {
+    module: string;
+    labels: string[];
+}[];

package/dist/lib/compiler/buildSession.js

@@ -0,0 +1,360 @@
+import { generateTypeScript } from "../index.js";
+import { initPlanForModule } from "../backends/typescriptGenerator.js";
+import { resolveImports } from "../preprocessors/importResolver.js";
+import { resolveReExports } from "../preprocessors/resolveReExports.js";
+import { liftCallbackBlocks } from "../preprocessors/liftCallbacks.js";
+import { buildCompilationUnit } from "../compilationUnit.js";
+import { SymbolTable } from "../symbolTable.js";
+import { formatErrors, typeCheck } from "../typeChecker/index.js";
+import { buildCompiledClosure, CompileClosureError, } from "../compiler/compileClosure.js";
+import { transformSync } from "esbuild";
+import * as fs from "fs";
+import * as path from "path";
+import { getStdlibDir, isNonTemplatedStdlib, isPkgImport, isStdlibImport, resolveAgencyImportPath, } from "../importPaths.js";
+import { CompileStrategy } from "../importStrategy.js";
+import { parseAgencyFileCached } from "../parseCache.js";
+import { findRecursively, getImports } from "../cli/util.js";
+export function createBuildSession() {
+    return new BuildSession();
+}
+export class BuildSession {
+    compiledFiles = new Set();
+    // Cached `CompiledClosure` for this session. Built once at the outermost
+    // compile call and reused by every per-file emit.
+    currentClosure = null;
+    /** Compile a file or directory entry: recursive imports, per-session
+     *  dedupe. Returns the output path (null for directories). */
+    compile(config, inputFile, outputFile, options) {
+        return this.compileEntry(config, inputFile, outputFile, options);
+    }
+    /** Compile a set of entry files under ONE union closure, like the
+     *  directory branch of `compile()`. Closure errors THROW
+     *  (`CompileClosureError`) so programmatic callers can attach context;
+     *  parse/typecheck failures inside per-file compiles keep their exit
+     *  behavior. */
+    compileMany(config, files, options) {
+        this.compileManyImpl(config, files, options);
+    }
+    /** Compile config-heterogeneous groups (one union closure each), after
+     *  asserting no module is reachable from groups whose configs differ —
+     *  compiled output is config-dependent and a sibling `.js` is a single
+     *  slot per module, so a shared module would be last-writer-wins.
+     *  Throws `CompileClosureError` naming the module and group labels. */
+    compileGroups(groups, options) {
+        const withClosures = groups.map((group) => ({
+            group,
+            configKey: deriveConfigKey(group.config),
+            closure: buildCompiledClosure(group.files, group.config),
+        }));
+        const conflicts = findCrossConfigConflicts(withClosures.map(({ group, configKey, closure }) => ({
+            label: group.label,
+            configKey,
+            modules: Object.keys(closure.programs),
+        })));
+        if (conflicts.length > 0) {
+            const lines = conflicts.map((c) => `  ${c.module}\n    reachable from: ${c.labels.join(", ")}`);
+            throw new CompileClosureError("Test sources with differing configs share modules. A module's " +
+                "compiled .js is a single slot, so this would be last-writer-wins. " +
+                "Move the shared module or align the configs:\n" +
+                lines.join("\n"));
+        }
+        for (const { group, closure } of withClosures) {
+            this.compileManyImpl(group.config, group.files, {
+                closure,
+                quiet: options?.quiet,
+                allowTestImports: options?.allowTestImports,
+            });
+        }
+    }
+    /** Drop all cached state (watch-mode rebuild boundary). */
+    reset() {
+        this.setClosure(null);
+    }
+    // `compiledFiles` entries are only meaningful under the current closure,
+    // so replacing the closure MUST clear the set. Previously that pairing
+    // was enforced by hand at three separate call sites; this makes it
+    // structural (and protects the additional writers PR 2 introduces).
+    setClosure(closure) {
+        this.currentClosure = closure;
+        this.compiledFiles.clear();
+    }
+    /**
+     * Internal variant of compileMany keeping the prebuilt-closure handoff
+     * (`options.closure`) used by compileGroups; the public method omits it —
+     * the closure MUST cover every file, a cache-coherence contract no
+     * external caller should have to carry.
+     */
+    compileManyImpl(config, files, options) {
+        const absFiles = files.map((f) => path.resolve(f));
+        if (absFiles.length === 0)
+            return;
+        this.setClosure(options?.closure ?? buildCompiledClosure(absFiles, config));
+        for (const file of absFiles) {
+            this.compileEntry(config, file, undefined, {
+                quiet: options?.quiet,
+                allowTestImports: options?.allowTestImports,
+            });
+        }
+    }
+    /**
+     * Build the import-closure analysis once per compile session — at the
+     * outermost call, before any recursive per-file compile runs. The
+     * recursive children reuse the cached closure to get per-module init
+     * plans without re-parsing.
+     *
+     * "Outermost call" = no `options.symbolTable` (passed by recursive
+     * children). When the outermost call's entry file changes (e.g. the
+     * `agency test` runner iterates several .test.json fixtures in one
+     * process), the cached closure no longer covers the new entry's
+     * imports so we rebuild and drop the stale `compiledFiles` set.
+     * Without that drop, downstream codegen would look up plans for
+     * modules that aren't in the closure and emit an empty init plan.
+     *
+     * Stdlib files compile under their own entry (e.g., when a user runs
+     * `agency compile std/...`) but most user code reaches them via
+     * `import "std::..."`, which the closure walker intentionally skips.
+     * Avoid building a closure rooted at a stdlib file — its imports are
+     * structured differently and we don't need the analysis there.
+     */
+    ensureCompiledClosure(absoluteInputFile, config, hasSymbolTable, verbose) {
+        const isOutermostCall = !hasSymbolTable;
+        const isStdlibEntry = absoluteInputFile.startsWith(getStdlibDir() + path.sep);
+        const closureCoversEntry = this.currentClosure?.programs[absoluteInputFile] !== undefined;
+        if (!isOutermostCall || isStdlibEntry || closureCoversEntry)
+            return;
+        this.setClosure(null);
+        try {
+            const ccStartTime = performance.now();
+            this.setClosure(buildCompiledClosure(absoluteInputFile, config));
+            const ccEndTime = performance.now();
+            logTime({ label: "Built compile closure", start: ccStartTime, end: ccEndTime, verbose });
+        }
+        catch (e) {
+            if (e instanceof CompileClosureError) {
+                console.error(e.message);
+                process.exit(1);
+            }
+            throw e;
+        }
+    }
+    // A directory is many entry points — every .agency file under it. To
+    // avoid recompiling shared dependencies once per entry, build ONE
+    // import closure covering all of them up front and reuse it for every
+    // file. Without this, each sibling entry the previous closure didn't
+    // cover would clear the per-session cache (see ensureCompiledClosure)
+    // and recompile shared deps once per entry. Skipped for:
+    //   - recursive child calls (a symbolTable was threaded in) — those
+    //     aren't real top-level directory compiles; and
+    //   - stdlib dirs, which intentionally compile without a closure (the
+    //     same carve-out ensureCompiledClosure makes for stdlib entries).
+    compileDirectory(config, inputFile, options) {
+        const files = [...findRecursively(inputFile)].map((f) => f.path);
+        const absDir = path.resolve(inputFile);
+        const isStdlibDir = absDir === getStdlibDir() || absDir.startsWith(getStdlibDir() + path.sep);
+        if (!options?.symbolTable && !isStdlibDir && files.length > 0) {
+            try {
+                // The fresh union closure supersedes anything cached for a prior
+                // entry (setClosure drops the per-file set so codegen reruns under
+                // the new closure).
+                this.setClosure(buildCompiledClosure(files.map((f) => path.resolve(f)), config));
+            }
+            catch (e) {
+                if (e instanceof CompileClosureError) {
+                    console.error(e.message);
+                    process.exit(1);
+                }
+                throw e;
+            }
+        }
+        for (const file of files) {
+            this.compileEntry(config, file, undefined, options);
+        }
+        return null;
+    }
+    compileEntry(config, inputFile, _outputFile, options) {
+        if (!fs.existsSync(inputFile)) {
+            console.error(`Error: Input file '${inputFile}' not found`);
+            process.exit(1);
+        }
+        const stats = fs.statSync(inputFile);
+        const verbose = config.verbose ?? false;
+        if (stats.isDirectory()) {
+            return this.compileDirectory(config, inputFile, options);
+        }
+        const compileStartTime = performance.now();
+        const absoluteInputFile = path.resolve(inputFile);
+        this.ensureCompiledClosure(absoluteInputFile, config, !!options?.symbolTable, verbose);
+        const ext = options?.ts ? ".ts" : ".js";
+        // Anchor the replacement to the extension so that an absolute path
+        // containing ".agency" as a substring in a parent directory (e.g.
+        // "/Users/me/dev/worksy.agency-init/src/agent.agency") does not get
+        // the first match clobbered. See issue #48.
+        let outputFile = _outputFile || inputFile.replace(/\.agency$/, ext);
+        if (config.outDir && !_outputFile) {
+            const outputDir = path.resolve(config.outDir);
+            if (!fs.existsSync(outputDir)) {
+                fs.mkdirSync(outputDir, { recursive: true });
+            }
+            outputFile = path.join(outputDir, outputFile);
+        }
+        if (this.compiledFiles.has(absoluteInputFile)) {
+            return outputFile;
+        }
+        this.compiledFiles.add(absoluteInputFile);
+        const contents = readFile(inputFile);
+        const applyTemplate = !isNonTemplatedStdlib(absoluteInputFile);
+        const parsedProgram = parseFileOrExit(absoluteInputFile, config, applyTemplate, contents);
+        const symbolTableStartTime = performance.now();
+        const symbolTable = options?.symbolTable ?? SymbolTable.build(absoluteInputFile, config);
+        const symbolTableEndTime = performance.now();
+        logTime({ label: `Built symbol table for ${absoluteInputFile}`, start: symbolTableStartTime, end: symbolTableEndTime, verbose });
+        const compilationUnitStartTime = performance.now();
+        const reExportedProgram = resolveReExports(parsedProgram, symbolTable, absoluteInputFile);
+        const resolvedProgram = resolveImports(reExportedProgram, symbolTable, absoluteInputFile, {
+            allowTestImports: options?.allowTestImports ?? false,
+        });
+        // Lift `callback("onX") { ... }` block bodies to top-level defs.
+        // Must run BEFORE buildCompilationUnit and typecheck so the lifted defs
+        // appear in functionDefinitions and get their bodies typechecked.
+        const liftedProgram = liftCallbackBlocks(resolvedProgram);
+        const info = buildCompilationUnit(liftedProgram, symbolTable, absoluteInputFile, contents);
+        const compilationUnitEndTime = performance.now();
+        logTime({ label: `Built compilation unit for ${absoluteInputFile}`, start: compilationUnitStartTime, end: compilationUnitEndTime, verbose });
+        runTypecheck(liftedProgram, config, info, absoluteInputFile, verbose);
+        const imports = getImports(resolvedProgram);
+        for (const importPath of imports) {
+            if (isStdlibImport(importPath) || isPkgImport(importPath))
+                continue;
+            const absPath = resolveAgencyImportPath(importPath, absoluteInputFile);
+            this.compileEntry(config, absPath, undefined, { ...options, symbolTable });
+        }
+        // Rewrite import paths in the AST using the import strategy
+        const strategy = options?.importStrategy ?? new CompileStrategy({ targetExt: ".js" });
+        const nonAgencyImports = [];
+        liftedProgram.nodes.forEach((node) => {
+            if (node.type !== "importStatement")
+                return;
+            if (isStdlibImport(node.modulePath) || isPkgImport(node.modulePath))
+                return;
+            node.modulePath = strategy.rewriteImport(node.modulePath, absoluteInputFile);
+            if (!node.modulePath.endsWith(".agency")) {
+                nonAgencyImports.push(node.modulePath);
+            }
+        });
+        try {
+            strategy.prepareDependencies(nonAgencyImports, absoluteInputFile);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            process.exit(1);
+        }
+        const moduleId = path.relative(process.cwd(), absoluteInputFile);
+        const absoluteOutputFile = path.resolve(outputFile);
+        // Per-module init plan view — derived from the cached closure if we
+        // built one. Modules not in the closure (e.g., out-of-tree stdlib
+        // compiles) fall through to the legacy path with no plan.
+        const initPlan = this.currentClosure
+            ? initPlanForModule(this.currentClosure, absoluteInputFile)
+            : undefined;
+        const codegenStartTime = performance.now();
+        const generatedCode = generateTypeScript(liftedProgram, config, info, moduleId, absoluteOutputFile, initPlan);
+        const codegenEndTime = performance.now();
+        logTime({ label: `Generated code for ${absoluteInputFile}`, start: codegenStartTime, end: codegenEndTime, verbose });
+        if (options?.ts) {
+            fs.writeFileSync(outputFile, "// @ts-nocheck\n" + generatedCode, "utf-8");
+        }
+        else {
+            const esbuildStartTime = performance.now();
+            const result = transformSync(generatedCode, {
+                loader: "ts",
+                format: "esm",
+                supported: { "top-level-await": true },
+            });
+            fs.writeFileSync(outputFile, result.code, "utf-8");
+            const esbuildEndTime = performance.now();
+            logTime({ label: `Transformed code for ${absoluteInputFile} with esbuild`, start: esbuildStartTime, end: esbuildEndTime, verbose });
+        }
+        const compileEndTime = performance.now();
+        const timeTaken = `${(compileEndTime - compileStartTime).toFixed(2)}ms`;
+        if (!options?.quiet) {
+            console.log(`${inputFile} → ${outputFile} (in ${timeTaken})`);
+        }
+        return outputFile;
+    }
+}
+export function readFile(inputFile) {
+    if (!fs.existsSync(inputFile)) {
+        console.error(`Error: Input file '${inputFile}' not found`);
+        process.exit(1);
+    }
+    return fs.readFileSync(inputFile, "utf-8");
+}
+// Canonical config identity. JSON.stringify is order-stable here because
+// every config passes through AgencyConfigSchema.safeParse (loadConfigSafe
+// returns result.data), and zod rebuilds objects in SCHEMA shape order —
+// guarded by the key-order test in lib/cli/precompile.test.ts.
+function deriveConfigKey(config) {
+    return JSON.stringify(config);
+}
+export function findCrossConfigConflicts(groups) {
+    // Null-prototype: keyed by absolute module paths.
+    const touchedBy = Object.create(null);
+    for (const group of groups) {
+        for (const module of group.modules) {
+            (touchedBy[module] ??= []).push({
+                configKey: group.configKey,
+                label: group.label,
+            });
+        }
+    }
+    const conflicts = [];
+    for (const [module, touches] of Object.entries(touchedBy)) {
+        const distinctKeys = touches
+            .map((t) => t.configKey)
+            .filter((key, i, all) => all.indexOf(key) === i);
+        if (distinctKeys.length > 1) {
+            conflicts.push({ module, labels: touches.map((t) => t.label) });
+        }
+    }
+    return conflicts;
+}
+// Cached-parse counterpart of `parse()`: same exit-on-failure contract the
+// CLI pipeline expects, but reads through the process-wide parse cache.
+function parseFileOrExit(absPath, config, applyTemplate, contents) {
+    const parseResult = parseAgencyFileCached(absPath, config, applyTemplate);
+    if (!parseResult.success) {
+        if (parseResult.message) {
+            console.error(`Failed to parse Agency program: ${parseResult.message}`);
+        }
+        else {
+            console.error("Failed to parse Agency program.", contents.slice(0, 400));
+        }
+        process.exit(1);
+    }
+    return parseResult.result;
+}
+function runTypecheck(liftedProgram, config, info, absoluteInputFile, verbose) {
+    const tc = config.typechecker;
+    if (!tc?.enabled && !tc?.strict)
+        return;
+    const tcStartTime = performance.now();
+    const { errors } = typeCheck(liftedProgram, config, info);
+    const tcEndTime = performance.now();
+    logTime({ label: `Type checked ${absoluteInputFile}`, start: tcStartTime, end: tcEndTime, verbose });
+    if (errors.length === 0)
+        return;
+    if (tc?.strict) {
+        console.error(formatErrors(errors));
+        const hasFatal = errors.some((e) => (e.severity ?? "error") === "error");
+        if (hasFatal)
+            process.exit(1);
+    }
+    else {
+        console.warn(formatErrors(errors, "warning"));
+    }
+}
+function logTime({ label, start, end, verbose }) {
+    if (verbose) {
+        console.log(`${label} in ${(end - start).toFixed(2)}ms`);
+    }
+}

package/dist/lib/compiler/buildSession.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/compiler/buildSession.test.js

@@ -0,0 +1,195 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { createBuildSession, findCrossConfigConflicts } from "./buildSession.js";
+import { CompileClosureError } from "./compileClosure.js";
+import { compile, resetCompilationCache } from "../cli/commands.js";
+const TRIVIAL = 'node main() {\n  return "ok"\n}\n';
+const HELPER = 'export def helper(): string {\n  return "shared"\n}\n';
+const IMPORTS_HELPER = 'import { helper } from "./helper.agency"\n\nnode main() {\n  return helper()\n}\n';
+function writeTempDir(files) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "agency-buildsession-"));
+    for (const [name, contents] of Object.entries(files)) {
+        fs.writeFileSync(path.join(dir, name), contents);
+    }
+    return dir;
+}
+// Back-date a file so any re-emit measurably moves its mtime, independent
+// of filesystem timestamp granularity vs compile duration.
+const BACKDATE = new Date("2020-01-01T00:00:00Z");
+function backdate(file) {
+    fs.utimesSync(file, BACKDATE, BACKDATE);
+    return fs.statSync(file).mtimeMs;
+}
+// Count progress lines ("<input> → <output> (in Nms)") for a source file.
+function emitCount(spy, sourceName) {
+    return spy.mock.calls.filter((args) => typeof args[0] === "string" && args[0].includes(`${sourceName} → `)).length;
+}
+afterEach(() => {
+    vi.restoreAllMocks();
+});
+describe("createBuildSession", () => {
+    test("compiles a single file and returns the output path", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const session = createBuildSession();
+        const out = session.compile({}, path.join(dir, "main.agency"), undefined, { quiet: true });
+        expect(out).toBe(path.join(dir, "main.js"));
+        expect(fs.existsSync(out)).toBe(true);
+    });
+    test("dedupes within a session: second compile of the same entry is a no-op", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const session = createBuildSession();
+        const entry = path.join(dir, "main.agency");
+        session.compile({}, entry, undefined, { quiet: true });
+        const stamped = backdate(path.join(dir, "main.js"));
+        session.compile({}, entry, undefined, { quiet: true });
+        expect(fs.statSync(path.join(dir, "main.js")).mtimeMs).toBe(stamped);
+    });
+    test("sessions are isolated: a fresh session recompiles", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const entry = path.join(dir, "main.agency");
+        createBuildSession().compile({}, entry, undefined, { quiet: true });
+        const stamped = backdate(path.join(dir, "main.js"));
+        createBuildSession().compile({}, entry, undefined, { quiet: true });
+        expect(fs.statSync(path.join(dir, "main.js")).mtimeMs).toBeGreaterThan(stamped);
+    });
+    test("reset() drops the dedupe state", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const entry = path.join(dir, "main.agency");
+        const session = createBuildSession();
+        session.compile({}, entry, undefined, { quiet: true });
+        const stamped = backdate(path.join(dir, "main.js"));
+        session.reset();
+        session.compile({}, entry, undefined, { quiet: true });
+        expect(fs.statSync(path.join(dir, "main.js")).mtimeMs).toBeGreaterThan(stamped);
+    });
+    test("compileMany compiles the shared import exactly once (union closure)", () => {
+        const dir = writeTempDir({
+            "helper.agency": HELPER,
+            "a.agency": IMPORTS_HELPER,
+            "b.agency": IMPORTS_HELPER,
+        });
+        const spy = vi.spyOn(console, "log");
+        createBuildSession().compileMany({}, [
+            path.join(dir, "a.agency"),
+            path.join(dir, "b.agency"),
+        ]);
+        for (const out of ["a.js", "b.js", "helper.js"]) {
+            expect(fs.existsSync(path.join(dir, out))).toBe(true);
+        }
+        // The property under test: helper compiles ONCE. A closure-per-entry
+        // regression compiles it twice and still leaves all files existing.
+        expect(emitCount(spy, "helper.agency")).toBe(1);
+    });
+    test("directory entries compile every member with one union closure", () => {
+        const dir = writeTempDir({
+            "helper.agency": HELPER,
+            "a.agency": IMPORTS_HELPER,
+            "b.agency": IMPORTS_HELPER,
+        });
+        const spy = vi.spyOn(console, "log");
+        const result = createBuildSession().compile({}, dir);
+        expect(result).toBeNull();
+        for (const out of ["a.js", "b.js", "helper.js"]) {
+            expect(fs.existsSync(path.join(dir, out))).toBe(true);
+        }
+        expect(emitCount(spy, "helper.agency")).toBe(1);
+    });
+    test("compileMany throws CompileClosureError for programmatic callers", () => {
+        const dir = writeTempDir({
+            "main.agency": 'import { gone } from "./missing.agency"\n\nnode main() {\n  return gone()\n}\n',
+        });
+        expect(() => createBuildSession().compileMany({}, [path.join(dir, "main.agency")], { quiet: true })).toThrow(CompileClosureError);
+    });
+    test("allowTestImports gates import test compilation", () => {
+        const dir = writeTempDir({
+            "lib.agency": 'def secret(): string {\n  return "s"\n}\n',
+            "main.agency": 'import test { secret } from "./lib.agency"\n\nnode main() {\n  return secret()\n}\n',
+        });
+        const files = [path.join(dir, "main.agency")];
+        expect(() => createBuildSession().compileMany({}, files, { quiet: true })).toThrow(/only allowed under the test harness/);
+        createBuildSession().compileMany({}, files, { quiet: true, allowTestImports: true });
+        expect(fs.existsSync(path.join(dir, "main.js"))).toBe(true);
+    });
+    test("outDir routes output into the configured directory", () => {
+        // The outDir branch joins outDir with the INPUT-derived path, so it is
+        // designed for CWD-relative inputs (`agency compile main.agency` with
+        // an outDir config). Exercise it the way the CLI does: chdir into the
+        // project dir and pass a bare relative path.
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const outDir = path.join(dir, "built");
+        const previousCwd = process.cwd();
+        try {
+            process.chdir(dir);
+            const out = createBuildSession().compile({ outDir }, "main.agency", undefined, {
+                quiet: true,
+            });
+            expect(out).toBe(path.join(outDir, "main.js"));
+            expect(fs.existsSync(out)).toBe(true);
+        }
+        finally {
+            process.chdir(previousCwd);
+        }
+    });
+});
+describe("findCrossConfigConflicts", () => {
+    test("no conflict when groups with the same config share a module", () => {
+        const conflicts = findCrossConfigConflicts([
+            { label: "a", configKey: "{}", modules: ["/shared.agency"] },
+            { label: "b", configKey: "{}", modules: ["/shared.agency"] },
+        ]);
+        expect(conflicts).toEqual([]);
+    });
+    test("conflict when groups with differing configs share a module", () => {
+        const conflicts = findCrossConfigConflicts([
+            { label: "a", configKey: "{}", modules: ["/shared.agency", "/a.agency"] },
+            { label: "b", configKey: '{"verbose":true}', modules: ["/shared.agency"] },
+        ]);
+        expect(conflicts).toHaveLength(1);
+        expect(conflicts[0].module).toBe("/shared.agency");
+        expect(conflicts[0].labels.sort()).toEqual(["a", "b"]);
+    });
+    test("no conflict when differing-config groups touch disjoint modules", () => {
+        const conflicts = findCrossConfigConflicts([
+            { label: "a", configKey: "{}", modules: ["/a.agency"] },
+            { label: "b", configKey: '{"verbose":true}', modules: ["/b.agency"] },
+        ]);
+        expect(conflicts).toEqual([]);
+    });
+});
+describe("compileGroups", () => {
+    test("asserts loudly when differing configs share a module", () => {
+        const dir = writeTempDir({
+            "helper.agency": HELPER,
+            "a.agency": IMPORTS_HELPER,
+            "b.agency": IMPORTS_HELPER,
+        });
+        const groups = [
+            { label: "a", config: {}, files: [path.join(dir, "a.agency")] },
+            { label: "b", config: { verbose: false }, files: [path.join(dir, "b.agency")] },
+        ];
+        expect(() => createBuildSession().compileGroups(groups, { quiet: true })).toThrow(/helper\.agency/);
+    });
+    test("compiles compatible groups", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const groups = [
+            { label: "<base config>", config: {}, files: [path.join(dir, "main.agency")] },
+        ];
+        createBuildSession().compileGroups(groups, { quiet: true });
+        expect(fs.existsSync(path.join(dir, "main.js"))).toBe(true);
+    });
+});
+describe("commands.ts delegates", () => {
+    test("module-level compile + resetCompilationCache re-emits", () => {
+        const dir = writeTempDir({ "main.agency": TRIVIAL });
+        const entry = path.join(dir, "main.agency");
+        compile({}, entry, undefined, { quiet: true });
+        const stamped = backdate(path.join(dir, "main.js"));
+        compile({}, entry, undefined, { quiet: true });
+        expect(fs.statSync(path.join(dir, "main.js")).mtimeMs).toBe(stamped); // deduped
+        resetCompilationCache();
+        compile({}, entry, undefined, { quiet: true });
+        expect(fs.statSync(path.join(dir, "main.js")).mtimeMs).toBeGreaterThan(stamped);
+    });
+});

package/dist/lib/stdlib/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.2";
+export declare const VERSION = "0.7.3";