@rong/agentscript 0.1.0

package/dist/semantic/analyzer.js

@@ -0,0 +1,519 @@
+import { SHAPE_TYPE_NAMES } from "../ast/constants.js";
+import { SemanticError } from "./diagnostics.js";
+class SemanticScope {
+    parent;
+    bindings = new Map();
+    configs = new Set();
+    constructor(parent) {
+        this.parent = parent;
+    }
+    define(name, binding) {
+        if (this.bindings.has(name)) {
+            return false;
+        }
+        this.bindings.set(name, binding);
+        return true;
+    }
+    hasLocal(name) {
+        return this.bindings.has(name);
+    }
+    resolve(name) {
+        return this.bindings.get(name) ?? this.parent?.resolve(name);
+    }
+    defineConfig(name) {
+        this.configs.add(name);
+    }
+    hasConfig(name) {
+        return this.configs.has(name) || this.parent?.hasConfig(name) === true;
+    }
+    child() {
+        return new SemanticScope(this);
+    }
+}
+export function analyze(program) {
+    const analyzer = new Analyzer();
+    return analyzer.analyze(program);
+}
+export function assertSemanticallyValid(program) {
+    const result = analyze(program);
+    const errors = result.diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    if (errors.length > 0) {
+        throw new SemanticError(errors);
+    }
+    return result;
+}
+class Analyzer {
+    diagnostics = [];
+    agentDecls = new Map();
+    importBindings = new Map();
+    agents = new Map();
+    analyze(program) {
+        this.checkImports(program);
+        this.checkAgents(program);
+        return { diagnostics: this.diagnostics };
+    }
+    checkImports(program) {
+        for (const imported of program.imports) {
+            if (this.importBindings.has(imported.name)) {
+                this.error("DUPLICATE_IMPORT", `Duplicate import '${imported.name}'`, imported.range);
+                continue;
+            }
+            const kind = importResourceKindToBindingKind(imported.resourceKind);
+            this.importBindings.set(imported.name, { kind, range: imported.range });
+            if (imported.resourceKind === "agent") {
+                this.agents.set(imported.name, imported.range);
+            }
+        }
+    }
+    checkAgents(program) {
+        let mainAgent;
+        const seenNames = new Set();
+        for (const agent of program.agents) {
+            if (seenNames.has(agent.name)) {
+                this.error("DUPLICATE_AGENT", `Duplicate agent '${agent.name}'`, agent.range);
+            }
+            seenNames.add(agent.name);
+            this.agentDecls.set(agent.name, agent);
+            this.agents.set(agent.name, agent.range);
+            if (agent.isMain) {
+                if (mainAgent) {
+                    this.error("DUPLICATE_MAIN_AGENT", "Program can only have one main agent", agent.range);
+                }
+                mainAgent = agent;
+            }
+        }
+        if (!mainAgent && program.agents.length > 1) {
+            this.error("MISSING_MAIN_AGENT", "Program with multiple agents must declare one main agent", program.range);
+        }
+        const entryAgent = mainAgent ?? (program.agents.length === 1 ? program.agents[0] : undefined);
+        if (entryAgent && !entryAgent.functions.some((fn) => fn.isMain)) {
+            this.error("MISSING_MAIN_FUNC", "Entry agent must declare one main func", entryAgent.range);
+        }
+        for (const agent of program.agents) {
+            this.checkAgent(agent);
+        }
+    }
+    checkAgent(agent) {
+        const agentScope = new SemanticScope();
+        for (const [name, binding] of this.importBindings) {
+            agentScope.define(name, {
+                kind: binding.kind,
+                range: binding.range,
+                agentName: binding.kind === "agent" ? name : undefined,
+            });
+        }
+        for (const [name, range] of this.agents) {
+            if (!agentScope.hasLocal(name)) {
+                agentScope.define(name, { kind: "agent", range, agentName: name });
+            }
+        }
+        const functionNames = new Set();
+        let mainFunc;
+        for (const fn of agent.functions) {
+            if (functionNames.has(fn.name)) {
+                this.error("DUPLICATE_FUNCTION", `Duplicate function '${fn.name}' in agent '${agent.name}'`, fn.range);
+                continue;
+            }
+            if (fn.isMain) {
+                if (mainFunc) {
+                    this.error("DUPLICATE_MAIN_FUNC", `Agent '${agent.name}' can only have one main func`, fn.range);
+                }
+                mainFunc = fn;
+            }
+            const existing = agentScope.resolve(fn.name);
+            if (existing && existing.kind !== "function") {
+                this.error("DUPLICATE_BINDING", `Function '${fn.name}' conflicts with an imported ${existing.kind}`, fn.range);
+                continue;
+            }
+            functionNames.add(fn.name);
+            agentScope.define(fn.name, functionBinding(agent.name, fn));
+        }
+        for (const config of agent.config) {
+            this.checkConfig(config, agentScope);
+        }
+        for (const fn of agent.functions) {
+            this.checkFunction(fn, agentScope);
+        }
+    }
+    checkFunction(fn, agentScope) {
+        const scope = agentScope.child();
+        const params = new Set();
+        for (const [index, param] of fn.params.entries()) {
+            if (params.has(param.name)) {
+                this.error("DUPLICATE_PARAM", `Duplicate parameter '${param.name}' in function '${fn.name}'`, param.range);
+                continue;
+            }
+            params.add(param.name);
+            const existing = scope.resolve(param.name);
+            if (existing && isImportedBinding(existing.kind)) {
+                this.error("PARAM_SHADOWS_IMPORT", `Parameter '${param.name}' conflicts with an imported ${existing.kind}`, param.range);
+            }
+            scope.define(param.name, { kind: "param", range: param.range });
+            if (param.shape) {
+                if (!fn.isMain || index !== 0 || param.name !== "input") {
+                    this.error("INVALID_PARAM_SHAPE", "V0 only supports shape declarations on the main func input parameter", param.range);
+                }
+                this.checkShapeObject(param.shape);
+            }
+        }
+        for (const stmt of fn.body) {
+            this.checkStatement(stmt, scope);
+        }
+    }
+    checkStatement(stmt, scope) {
+        switch (stmt.kind) {
+            case "ConfigStmt":
+                this.checkConfig(stmt, scope);
+                break;
+            case "UseStmt":
+                this.checkExpression(stmt.value, scope);
+                this.checkUseValue(stmt.value, scope);
+                if (stmt.budget && stmt.budget.amount <= 0) {
+                    this.error("INVALID_BUDGET", "Budget amount must be greater than 0", stmt.range);
+                }
+                break;
+            case "AssignStmt":
+                this.checkAssignment(stmt, scope);
+                break;
+            case "ExprStmt":
+                this.checkExpression(stmt.expr, scope);
+                break;
+            case "IfStmt":
+                this.checkExpression(stmt.condition, scope);
+                this.checkBlock(stmt.thenBody, scope.child());
+                if (stmt.elseBody) {
+                    this.checkBlock(stmt.elseBody, scope.child());
+                }
+                break;
+            case "ForInStmt": {
+                this.checkExpression(stmt.iterable, scope);
+                if (stmt.maxIterations <= 0) {
+                    this.error("INVALID_ITERATION_LIMIT", "For iteration count must be greater than 0", stmt.range);
+                }
+                const child = scope.child();
+                child.define(stmt.itemName, { kind: "local", range: stmt.itemRange });
+                this.checkBlock(stmt.body, child);
+                break;
+            }
+            case "LoopUntilStmt":
+                this.checkExpression(stmt.condition, scope);
+                this.checkBlock(stmt.body, scope.child());
+                break;
+            case "RepeatStmt":
+                this.checkRepeat(stmt, scope);
+                break;
+            case "ReturnStmt":
+                this.checkExpression(stmt.value, scope);
+                break;
+        }
+    }
+    checkConfig(config, scope) {
+        scope.defineConfig(config.key);
+        switch (config.key) {
+            case "model": {
+                if (config.value.kind !== "IdentifierExpr") {
+                    this.error("INVALID_CONFIG", "model must reference an imported llm name", config.value.range);
+                    return;
+                }
+                const binding = scope.resolve(config.value.name);
+                if (!binding) {
+                    this.error("UNKNOWN_MODEL", `Unknown model import '${config.value.name}'`, config.value.range);
+                }
+                else if (binding.kind !== "llm") {
+                    this.error("INVALID_MODEL", `model must reference an imported llm`, config.value.range);
+                }
+                return;
+            }
+            case "role":
+            case "description":
+                if (config.value.kind !== "StringExpr") {
+                    this.error("INVALID_CONFIG", `${config.key} must be a string`, config.value.range);
+                }
+                return;
+        }
+    }
+    checkBlock(statements, scope) {
+        for (const stmt of statements) {
+            this.checkStatement(stmt, scope);
+        }
+    }
+    checkRepeat(stmt, scope) {
+        this.checkBlock(stmt.body, scope.child());
+    }
+    checkAssignment(stmt, scope) {
+        this.checkExpression(stmt.value, scope);
+        if (stmt.target.kind === "IdentifierExpr") {
+            if (!scope.hasLocal(stmt.target.name)) {
+                scope.define(stmt.target.name, { kind: "local", range: stmt.target.range });
+            }
+            return;
+        }
+        if (stmt.target.kind === "MemberExpr") {
+            this.checkExpression(stmt.target.object, scope);
+            return;
+        }
+        this.error("INVALID_ASSIGNMENT_TARGET", "Assignment target must be an identifier or member expression", stmt.target.range);
+    }
+    checkExpression(expr, scope) {
+        switch (expr.kind) {
+            case "IdentifierExpr":
+                this.checkIdentifier(expr.name, expr.range, scope);
+                break;
+            case "StringExpr":
+            case "NumberExpr":
+            case "BooleanExpr":
+            case "NullExpr":
+                break;
+            case "ListExpr":
+                for (const item of expr.items) {
+                    this.checkExpression(item, scope);
+                }
+                break;
+            case "ObjectExpr":
+                for (const property of expr.properties) {
+                    this.checkExpression(property.value, scope);
+                }
+                break;
+            case "ShapeObjectExpr":
+                this.checkShapeObject(expr);
+                break;
+            case "MemberExpr":
+                this.checkMember(expr, scope);
+                break;
+            case "IndexExpr":
+                this.checkExpression(expr.object, scope);
+                this.checkExpression(expr.index, scope);
+                break;
+            case "UnaryExpr":
+                this.checkExpression(expr.value, scope);
+                break;
+            case "BinaryExpr":
+                this.checkExpression(expr.left, scope);
+                this.checkExpression(expr.right, scope);
+                break;
+            case "CallExpr":
+                this.checkCall(expr, scope);
+                break;
+            case "GenerateExpr":
+                this.checkGenerate(expr, scope);
+                break;
+        }
+    }
+    checkIdentifier(name, range, scope) {
+        if (!scope.resolve(name)) {
+            this.error("UNKNOWN_IDENTIFIER", `Unknown identifier '${name}'`, range);
+        }
+    }
+    checkUseValue(expr, scope) {
+        const root = this.rootIdentifier(expr);
+        if (!root) {
+            return;
+        }
+        const binding = scope.resolve(root.name);
+        if (binding && NON_CONTEXT_BINDING_KINDS.has(binding.kind)) {
+            this.error("INVALID_USE_RESOURCE", `Resource '${root.name}' cannot be used as prompt context`, root.range);
+        }
+    }
+    rootIdentifier(expr) {
+        switch (expr.kind) {
+            case "IdentifierExpr":
+                return { name: expr.name, range: expr.range };
+            case "MemberExpr":
+                return this.rootIdentifier(expr.object);
+            case "IndexExpr":
+                return this.rootIdentifier(expr.object);
+            default:
+                return undefined;
+        }
+    }
+    checkMember(expr, scope) {
+        this.checkExpression(expr.object, scope);
+    }
+    checkCall(expr, scope) {
+        this.checkCallable(expr.callee, scope);
+        for (const arg of expr.args) {
+            this.checkExpression(arg, scope);
+        }
+        this.checkCallArity(expr, scope);
+    }
+    checkCallable(callee, scope) {
+        if (callee.kind === "IdentifierExpr") {
+            const binding = scope.resolve(callee.name);
+            if (!binding) {
+                this.error("UNKNOWN_FUNCTION", `Unknown function '${callee.name}'`, callee.range);
+                return;
+            }
+            if (binding.kind !== "function" && binding.kind !== "agent") {
+                this.error("NOT_CALLABLE", `'${callee.name}' is not an agent function or agent`, callee.range);
+            }
+            return;
+        }
+        if (callee.kind === "MemberExpr") {
+            this.checkExpression(callee.object, scope);
+            if (callee.object.kind === "IdentifierExpr") {
+                const binding = scope.resolve(callee.object.name);
+                if (binding?.kind === "memory" && !VALID_MEMORY_METHODS.has(callee.property)) {
+                    this.error("UNKNOWN_MEMORY_METHOD", `Unknown memory method '${callee.object.name}.${callee.property}'`, callee.range);
+                }
+            }
+            return;
+        }
+        this.checkExpression(callee, scope);
+        this.error("NOT_CALLABLE", "Only agent functions and member calls can be called in V0", callee.range);
+    }
+    checkGenerate(expr, scope) {
+        if (expr.options.input) {
+            this.checkExpression(expr.options.input, scope);
+        }
+        this.checkGenerateInput(expr);
+        this.checkShapeObject(expr.returnShape);
+        this.checkGenerateConfig("model", expr, scope);
+        this.checkGenerateConfig("role", expr, scope);
+        this.checkGenerateConfig("description", expr, scope);
+    }
+    checkGenerateInput(expr) {
+        let hasInput = false;
+        const seen = new Set();
+        for (const property of expr.options.properties) {
+            if (seen.has(property.key)) {
+                this.error("DUPLICATE_GENERATE_OPTION", `Duplicate generate option '${property.key}'`, property.range);
+            }
+            seen.add(property.key);
+            if (property.key === "input") {
+                hasInput = true;
+            }
+            else if (property.key === "attempts") {
+                const isPositiveInteger = property.value.kind === "NumberExpr" &&
+                    Number.isInteger(property.value.value) &&
+                    property.value.value > 0;
+                if (!isPositiveInteger) {
+                    this.error("INVALID_GENERATE_ATTEMPTS", "generate attempts must be a positive integer", property.value.range);
+                }
+            }
+            else if (property.key === "limit") {
+                if (!expr.options.limit || expr.options.limit.amount <= 0) {
+                    this.error("INVALID_GENERATE_LIMIT", "generate limit must be a positive budget", property.value.range);
+                }
+            }
+            else if (property.key === "debug") {
+                if (property.value.kind !== "BooleanExpr") {
+                    this.error("INVALID_GENERATE_DEBUG", "generate debug must be a boolean", property.value.range);
+                }
+            }
+            else {
+                this.error("UNKNOWN_GENERATE_OPTION", `Unknown generate option '${property.key}'`, property.range);
+            }
+        }
+        if (!hasInput) {
+            this.error("INVALID_GENERATE_INPUT", "generate object argument requires an input field", expr.options.range);
+        }
+    }
+    checkGenerateConfig(key, expr, scope) {
+        if (!scope.hasConfig(key)) {
+            this.error("MISSING_GENERATE_CONFIG", `generate requires ${key} in the current scope`, expr.range);
+        }
+    }
+    checkCallArity(expr, scope) {
+        if (expr.callee.kind === "IdentifierExpr") {
+            const binding = scope.resolve(expr.callee.name);
+            if (binding?.kind === "function") {
+                this.checkExpectedArity(binding, expr.args.length, expr.range);
+            }
+            else if (binding?.kind === "agent" && binding.agentName) {
+                const fn = this.findAgentMainFunction(binding.agentName);
+                if (!fn) {
+                    this.error("UNKNOWN_FUNCTION", `Agent '${binding.agentName}' has no callable main func`, expr.callee.range);
+                }
+                else {
+                    this.checkExpectedArity(functionBinding(binding.agentName, fn), expr.args.length, expr.range);
+                }
+            }
+            return;
+        }
+        if (expr.callee.kind === "MemberExpr" && expr.callee.object.kind === "IdentifierExpr") {
+            const binding = scope.resolve(expr.callee.object.name);
+            if (binding?.kind === "agent" && binding.agentName) {
+                const fn = this.findAgentFunction(binding.agentName, expr.callee.property);
+                if (!fn) {
+                    this.error("UNKNOWN_FUNCTION", `Unknown function '${binding.agentName}.${expr.callee.property}'`, expr.callee.range);
+                }
+                else {
+                    this.checkExpectedArity(functionBinding(binding.agentName, fn), expr.args.length, expr.range);
+                }
+            }
+            else if (binding?.kind === "memory") {
+                const methodName = `${expr.callee.object.name}.${expr.callee.property}`;
+                if (VALID_MEMORY_METHODS.has(expr.callee.property)) {
+                    if (expr.args.length !== 1) {
+                        this.error("INVALID_ARGUMENT_COUNT", `Memory method '${methodName}' expects 1 argument(s), got ${expr.args.length}`, expr.range);
+                    }
+                }
+                else {
+                    this.error("UNKNOWN_MEMORY_METHOD", `Unknown memory method '${methodName}'`, expr.callee.range);
+                }
+            }
+        }
+    }
+    checkExpectedArity(binding, actual, range) {
+        if (binding.arity === undefined || binding.arity === actual) {
+            return;
+        }
+        const displayName = binding.agentName && binding.functionName ? `${binding.agentName}.${binding.functionName}` : "function";
+        this.error("INVALID_ARGUMENT_COUNT", `Function '${displayName}' expects ${binding.arity} argument(s), got ${actual}`, range);
+    }
+    findAgentFunction(agentName, functionName) {
+        return this.agentDecls.get(agentName)?.functions.find((fn) => fn.name === functionName);
+    }
+    findAgentMainFunction(agentName) {
+        return this.agentDecls.get(agentName)?.functions.find((fn) => fn.isMain);
+    }
+    checkShapeObject(shape) {
+        const fields = new Set();
+        for (const field of shape.fields) {
+            if (fields.has(field.name)) {
+                this.error("DUPLICATE_SHAPE_FIELD", `Duplicate generate return field '${field.name}'`, field.range);
+            }
+            fields.add(field.name);
+            this.checkShapeType(field.type);
+        }
+    }
+    checkShapeType(type) {
+        if (type.kind === "ListShapeType") {
+            this.checkListShapeType(type);
+            return;
+        }
+        this.checkNamedShapeType(type);
+    }
+    checkListShapeType(type) {
+        this.checkShapeType(type.itemType);
+    }
+    checkNamedShapeType(type) {
+        if (!SHAPE_TYPE_NAMES.has(type.name)) {
+            this.error("UNKNOWN_SHAPE_TYPE", `Unsupported shape type '${type.name}'`, type.range);
+        }
+    }
+    error(code, message, range) {
+        this.diagnostics.push({ severity: "error", code, message, range });
+    }
+}
+const IMPORTED_BINDING_KINDS = new Set(["tool", "llm", "file", "agent", "memory"]);
+const NON_CONTEXT_BINDING_KINDS = new Set(["tool", "llm", "agent", "function", "memory"]);
+const VALID_MEMORY_METHODS = new Set(["add", "query"]);
+function functionBinding(agentName, fn) {
+    return {
+        kind: "function",
+        range: fn.range,
+        agentName,
+        functionName: fn.name,
+        arity: fn.params.length,
+    };
+}
+function isImportedBinding(kind) {
+    return IMPORTED_BINDING_KINDS.has(kind);
+}
+function importResourceKindToBindingKind(resourceKind) {
+    if (IMPORTED_BINDING_KINDS.has(resourceKind)) {
+        return resourceKind;
+    }
+    return "file";
+}

package/dist/semantic/diagnostics.js

@@ -0,0 +1,16 @@
+export class SemanticError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        super(formatSemanticDiagnostics(diagnostics));
+        this.name = "SemanticError";
+        this.diagnostics = diagnostics;
+    }
+}
+export function formatSemanticDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => {
+        const { line, column } = diagnostic.range.start;
+        return `${diagnostic.severity.toUpperCase()} ${diagnostic.code} at ${line}:${column}: ${diagnostic.message}`;
+    })
+        .join("\n");
+}

package/dist/utils/assert.js

@@ -0,0 +1,3 @@
+export function assertNever(value) {
+    throw new Error(`Unexpected value: ${String(value)}`);
+}