agency-lang 0.0.86 → 0.0.87

package/dist/lib/backends/agencyGenerator.d.ts

@@ -1,5 +1,5 @@
 import { SpecialVar } from "../types/specialVar.js";
-import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, DebuggerStatement, Literal, NewLine, Scope, TypeAlias, TypeHint, TypeHintMap, VariableType } from "../types.js";
+import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, DebuggerStatement, Literal, NewLine, Scope, TypeAlias, VariableType } from "../types.js";
 import { AccessChainElement, ValueAccess } from "../types/access.js";
 import { AgencyArray, AgencyObject } from "../types/dataStructures.js";
 import { FunctionCall, FunctionDefinition } from "../types/function.js";
@@ -18,7 +18,6 @@ import { BinOpArgument, BinOpExpression, Operator } from "../types/binop.js";
 import { Keyword } from "../types/keyword.js";
 import { HandleBlock } from "../types/handleBlock.js";
 export declare class AgencyGenerator {
-    protected typeHints: TypeHintMap;
     protected graphNodes: GraphNodeDefinition[];
     protected generatedStatements: string[];
     protected generatedTypeAliases: string[];
@@ -48,7 +47,7 @@ export declare class AgencyGenerator {
     protected postprocess(): string;
     protected collectFunctionSignature(node: FunctionDefinition): void;
     protected processGraphNodeName(node: GraphNodeDefinition): void;
-    protected processNode(node: AgencyNode): string;
+    processNode(node: AgencyNode): string;
     protected needsParensLeft(child: BinOpArgument, parentOp: Operator): boolean;
     protected needsParensRight(child: BinOpArgument, parentOp: Operator): boolean;
     protected startScope(scope: Scope): void;
@@ -63,7 +62,6 @@ export declare class AgencyGenerator {
     private stringifyProp;
     protected aliasedTypeToString(aliasedType: VariableType): string;
     protected processTypeAlias(node: TypeAlias): string;
-    protected processTypeHint(node: TypeHint): string;
     protected processAssignment(node: Assignment): string;
     protected generateLiteral(literal: Literal): string;
     private generateStringLiteral;

package/dist/lib/backends/agencyGenerator.js

@@ -3,7 +3,6 @@ import { mergeDeep } from "../utils.js";
 import { PRECEDENCE, } from "../types/binop.js";
 import { expressionToString } from "../utils/node.js";
 export class AgencyGenerator {
-    typeHints = {};
     graphNodes = [];
     generatedStatements = [];
     generatedTypeAliases = [];
@@ -35,19 +34,13 @@ export class AgencyGenerator {
                 this.processTypeAlias(node);
             }
         }
-        // Pass 2: Collect all type hints
-        for (const node of program.nodes) {
-            if (node.type === "typeHint") {
-                this.processTypeHint(node);
-            }
-        }
-        // Pass 3: Collect all node names
+        // Pass 2: Collect all node names
         for (const node of program.nodes) {
             if (node.type === "graphNode") {
                 this.processGraphNodeName(node);
             }
         }
-        // Pass 4: Collect all node and tool imports
+        // Pass 3: Collect all node and tool imports
         for (const node of program.nodes) {
             if (node.type === "importNodeStatement") {
                 this.importedNodes.push(node);
@@ -56,7 +49,7 @@ export class AgencyGenerator {
                 this.importedTools.push(node);
             }
         }
-        // Pass 5: Generate code for tools
+        // Pass 4: Generate code for tools
         for (const node of program.nodes) {
             if (node.type === "function") {
                 this.generatedStatements.push(this.processTool(node));
@@ -71,7 +64,7 @@ export class AgencyGenerator {
         const NO_SPACE_TYPES = new Set([
             "comment", "multiLineComment"
         ]);
-        // Pass 7: Process all nodes and generate code
+        // Pass 5: Process all nodes and generate code
         const stmtPairs = [];
         for (const node of program.nodes) {
             const result = this.processNode(node);
@@ -128,8 +121,6 @@ export class AgencyGenerator {
     processGraphNodeName(node) { }
     processNode(node) {
         switch (node.type) {
-            case "typeHint":
-                return this.processTypeHint(node);
             case "typeAlias":
                 return this.processTypeAlias(node);
             case "assignment":
@@ -151,6 +142,7 @@ export class AgencyGenerator {
             case "string":
             case "variableName":
             case "boolean":
+            case "null":
                 return this.generateLiteral(node);
             case "returnStatement":
                 return this.processReturnStatement(node);
@@ -286,11 +278,6 @@ export class AgencyGenerator {
         const aliasedTypeStr = this.aliasedTypeToString(node.aliasedType);
         return this.indentStr(`type ${node.aliasName} = ${aliasedTypeStr}`);
     }
-    processTypeHint(node) {
-        this.typeHints[node.variableName] = node.variableType;
-        const typeStr = variableTypeToString(node.variableType, this.typeAliases);
-        return this.indentStr(`${node.variableName} :: ${typeStr}`);
-    }
     // Assignment and literals
     processAssignment(node) {
         const chainStr = node.accessChain
@@ -299,9 +286,10 @@ export class AgencyGenerator {
         const varName = node.typeHint
             ? `${node.variableName}${chainStr}: ${variableTypeToString(node.typeHint, this.typeAliases)}`
             : `${node.variableName}${chainStr}`;
-        const prefix = node.shared ? "shared " : "";
+        const sharedPrefix = node.shared ? "shared " : "";
+        const declPrefix = node.declKind ? `${node.declKind} ` : "";
         let valueCode = this.processNode(node.value).trim();
-        return this.indentStr(`${prefix}${varName} = ${valueCode}`);
+        return this.indentStr(`${sharedPrefix}${declPrefix}${varName} = ${valueCode}`);
     }
     generateLiteral(literal) {
         switch (literal.type) {
@@ -315,6 +303,8 @@ export class AgencyGenerator {
                 return this.generateMultiLineStringLiteral(literal);
             case "boolean":
                 return literal.value ? "true" : "false";
+            case "null":
+                return "null";
             default:
                 return "";
         }
@@ -353,12 +343,16 @@ export class AgencyGenerator {
         const { functionName, body, parameters } = node;
         const params = parameters
             .map((p) => {
+            const prefix = p.variadic ? "..." : "";
+            const defaultSuffix = p.defaultValue
+                ? ` = ${this.processNode(p.defaultValue).trim()}`
+                : "";
             if (p.typeHint) {
                 const typeStr = variableTypeToString(p.typeHint, this.typeAliases);
-                return `${p.name}: ${typeStr}`;
+                return `${prefix}${p.name}: ${typeStr}${defaultSuffix}`;
             }
             else {
-                return p.name;
+                return `${prefix}${p.name}${defaultSuffix}`;
             }
         })
             .join(", ");
@@ -366,14 +360,8 @@ export class AgencyGenerator {
             ? ": " + variableTypeToString(node.returnType, this.typeAliases)
             : "";
         let safePrefix = node.safe ? "safe " : "";
-        let asyncPrefix = "";
-        if (node.async === true) {
-            asyncPrefix = "async ";
-        }
-        else if (node.async === false) {
-            asyncPrefix = "sync ";
-        }
-        let result = this.indentStr(`${safePrefix}${asyncPrefix}def ${functionName}(${params})${returnTypeStr} {\n`);
+        const exportPrefix = node.exported ? "export " : "";
+        let result = this.indentStr(`${exportPrefix}${safePrefix}def ${functionName}(${params})${returnTypeStr} {\n`);
         this.increaseIndent();
         if (node.docString) {
             const docLines = [`"""`, ...node.docString.value.split("\n"), `"""`];
@@ -396,6 +384,12 @@ export class AgencyGenerator {
     }
     generateFunctionCallExpression(node, context) {
         const args = node.arguments.map((arg) => {
+            if (arg.type === "namedArgument") {
+                return `${arg.name}: ${this.processNode(arg.value).trim()}`;
+            }
+            if (arg.type === "splat") {
+                return `...${this.processNode(arg.value).trim()}`;
+            }
             return this.processNode(arg).trim();
         });
         let asyncPrefix = "";
@@ -405,7 +399,26 @@ export class AgencyGenerator {
         else if (node.async === false) {
             asyncPrefix = "await ";
         }
-        return `${asyncPrefix}${node.functionName}(${args.join(", ")})`;
+        let result = `${asyncPrefix}${node.functionName}(${args.join(", ")})`;
+        if (node.block) {
+            const block = node.block;
+            let asClause = "as ";
+            if (block.params.length === 1) {
+                asClause = `as ${block.params[0].name} `;
+            }
+            else if (block.params.length > 1) {
+                asClause = `as (${block.params.map((p) => p.name).join(", ")}) `;
+            }
+            this.increaseIndent();
+            const bodyLines = [];
+            for (const stmt of block.body) {
+                bodyLines.push(this.processNode(stmt));
+            }
+            this.decreaseIndent();
+            const bodyStr = bodyLines.filter((s) => s !== "").join("\n").trimEnd() + "\n";
+            result += ` ${asClause}{\n${bodyStr}${this.indentStr("}")}`;
+        }
+        return result;
     }
     // Data structures
     processAgencyArray(node) {

package/dist/lib/backends/index.d.ts

@@ -1 +1,2 @@
 export * from "./typescriptGenerator.js";
+export * from "./sourceMap.js";

package/dist/lib/backends/index.js

@@ -1 +1,2 @@
 export * from "./typescriptGenerator.js";
+export * from "./sourceMap.js";

package/dist/lib/backends/sourceMap.d.ts

@@ -0,0 +1,13 @@
+import type { SourceLocation } from "../types/base.js";
+export type SourceMapLocation = {
+    line: number;
+    col: number;
+};
+export type SourceMap = Record<string, Record<string, SourceMapLocation>>;
+export declare class SourceMapBuilder {
+    private currentKey;
+    private map;
+    enterScope(moduleId: string, scopeName: string): void;
+    record(subStepPath: number[], loc: SourceLocation | undefined): void;
+    build(): SourceMap;
+}

package/dist/lib/backends/sourceMap.js

@@ -0,0 +1,18 @@
+export class SourceMapBuilder {
+    currentKey = "";
+    map = {};
+    enterScope(moduleId, scopeName) {
+        this.currentKey = `${moduleId}:${scopeName}`;
+        if (!this.map[this.currentKey]) {
+            this.map[this.currentKey] = {};
+        }
+    }
+    record(subStepPath, loc) {
+        if (!loc || !this.currentKey)
+            return;
+        this.map[this.currentKey][subStepPath.join(".")] = { line: loc.line, col: loc.col };
+    }
+    build() {
+        return structuredClone(this.map);
+    }
+}

package/dist/lib/backends/sourceMap.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect } from "vitest";
+import { SourceMapBuilder } from "./sourceMap.js";
+describe("SourceMapBuilder", () => {
+    it("records entries and builds correct structure", () => {
+        const builder = new SourceMapBuilder();
+        builder.enterScope("foo.agency", "main");
+        builder.record([0], { line: 1, col: 2, start: 0, end: 10 });
+        builder.record([1], { line: 3, col: 2, start: 20, end: 30 });
+        const result = builder.build();
+        expect(result).toEqual({
+            "foo.agency:main": {
+                "0": { line: 1, col: 2 },
+                "1": { line: 3, col: 2 },
+            },
+        });
+    });
+    it("handles multiple scopes", () => {
+        const builder = new SourceMapBuilder();
+        builder.enterScope("foo.agency", "main");
+        builder.record([0], { line: 1, col: 2, start: 0, end: 10 });
+        builder.enterScope("foo.agency", "greet");
+        builder.record([0], { line: 5, col: 2, start: 50, end: 60 });
+        const result = builder.build();
+        expect(result).toHaveProperty("foo.agency:main");
+        expect(result).toHaveProperty("foo.agency:greet");
+    });
+    it("silently skips undefined loc", () => {
+        const builder = new SourceMapBuilder();
+        builder.enterScope("foo.agency", "main");
+        builder.record([0], undefined);
+        builder.record([1], { line: 3, col: 2, start: 20, end: 30 });
+        const result = builder.build();
+        expect(result["foo.agency:main"]).toEqual({
+            "1": { line: 3, col: 2 },
+        });
+    });
+    it("formats substep paths with dot separator", () => {
+        const builder = new SourceMapBuilder();
+        builder.enterScope("foo.agency", "main");
+        builder.record([2, 0, 1], { line: 10, col: 4, start: 100, end: 120 });
+        const result = builder.build();
+        expect(result["foo.agency:main"]).toHaveProperty("2.0.1");
+    });
+    it("returns empty object when nothing recorded", () => {
+        const builder = new SourceMapBuilder();
+        expect(builder.build()).toEqual({});
+    });
+    it("build returns a copy, not the internal reference", () => {
+        const builder = new SourceMapBuilder();
+        builder.enterScope("foo.agency", "main");
+        builder.record([0], { line: 1, col: 2, start: 0, end: 10 });
+        const result1 = builder.build();
+        result1["foo.agency:main"]["0"].line = 999;
+        const result2 = builder.build();
+        expect(result2["foo.agency:main"]["0"].line).toBe(1);
+    });
+});

package/dist/lib/backends/typescriptBuilder.d.ts

@@ -15,6 +15,7 @@ export declare class TypeScriptBuilder {
     private loopVars;
     private insideMessageThread;
     private insideHandlerBody;
+    private _blockCounter;
     /** Stack of loop subKeys for generating break/continue cleanup code.
      * Pushed when entering a stepped loop, popped when leaving. */
     private _loopContextStack;
@@ -24,6 +25,7 @@ export declare class TypeScriptBuilder {
      * has been broken into substeps. Used to generate unique variable names
      * like __substep_3_1 for nested blocks. */
     private _subStepPath;
+    private _sourceMapBuilder;
     private programInfo;
     private moduleId;
     /**
@@ -47,9 +49,11 @@ export declare class TypeScriptBuilder {
      */
     private scopedAssign;
     private currentScopeKey;
-    private getTypeHint;
+    /** Returns the name of the current scope (function, node, or block name, or empty string for global). */
+    private currentScopeName;
+    /** Returns the template opts for checkpoint creation (moduleId, scopeName, stepPath as JSON-quoted strings). */
+    private checkpointOpts;
     private getVisibleTypeAliases;
-    private getVisibleTypeHints;
     private forkBranchSetup;
     private isImportedTool;
     private static RUNTIME_STATEFUL_FUNCTIONS;
@@ -62,10 +66,19 @@ export declare class TypeScriptBuilder {
     private needsParensLeft;
     private needsParensRight;
     build(program: AgencyProgram): TsNode;
+    /** Named args are cosmetic/positional — validate name matches the param at that index. */
+    private validateNamedArgs;
+    /** Process a function call argument, unwrapping NamedArgument and SplatExpression. */
+    private processCallArg;
+    /**
+     * Adjust call-site arguments to match the function's parameter list:
+     * 1. Pad omitted optional args (those with defaults) with null
+     * 2. Wrap extra args into an array for variadic params
+     */
+    private adjustCallArgs;
     private processNode;
     private processKeyword;
     private processTypeAlias;
-    private processTypeHint;
     private processComment;
     private processAgencyObject;
     private processAgencyArray;
@@ -90,6 +103,7 @@ export declare class TypeScriptBuilder {
     private generateToolRegistry;
     private processFunctionDefinition;
     private processStatement;
+    private buildInterruptReturn;
     private processFunctionCallAsStatement;
     private processFunctionCall;
     private generateFunctionCallExpression;
@@ -107,11 +121,14 @@ export declare class TypeScriptBuilder {
     private processLlmCall;
     private processSentinel;
     private processDebuggerStatement;
-    private buildPromptString;
     private processSpecialVar;
     private processMessageThread;
     private processBlockPlain;
     private processHandleBlockWithSteps;
+    /** In debugger mode, insert debuggerStatement nodes before each
+     *  step-triggering statement so that debugStep() is called at every
+     *  substep boundary, not just top-level steps. */
+    private insertDebugSteps;
     private processBodyAsParts;
     private generateBuiltins;
     private generateImports;

package/dist/lib/backends/typescriptBuilder.integration.test.js

@@ -58,7 +58,7 @@ function normalizeWhitespace(code) {
         .concat("\n"));
 }
 export function generateWithBuilder(agencySource, moduleId = "test.agency") {
-    const parseResult = parseAgency(agencySource);
+    const parseResult = parseAgency(agencySource, {}, false);
     if (!parseResult.success) {
         throw new Error(`Failed to parse: ${parseResult.message}`);
     }
@@ -93,3 +93,29 @@ describe("TypeScript Builder Integration Tests", () => {
         });
     });
 });
+describe("Named argument validation", () => {
+    it("should throw on mismatched named argument", () => {
+        expect(() => generateWithBuilder(`
+def greet(name: string, greeting: string = "Hello") {
+  print(name)
+}
+greet(greeting: "Hi")
+`)).toThrow("Named argument 'greeting' does not match parameter 'name' at position 1");
+    });
+    it("should throw on named argument beyond parameter list", () => {
+        expect(() => generateWithBuilder(`
+def foo(a: string) {
+  print(a)
+}
+foo(a: "hi", extra: "oops")
+`)).toThrow("Named argument 'extra' at position 2 is beyond the parameter list");
+    });
+    it("should accept correct named arguments", () => {
+        expect(() => generateWithBuilder(`
+def greet(name: string, greeting: string = "Hello") {
+  print(name)
+}
+greet(name: "world", greeting: "Hi")
+`)).not.toThrow();
+    });
+});