@renseiai/agentfactory 0.8.6 → 0.8.8

package/dist/src/workflow/expression/ast.js

@@ -0,0 +1,8 @@
+/**
+ * Expression AST Node Definitions
+ *
+ * Typed AST nodes for parsed condition expressions from WorkflowDefinition
+ * `branching[].condition` fields. Uses discriminated unions with a literal
+ * `type` field for exhaustive pattern matching.
+ */
+export {};

package/dist/src/workflow/expression/context.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Evaluation Context
+ *
+ * Defines the sandboxed context in which expression ASTs are evaluated.
+ * The context provides variable bindings and registered helper functions,
+ * with no access to globals, prototypes, or dynamic code execution.
+ */
+import type { GovernorIssue } from '../../governor/governor-types.js';
+/**
+ * The sandboxed evaluation context passed to the expression evaluator.
+ *
+ * - `variables` holds named values that `VariableRef` nodes resolve against.
+ * - `functions` holds callable helpers that `FunctionCall` nodes invoke.
+ */
+export interface EvaluationContext {
+    /** Variable bindings — e.g., { isParentIssue: true, priority: 3 } */
+    readonly variables: Record<string, unknown>;
+    /** Registered helper functions */
+    readonly functions: Record<string, (...args: unknown[]) => unknown>;
+}
+export interface BuildContextOptions {
+    /** Whether the issue has sub-issues (i.e., it is a parent issue) */
+    hasSubIssues?: boolean;
+}
+/**
+ * Build an EvaluationContext from a GovernorIssue and optional phase state.
+ *
+ * This is the primary way to create contexts for condition evaluation
+ * during workflow transitions. It:
+ *   1. Extracts well-known variables from the issue (status, labels, etc.)
+ *   2. Merges in phase-state booleans (researchCompleted, etc.)
+ *   3. Registers all built-in helper functions
+ *
+ * @param issue      - The issue being evaluated.
+ * @param phaseState - Optional map of phase completion flags.
+ * @param opts       - Additional context not on the issue itself.
+ * @returns A fully populated EvaluationContext.
+ */
+export declare function buildEvaluationContext(issue: GovernorIssue, phaseState?: Record<string, boolean>, opts?: BuildContextOptions): EvaluationContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/src/workflow/expression/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../src/workflow/expression/context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAOrE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC3C,kCAAkC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAA;CACpE;AAMD,MAAM,WAAW,mBAAmB;IAClC,oEAAoE;IACpE,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,aAAa,EACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,IAAI,CAAC,EAAE,mBAAmB,GACzB,iBAAiB,CAkBnB"}

package/dist/src/workflow/expression/context.js

@@ -0,0 +1,37 @@
+/**
+ * Evaluation Context
+ *
+ * Defines the sandboxed context in which expression ASTs are evaluated.
+ * The context provides variable bindings and registered helper functions,
+ * with no access to globals, prototypes, or dynamic code execution.
+ */
+import { createBuiltinHelpers } from './helpers.js';
+/**
+ * Build an EvaluationContext from a GovernorIssue and optional phase state.
+ *
+ * This is the primary way to create contexts for condition evaluation
+ * during workflow transitions. It:
+ *   1. Extracts well-known variables from the issue (status, labels, etc.)
+ *   2. Merges in phase-state booleans (researchCompleted, etc.)
+ *   3. Registers all built-in helper functions
+ *
+ * @param issue      - The issue being evaluated.
+ * @param phaseState - Optional map of phase completion flags.
+ * @param opts       - Additional context not on the issue itself.
+ * @returns A fully populated EvaluationContext.
+ */
+export function buildEvaluationContext(issue, phaseState, opts) {
+    const hasSubIssues = opts?.hasSubIssues ?? false;
+    const variables = {
+        // Issue-derived variables
+        isParentIssue: hasSubIssues,
+        labels: issue.labels,
+        status: issue.status,
+        priority: 0, // GovernorIssue doesn't carry priority; default to 0
+        // Spread phase-state booleans so expressions like
+        // `researchCompleted and not backlogCreationCompleted` work directly.
+        ...phaseState,
+    };
+    const functions = createBuiltinHelpers(issue, { hasSubIssues });
+    return { variables, functions };
+}

package/dist/src/workflow/expression/evaluator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Expression Evaluator (Tree-Walking)
+ *
+ * Walks a parsed AST and produces a result value within a sandboxed
+ * EvaluationContext. No `eval()`, `new Function()`, or dynamic code
+ * execution is used — evaluation is a pure recursive descent over the
+ * typed AST nodes.
+ */
+import type { ASTNode } from './ast.js';
+import type { EvaluationContext } from './context.js';
+/**
+ * Error thrown when expression evaluation fails at runtime.
+ *
+ * Examples: unknown function name, type mismatch in numeric comparison.
+ */
+export declare class EvaluationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Evaluate an AST node within the given context.
+ *
+ * @param ast     - The AST node to evaluate.
+ * @param context - The sandboxed evaluation context.
+ * @returns The result of evaluating the node.
+ * @throws {EvaluationError} on unknown functions or type mismatches.
+ */
+export declare function evaluate(ast: ASTNode, context: EvaluationContext): unknown;
+//# sourceMappingURL=evaluator.d.ts.map

package/dist/src/workflow/expression/evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.d.ts","sourceRoot":"","sources":["../../../../src/workflow/expression/evaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAMrD;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAiBD;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CA6D1E"}

