agency-lang 0.0.92 → 0.0.93

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

@@ -82,6 +82,9 @@ export declare class AgencyGenerator {
     protected processDebuggerStatement(node: DebuggerStatement): string;
     protected processComment(node: AgencyComment): string;
     protected processMultiLineComment(node: AgencyMultiLineComment): string;
+    protected formatDocComment(node: {
+        docComment?: AgencyMultiLineComment;
+    }): string;
     protected processImportStatement(node: ImportStatement): string;
     protected processImportNameType(node: ImportNameType): string;
     protected processImportNodeStatement(node: ImportNodeStatement): string;

package/dist/lib/backends/agencyGenerator.js

@@ -196,8 +196,10 @@ export class AgencyGenerator {
                 return this.processClassDefinition(node);
             case "newExpression":
                 return this.processNewExpression(node);
+            case "schemaExpression":
+                return `schema(${variableTypeToString(node.typeArg, this.typeAliases)})`;
             case "regex":
-                return `/${node.pattern}/${node.flags}`;
+                return `re/${node.pattern}/${node.flags}`;
             default:
                 throw new Error(`Unhandled Agency node type: ${node.type}`);
         }
@@ -205,6 +207,9 @@ export class AgencyGenerator {
     needsParensLeft(child, parentOp) {
         if (child.type !== "binOpExpression")
             return false;
+        // For right-associative ops like **, (2 ** 3) ** 4 needs parens on the left
+        if (parentOp === "**")
+            return PRECEDENCE[child.operator] <= PRECEDENCE[parentOp];
         return PRECEDENCE[child.operator] < PRECEDENCE[parentOp];
     }
     needsParensRight(child, parentOp) {
@@ -287,7 +292,8 @@ export class AgencyGenerator {
         this.typeAliases[node.aliasName] = node.aliasedType;
         const aliasedTypeStr = this.aliasedTypeToString(node.aliasedType);
         const exportPrefix = node.exported ? "export " : "";
-        return this.indentStr(`${exportPrefix}type ${node.aliasName} = ${aliasedTypeStr}`);
+        return (this.formatDocComment(node) +
+            this.indentStr(`${exportPrefix}type ${node.aliasName} = ${aliasedTypeStr}`));
     }
     // Assignment and literals
     processAssignment(node) {
@@ -295,8 +301,9 @@ export class AgencyGenerator {
         const chainStr = node.accessChain
             ?.map((ce) => this.processAccessChainElement(ce))
             .join("") ?? "";
+        const bangSuffix = node.validated ? "!" : "";
         const varName = node.typeHint
-            ? `${node.variableName}${chainStr}: ${variableTypeToString(node.typeHint, this.typeAliases)}`
+            ? `${node.variableName}${chainStr}: ${variableTypeToString(node.typeHint, this.typeAliases)}${bangSuffix}`
             : `${node.variableName}${chainStr}`;
         const sharedPrefix = node.shared ? "shared " : "";
         const declPrefix = node.declKind ? `${node.declKind} ` : "";
@@ -365,19 +372,22 @@ export class AgencyGenerator {
                 : "";
             if (p.typeHint) {
                 const typeStr = variableTypeToString(p.typeHint, this.typeAliases);
-                return `${prefix}${p.name}: ${typeStr}${defaultSuffix}`;
+                const bang = p.validated ? "!" : "";
+                return `${prefix}${p.name}: ${typeStr}${bang}${defaultSuffix}`;
             }
             else {
                 return `${prefix}${p.name}${defaultSuffix}`;
             }
         })
             .join(", ");
+        const returnTypeBang = node.returnTypeValidated ? "!" : "";
         const returnTypeStr = node.returnType
-            ? ": " + variableTypeToString(node.returnType, this.typeAliases)
+            ? ": " + variableTypeToString(node.returnType, this.typeAliases) + returnTypeBang
             : "";
         let safePrefix = node.safe ? "safe " : "";
         const exportPrefix = node.exported ? "export " : "";
-        let result = this.indentStr(`${exportPrefix}${safePrefix}def ${functionName}(${params})${returnTypeStr} {\n`);
+        const keyword = node.callback ? "callback" : "def";
+        let result = this.indentStr(`${exportPrefix}${safePrefix}${keyword} ${functionName}(${params})${returnTypeStr} {\n`);
         this.increaseIndent();
         if (node.docString) {
             const docLines = [`"""`, ...node.docString.value.split("\n"), `"""`];
@@ -395,7 +405,7 @@ export class AgencyGenerator {
         result += bodyCode;
         this.decreaseIndent();
         result += this.indentStr(`}`);
-        return tags + result;
+        return this.formatDocComment(node) + tags + result;
     }
     processFunctionCall(node) {
         const tags = this.formatAttachedTags(node);
@@ -588,6 +598,8 @@ export class AgencyGenerator {
         return lines.join("");
     }
     processReturnStatement(node) {
+        if (!node.value)
+            return this.indentStr("return");
         const valueCode = this.processNode(node.value).trim();
         return this.indentStr(`return ${valueCode}`);
     }
@@ -599,8 +611,16 @@ export class AgencyGenerator {
         return this.indentStr(`//${node.content}`);
     }
     processMultiLineComment(node) {
+        if (node.isDoc) {
+            return this.indentStr(`/**${node.content}*/`);
+        }
         return this.indentStr(`/*${node.content}*/`);
     }
+    formatDocComment(node) {
+        if (!node.docComment)
+            return "";
+        return this.processMultiLineComment(node.docComment) + "\n";
+    }
     processImportStatement(node) {
         const importedNames = node.importedNames.map((name) => this.processImportNameType(name));
         const modulePath = node.modulePath.startsWith("std::")
@@ -649,16 +669,26 @@ export class AgencyGenerator {
         const tags = this.formatAttachedTags(node);
         const { nodeName, body, parameters } = node;
         const params = parameters
-            .map((p) => p.typeHint
-            ? `${p.name}: ${variableTypeToString(p.typeHint, this.typeAliases)}`
-            : p.name)
+            .map((p) => {
+            if (p.typeHint) {
+                const bang = p.validated ? "!" : "";
+                return `${p.name}: ${variableTypeToString(p.typeHint, this.typeAliases)}${bang}`;
+            }
+            return p.name;
+        })
             .join(", ");
+        const returnTypeBang = node.returnTypeValidated ? "!" : "";
         const returnTypeStr = node.returnType
-            ? ": " + variableTypeToString(node.returnType, this.typeAliases)
+            ? ": " + variableTypeToString(node.returnType, this.typeAliases) + returnTypeBang
             : "";
         const visibilityStr = this.visibilityToString(node.visibility);
         let result = this.indentStr(`${visibilityStr}node ${nodeName}(${params})${returnTypeStr} {\n`);
         this.increaseIndent();
+        if (node.docString) {
+            const docLines = [`"""`, ...node.docString.value.split("\n"), `"""`];
+            const docStr = docLines.map((line) => this.indentStr(line)).join("\n");
+            result += `${docStr}\n`;
+        }
         const lines = [];
         for (const stmt of body) {
             lines.push(this.processNode(stmt));
@@ -670,7 +700,7 @@ export class AgencyGenerator {
         result += bodyCode;
         this.decreaseIndent();
         result += this.indentStr(`}`);
-        return tags + result;
+        return this.formatDocComment(node) + tags + result;
     }
     processClassDefinition(node) {
         const extendsStr = node.parentClass ? ` extends ${node.parentClass}` : "";
@@ -683,9 +713,13 @@ export class AgencyGenerator {
         // Methods (constructor is auto-generated, not formatted)
         for (const method of node.methods) {
             const params = method.parameters
-                .map((p) => p.typeHint
-                ? `${p.name}: ${variableTypeToString(p.typeHint, this.typeAliases)}`
-                : p.name)
+                .map((p) => {
+                if (p.typeHint) {
+                    const bang = p.validated ? "!" : "";
+                    return `${p.name}: ${variableTypeToString(p.typeHint, this.typeAliases)}${bang}`;
+                }
+                return p.name;
+            })
                 .join(", ");
             const returnTypeStr = `: ${variableTypeToString(method.returnType, this.typeAliases)}`;
             result +=
@@ -747,8 +781,9 @@ export class AgencyGenerator {
             .trimEnd() + "\n";
         let handlerStr;
         if (node.handler.kind === "inline") {
+            const handlerBang = node.handler.param.validated ? "!" : "";
             const paramStr = node.handler.param.typeHint
-                ? `${node.handler.param.name}: ${variableTypeToString(node.handler.param.typeHint, this.typeAliases)}`
+                ? `${node.handler.param.name}: ${variableTypeToString(node.handler.param.typeHint, this.typeAliases)}${handlerBang}`
                 : node.handler.param.name;
             this.increaseIndent();
             const handlerBodyCodes = [];
@@ -771,26 +806,26 @@ export class AgencyGenerator {
         return this.indentStr(`skill "${node.filepath}"`);
     }
     processBinOpExpression(node, assigned = false) {
-        // Collect a chain of the same operator (e.g. a |> b |> c)
         const op = node.operator;
-        const parts = [];
-        let current = node;
-        while (current.type === "binOpExpression" && current.operator === op) {
-            parts.push(this.processNode(current.right).trim());
-            current = current.left;
-        }
-        parts.push(this.processNode(current).trim());
-        parts.reverse();
-        const oneLine = parts.join(` ${op} `);
-        const multiLine = oneLine.length <= 60
-            ? oneLine
-            : parts[0] +
-                "\n" +
-                parts
-                    .slice(1)
-                    .map((p) => this.indentStr(`${op} ${p}`))
-                    .join("\n");
-        return assigned ? multiLine : this.indentStr(multiLine);
+        // Unary prefix operators: !x, typeof x, void x
+        if (op === "!" || op === "typeof" || op === "void") {
+            const operand = this.processNode(node.right).trim();
+            const sep = op === "!" ? "" : " ";
+            const result = `${op}${sep}${operand}`;
+            return assigned ? result : this.indentStr(result);
+        }
+        // Postfix operators: x++, x--
+        if (op === "++" || op === "--") {
+            const operand = this.processNode(node.left).trim();
+            const result = `${operand}${op}`;
+            return assigned ? result : this.indentStr(result);
+        }
+        const leftStr = this.processNode(node.left).trim();
+        const rightStr = this.processNode(node.right).trim();
+        const left = this.needsParensLeft(node.left, op) ? `(${leftStr})` : leftStr;
+        const right = this.needsParensRight(node.right, op) ? `(${rightStr})` : rightStr;
+        const result = `${left} ${op} ${right}`;
+        return assigned ? result : this.indentStr(result);
     }
     processAccessChainElement(node) {
         const dot = node.optional ? "?." : ".";
@@ -801,6 +836,12 @@ export class AgencyGenerator {
                 const inner = this.processNode(node.index).trim();
                 return node.optional ? `?.[${inner}]` : `[${inner}]`;
             }
+            case "slice": {
+                const start = node.start ? this.processNode(node.start).trim() : "";
+                const end = node.end ? this.processNode(node.end).trim() : "";
+                const inner = `${start}:${end}`;
+                return node.optional ? `?.[${inner}]` : `[${inner}]`;
+            }
             case "methodCall":
                 return `${dot}${this.generateFunctionCallExpression(node.functionCall, "valueAccess")}`;
             default:

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

@@ -239,4 +239,134 @@ describe("AgencyGenerator - Class Definitions", () => {
         const output = formatAgency(input);
         expect(output).toContain("new Counter(0)");
     });
+    it("should format callback declarations with the callback keyword", () => {
+        const input = `callback onLLMCallEnd(data) {
+  log(data)
+}`;
+        const output = formatAgency(input);
+        expect(output).toContain("callback onLLMCallEnd(data)");
+        expect(output).not.toContain("def onLLMCallEnd");
+    });
+});
+describe("AgencyGenerator - Doc Comments", () => {
+    function formatAgency(input) {
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(true);
+        if (!parseResult.success)
+            return "";
+        const generator = new AgencyGenerator();
+        return generator.generate(parseResult.result).output.trim();
+    }
+    it("should preserve /** syntax for doc comments", () => {
+        const input = `/** This is a doc comment */\ndef foo() {\n  print("hi")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("/** This is a doc comment */");
+    });
+    it("should preserve /* syntax for regular multi-line comments", () => {
+        const input = `/* This is a regular comment */\ndef foo() {\n  print("hi")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("/* This is a regular comment */");
+        expect(output).not.toContain("/**");
+    });
+    it("should preserve multi-line doc comments", () => {
+        const input = `/**\nThis is a multi-line\ndoc comment\n*/\ndef foo() {\n  print("hi")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("/**");
+        expect(output).toContain("This is a multi-line");
+    });
+    it("should round-trip node docstrings", () => {
+        const input = `node main() {\n  """Main entry point."""\n  print("hello")\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain('"""');
+        expect(output).toContain("Main entry point.");
+    });
+});
+describe("AgencyGenerator - bang (!) validated type annotations", () => {
+    function formatAgency(input) {
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(true);
+        if (!parseResult.success)
+            return "";
+        const generator = new AgencyGenerator();
+        return generator.generate(parseResult.result).output.trim();
+    }
+    it("should preserve ! on assignment type annotations", () => {
+        const input = `node main() {\n  const x: number! = 42\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("const x: number! = 42");
+    });
+    it("should preserve ! on function parameter types", () => {
+        const input = `def process(data: number!) {\n  print(data)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("data: number!");
+    });
+    it("should preserve ! on function return types", () => {
+        const input = `def process(x: number): string! {\n  return x\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("): string!");
+    });
+    it("should preserve ! on node return types", () => {
+        const input = `node main(): number! {\n  return 42\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("(): number!");
+    });
+    it("should not add ! when not present", () => {
+        const input = `node main() {\n  const x: number = 42\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("const x: number = 42");
+        expect(output).not.toContain("number!");
+    });
+});
+describe("AgencyGenerator - Result type formatting", () => {
+    function formatAgency(input) {
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(true);
+        if (!parseResult.success)
+            return "";
+        const generator = new AgencyGenerator();
+        return generator.generate(parseResult.result).output.trim();
+    }
+    it("should format Result<Foo> with single type param", () => {
+        const input = `def check(): Result<number> {\n  return success(42)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("Result<number>");
+        expect(output).not.toContain("Result<number,");
+    });
+    it("should format bare Result without type params", () => {
+        const input = `def check(): Result {\n  return success(42)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain(": Result");
+        expect(output).not.toContain("Result<");
+    });
+    it("should format Result<Foo, Bar> with non-default failure type", () => {
+        const input = `def check(): Result<number, number> {\n  return success(42)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("Result<number, number>");
+    });
+    it("should normalize Result<Foo, string> to Result<Foo>", () => {
+        const input = `def check(): Result<number, string> {\n  return success(42)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("Result<number>");
+        expect(output).not.toContain("Result<number, string>");
+    });
+});
+describe("AgencyGenerator - schema(Type) expressions", () => {
+    function formatAgency(input) {
+        const parseResult = parseAgency(input, {}, false);
+        expect(parseResult.success).toBe(true);
+        if (!parseResult.success)
+            return "";
+        const generator = new AgencyGenerator();
+        return generator.generate(parseResult.result).output.trim();
+    }
+    it("should format schema(number)", () => {
+        const input = `node main() {\n  const s = schema(number)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("schema(number)");
+    });
+    it("should format schema(Result<number>)", () => {
+        const input = `node main() {\n  const s = schema(Result<number>)\n}`;
+        const output = formatAgency(input);
+        expect(output).toContain("schema(Result<number>)");
+    });
 });

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

@@ -24,7 +24,7 @@ export declare class TypeScriptBuilder {
     /** Tracks the current substep nesting path. Empty when at the top level
      * of a stepped body. Non-empty when inside a block (if/else, etc.) that
      * has been broken into substeps. Used to generate unique variable names
-     * like __substep_3_1 for nested blocks. */
+     * like __substep_3.1 for nested blocks. */
     private _subStepPath;
     private _sourceMapBuilder;
     private programInfo;
@@ -49,6 +49,11 @@ export declare class TypeScriptBuilder {
      * emits a normal `lhs = rhs` assignment.
      */
     private scopedAssign;
+    /**
+     * arr[1:3] = [10, 20] → arr.splice(start, end - start, ...value)
+     * arr[2:] = [10]      → arr.splice(start, arr.length - start, ...value)
+     */
+    private buildSliceAssignment;
     private currentScopeKey;
     /** Returns the name of the current scope (function, node, or block name, or empty string for global). */
     private currentScopeName;
@@ -63,6 +68,7 @@ export declare class TypeScriptBuilder {
     private isImpureImportedFunction;
     private containsImpureCall;
     private getScopeReturnType;
+    private getScopeReturnTypeValidated;
     private agencyFileToDefaultImportName;
     private needsParensLeft;
     private needsParensRight;
@@ -105,6 +111,7 @@ export declare class TypeScriptBuilder {
     private processPipeExpression;
     private processTryExpression;
     private processNewExpression;
+    private processSchemaExpression;
     /**
      * Check if a method name matches any method defined on any known Agency class.
      * Used to decide whether to inject __state into method calls.
@@ -157,8 +164,11 @@ export declare class TypeScriptBuilder {
     private processForkCall;
     private generateNodeCallExpression;
     private processGraphNode;
+    /** If the enclosing function/node has returnTypeValidated, wrap value in __validateType */
+    private maybeWrapReturnValidation;
     private processReturnStatement;
     private processAssignment;
+    private _processAssignmentInner;
     private buildAccessChain;
     private buildAssignmentLhs;
     /**
@@ -167,7 +177,6 @@ export declare class TypeScriptBuilder {
      * response format from type hints, and tools from config object.
      */
     private processLlmCall;
-    private processSentinel;
     private processDebuggerStatement;
     private processMessageThread;
     private processBlockPlain;

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

@@ -213,3 +213,53 @@ ${safeKeyword}def ${funcName}(id: string, shouldSave: boolean, items: string[]):
         }
     });
 });
+describe("schema(Type) expression", () => {
+    it("should compile schema(Type) for named type aliases", () => {
+        expect(() => generateWithBuilder(`
+type Category = "bug" | "feature"
+node main() {
+  const s = schema(Category)
+}
+`)).not.toThrow();
+    });
+    it("should compile schema(Type) for builtin types", () => {
+        expect(() => generateWithBuilder(`
+node main() {
+  const s = schema(number)
+}
+`)).not.toThrow();
+    });
+    it("should compile schema(Result<number>)", () => {
+        expect(() => generateWithBuilder(`
+node main() {
+  const s = schema(Result<number>)
+}
+`)).not.toThrow();
+    });
+    it("generated code contains new Schema(...)", () => {
+        const output = generateWithBuilder(`
+type Category = "bug" | "feature"
+node main() {
+  const s = schema(Category)
+}
+`);
+        expect(output).toContain("new Schema(");
+    });
+});
+import { mapTypeToValidationSchema } from "./typescriptGenerator/typeToZodSchema.js";
+describe("mapTypeToValidationSchema", () => {
+    it("generates Result validation schema for bare Result", () => {
+        const schema = mapTypeToValidationSchema({ type: "resultType", successType: { type: "primitiveType", value: "any" }, failureType: { type: "primitiveType", value: "any" } }, {});
+        expect(schema).toContain("z.literal(true)");
+        expect(schema).toContain("z.literal(false)");
+    });
+    it("generates Result validation schema with typed success", () => {
+        const schema = mapTypeToValidationSchema({ type: "resultType", successType: { type: "primitiveType", value: "number" }, failureType: { type: "primitiveType", value: "string" } }, {});
+        expect(schema).toContain("z.number()");
+        expect(schema).toContain("z.literal(true)");
+    });
+    it("delegates non-Result types to mapTypeToZodSchema", () => {
+        const schema = mapTypeToValidationSchema({ type: "primitiveType", value: "number" }, {});
+        expect(schema).toBe("z.number()");
+    });
+});