package/dist/src/workflow/expression/evaluator.js

@@ -0,0 +1,165 @@
+/**
+ * Expression Evaluator (Tree-Walking)
+ *
+ * Walks a parsed AST and produces a result value within a sandboxed
+ * EvaluationContext. No `eval()`, `new Function()`, or dynamic code
+ * execution is used — evaluation is a pure recursive descent over the
+ * typed AST nodes.
+ */
+// ---------------------------------------------------------------------------
+// EvaluationError
+// ---------------------------------------------------------------------------
+/**
+ * Error thrown when expression evaluation fails at runtime.
+ *
+ * Examples: unknown function name, type mismatch in numeric comparison.
+ */
+export class EvaluationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EvaluationError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Coerce an arbitrary value to a boolean using JavaScript truthiness rules.
+ */
+function toBool(value) {
+    return Boolean(value);
+}
+// ---------------------------------------------------------------------------
+// Evaluator
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate an AST node within the given context.
+ *
+ * @param ast     - The AST node to evaluate.
+ * @param context - The sandboxed evaluation context.
+ * @returns The result of evaluating the node.
+ * @throws {EvaluationError} on unknown functions or type mismatches.
+ */
+export function evaluate(ast, context) {
+    switch (ast.type) {
+        // -------------------------------------------------------------------
+        // Literals — return value directly
+        // -------------------------------------------------------------------
+        case 'BooleanLiteral':
+            return ast.value;
+        case 'StringLiteral':
+            return ast.value;
+        case 'NumberLiteral':
+            return ast.value;
+        // -------------------------------------------------------------------
+        // Variable reference — look up in context, default to false
+        // -------------------------------------------------------------------
+        case 'VariableRef': {
+            const value = context.variables[ast.name];
+            // Undefined variables resolve to `false` (no crash)
+            if (value === undefined) {
+                return false;
+            }
+            return value;
+        }
+        // -------------------------------------------------------------------
+        // Unary operator
+        // -------------------------------------------------------------------
+        case 'UnaryOp': {
+            // Currently only 'not' is supported
+            const operand = evaluate(ast.operand, context);
+            return !toBool(operand);
+        }
+        // -------------------------------------------------------------------
+        // Binary operator
+        // -------------------------------------------------------------------
+        case 'BinaryOp':
+            return evaluateBinaryOp(ast.operator, ast.left, ast.right, context);
+        // -------------------------------------------------------------------
+        // Function call
+        // -------------------------------------------------------------------
+        case 'FunctionCall': {
+            const fn = context.functions[ast.name];
+            if (!fn) {
+                throw new EvaluationError(`Unknown function '${ast.name}'. Available functions: ${Object.keys(context.functions).join(', ') || '(none)'}`);
+            }
+            const args = ast.args.map((arg) => evaluate(arg, context));
+            return fn(...args);
+        }
+        default: {
+            // Exhaustive check — should never reach here with a well-typed AST
+            const _exhaustive = ast;
+            throw new EvaluationError(`Unknown AST node type: ${_exhaustive.type}`);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Binary operator evaluation
+// ---------------------------------------------------------------------------
+function evaluateBinaryOp(operator, left, right, context) {
+    switch (operator) {
+        // Short-circuit logical operators
+        case 'and': {
+            const leftVal = evaluate(left, context);
+            if (!toBool(leftVal))
+                return leftVal;
+            return evaluate(right, context);
+        }
+        case 'or': {
+            const leftVal = evaluate(left, context);
+            if (toBool(leftVal))
+                return leftVal;
+            return evaluate(right, context);
+        }
+        // Equality — works across all types
+        case 'eq': {
+            const leftVal = evaluate(left, context);
+            const rightVal = evaluate(right, context);
+            return leftVal === rightVal;
+        }
+        case 'neq': {
+            const leftVal = evaluate(left, context);
+            const rightVal = evaluate(right, context);
+            return leftVal !== rightVal;
+        }
+        // Ordering comparisons — require matching numeric types
+        case 'gt':
+        case 'lt':
+        case 'gte':
+        case 'lte': {
+            const leftVal = evaluate(left, context);
+            const rightVal = evaluate(right, context);
+            return evaluateOrdering(operator, leftVal, rightVal);
+        }
+        default:
+            throw new EvaluationError(`Unknown operator '${operator}'`);
+    }
+}
+function evaluateOrdering(operator, left, right) {
+    // Both must be numbers or both must be strings for ordering comparisons
+    if (typeof left === 'number' && typeof right === 'number') {
+        switch (operator) {
+            case 'gt': return left > right;
+            case 'lt': return left < right;
+            case 'gte': return left >= right;
+            case 'lte': return left <= right;
+        }
+    }
+    if (typeof left === 'string' && typeof right === 'string') {
+        switch (operator) {
+            case 'gt': return left > right;
+            case 'lt': return left < right;
+            case 'gte': return left >= right;
+            case 'lte': return left <= right;
+        }
+    }
+    throw new EvaluationError(`Cannot compare ${typeLabel(left)} and ${typeLabel(right)} with '${operator}'. ` +
+        `Both operands must be numbers or both must be strings.`);
+}
+function typeLabel(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}

package/dist/src/workflow/expression/evaluator.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=evaluator.test.d.ts.map

package/dist/src/workflow/expression/evaluator.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluator.test.d.ts","sourceRoot":"","sources":["../../../../src/workflow/expression/evaluator.test.ts"],"names":[],"mappings":""}