@jsleekr/graft 5.7.2 → 6.0.0

package/dist/codegen/hooks.js

@@ -163,3 +163,86 @@ function filterToJs(t) {
     const op = condition.op === '==' ? '===' : condition.op === '!=' ? '!==' : condition.op;
     return `result[${JSON.stringify(field)}] = (result[${JSON.stringify(field)}] || []).filter(item => item[${JSON.stringify(fieldName)}] ${op} ${valueStr});`;
 }
+/**
+ * Generate a router hook for conditional edges.
+ * Evaluates branch conditions and writes routing decision.
+ */
+export function generateConditionalHook(edge) {
+    if (edge.target.kind !== 'conditional')
+        return null;
+    const source = edge.source.toLowerCase();
+    const branches = edge.target.branches;
+    const targets = branches.map(b => b.target).filter(t => t !== 'done');
+    const conditionCode = branchesToJs(branches);
+    return `#!/usr/bin/env node
+// Auto-generated by Graft Compiler
+// Conditional routing: ${edge.source} -> {${branches.map(b => b.target).join(', ')}}
+
+const fs = require('fs');
+const path = require('path');
+
+const INPUT = path.resolve('.graft/session/node_outputs/${source}.json');
+const ROUTE = path.resolve('.graft/session/routing/${source}_route.json');
+
+if (!fs.existsSync(INPUT)) {
+  process.exit(0);
+}
+
+const data = JSON.parse(fs.readFileSync(INPUT, 'utf-8'));
+
+${conditionCode}
+
+fs.mkdirSync(path.dirname(ROUTE), { recursive: true });
+fs.writeFileSync(ROUTE, JSON.stringify({ target, from: ${JSON.stringify(edge.source)} }, null, 2));
+`;
+}
+function branchesToJs(branches) {
+    const lines = [];
+    let first = true;
+    for (const branch of branches) {
+        if (!branch.condition) {
+            // else branch
+            if (first) {
+                lines.push(`let target = ${JSON.stringify(branch.target)};`);
+            }
+            else {
+                lines.push(`} else {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+                lines.push(`}`);
+            }
+        }
+        else {
+            const jsCondition = exprToJs(branch.condition);
+            if (first) {
+                lines.push(`let target = null;`);
+                lines.push(`if (${jsCondition}) {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+                first = false;
+            }
+            else {
+                lines.push(`} else if (${jsCondition}) {`);
+                lines.push(`  target = ${JSON.stringify(branch.target)};`);
+            }
+        }
+    }
+    // Close the if chain if we have conditions but no else
+    if (!first && !branches.some(b => !b.condition)) {
+        lines.push(`}`);
+    }
+    return lines.join('\n');
+}
+function exprToJs(expr) {
+    if (expr.kind === 'binary') {
+        const left = exprToJs(expr.left);
+        const right = exprToJs(expr.right);
+        const op = expr.op === '==' ? '===' : expr.op === '!=' ? '!==' : expr.op;
+        return `${left} ${op} ${right}`;
+    }
+    if (expr.kind === 'field_access') {
+        return `data[${JSON.stringify(expr.segments[0])}]`;
+    }
+    if (expr.kind === 'literal') {
+        return JSON.stringify(expr.value);
+    }
+    return formatExpr(expr);
+}

package/dist/codegen/orchestration.js

@@ -7,12 +7,16 @@ export function generateOrchestration(program, report) {
     const index = new ProgramIndex(program);
     const memoryNames = new Set(program.memories.map(m => m.name));
     const edgeMap = new Map();
+    const conditionalEdgeMap = new Map();
     for (const edge of program.edges) {
         if (edge.target.kind === 'direct' && edge.transforms.length > 0) {
             edgeMap.set(`${edge.source}->${edge.target.node}`, { transforms: edge.transforms });
         }
+        else if (edge.target.kind === 'conditional') {
+            conditionalEdgeMap.set(edge.source, edge);
+        }
     }
-    const { text: steps } = generateSteps(graph.flow, report, edgeMap, 1, null, index.nodeMap, memoryNames);
+    const { text: steps } = generateSteps(graph.flow, report, edgeMap, conditionalEdgeMap, 1, null, index.nodeMap, memoryNames);
     // Memory preamble
     const memorySection = program.memories.length > 0
         ? `
@@ -70,7 +74,42 @@ function describeTransforms(transforms) {
     }
     return parts.join(', then ');
 }
-function generateSteps(flow, report, edgeMap, startStep, prevNode, nodeMap, memoryNames) {
+function describeCondition(expr) {
+    if (expr.kind === 'binary') {
+        const left = expr.left.kind === 'field_access' ? `\`${expr.left.segments[0]}\`` : formatExpr(expr.left);
+        const right = expr.right.kind === 'literal' ? `\`${expr.right.value}\`` : formatExpr(expr.right);
+        return `${left} ${expr.op} ${right}`;
+    }
+    return formatExpr(expr);
+}
+function generateConditionalRoutingStep(stepNum, edge, nodeMap, report) {
+    if (edge.target.kind !== 'conditional')
+        return '';
+    const source = edge.source.toLowerCase();
+    const branches = edge.target.branches;
+    let text = `
+### Step ${stepNum}: Conditional routing from ${edge.source}
+- **Automatic**: Router hook evaluates conditions on ${edge.source}'s output
+- Routing file: \`.graft/session/routing/${source}_route.json\`
+- Read the \`target\` field and proceed accordingly:
+`;
+    for (const branch of branches) {
+        const label = branch.condition ? describeCondition(branch.condition) : 'else (default)';
+        if (branch.target === 'done') {
+            text += `  - If ${label}: **pipeline complete**\n`;
+        }
+        else {
+            const nodeReport = report.nodes.find(n => n.name === branch.target);
+            const tokenInfo = nodeReport
+                ? ` (tokens: input ~${nodeReport.estimatedIn.toLocaleString('en-US')} / output ~${nodeReport.estimatedOut.toLocaleString('en-US')})`
+                : '';
+            text += `  - If ${label}: run **${branch.target}** agent${tokenInfo}\n`;
+        }
+    }
+    text += `- Each branch agent reads from \`.graft/session/node_outputs/${source}.json\`\n`;
+    return text;
+}
+function generateSteps(flow, report, edgeMap, conditionalEdgeMap, startStep, prevNode, nodeMap, memoryNames) {
     let text = '';
     let stepNum = startStep;
     let prev = prevNode;
@@ -154,9 +193,15 @@ function generateSteps(flow, report, edgeMap, startStep, prevNode, nodeMap, memo
 - Completion: \`===NODE_COMPLETE:${lowerName}===\`
 - Output: \`.graft/session/node_outputs/${lowerName}.json\`
 `;
+                stepNum++;
+                // Conditional routing after this node
+                const condEdge = conditionalEdgeMap.get(step.name);
+                if (condEdge && condEdge.target.kind === 'conditional') {
+                    text += generateConditionalRoutingStep(stepNum, condEdge, nodeMap, report);
+                    stepNum++;
+                }
                 prev = step.name;
                 prevParallelBranches = [];
-                stepNum++;
                 break;
             }
             case 'parallel': {

package/dist/codegen/settings.js

@@ -42,17 +42,25 @@ export function generateSettings(program, sourceFile, index) {
     // Collect all hook commands, then merge into a single "Write" matcher entry
     const hookCommands = [];
     for (const edge of program.edges) {
-        if (edge.transforms.length === 0)
-            continue;
-        if (edge.target.kind !== 'direct')
-            continue;
-        const source = edge.source.toLowerCase();
-        const target = edge.target.node.toLowerCase();
-        hookCommands.push({
-            type: 'command',
-            command: `node .claude/hooks/${source}-to-${target}.js`,
-            if: `Write(.graft/session/node_outputs/${source}.json)`,
-        });
+        if (edge.target.kind === 'conditional') {
+            // Conditional edge → router hook
+            const source = edge.source.toLowerCase();
+            hookCommands.push({
+                type: 'command',
+                command: `node .claude/hooks/${source}-router.js`,
+                if: `Write(.graft/session/node_outputs/${source}.json)`,
+            });
+        }
+        else if (edge.target.kind === 'direct' && edge.transforms.length > 0) {
+            // Direct edge with transforms → transform hook
+            const source = edge.source.toLowerCase();
+            const target = edge.target.node.toLowerCase();
+            hookCommands.push({
+                type: 'command',
+                command: `node .claude/hooks/${source}-to-${target}.js`,
+                if: `Write(.graft/session/node_outputs/${source}.json)`,
+            });
+        }
     }
     const hookEntries = [];
     if (hookCommands.length > 0) {

package/dist/compiler.d.ts

@@ -3,6 +3,7 @@ import { GeneratedFile } from './codegen/codegen.js';
 import { GraftError } from './errors/diagnostics.js';
 import { Program } from './parser/ast.js';
 import { ProgramIndex } from './program-index.js';
+import { CodegenBackend } from './codegen/backend.js';
 export interface ProgramResult {
     success: boolean;
     program?: Program;
@@ -15,7 +16,7 @@ export interface CompileResult extends ProgramResult {
     files?: GeneratedFile[];
 }
 export declare function compileToProgram(source: string, sourceFile: string): ProgramResult;
-export declare function compileAndGenerate(source: string, sourceFile: string): CompileResult;
+export declare function compileAndGenerate(source: string, sourceFile: string, backend?: CodegenBackend): CompileResult;
 /** Backward-compatible alias for compileAndGenerate */
-export declare function compile(source: string, sourceFile: string): CompileResult;
-export declare function compileAndWrite(source: string, sourceFile: string, outDir: string): CompileResult;
+export declare function compile(source: string, sourceFile: string, backend?: CodegenBackend): CompileResult;
+export declare function compileAndWrite(source: string, sourceFile: string, outDir: string, backend?: CodegenBackend): CompileResult;

package/dist/compiler.js

@@ -68,7 +68,7 @@ export function compileToProgram(source, sourceFile) {
     warnings.push(...report.warnings);
     return { success: true, program, index, report, errors, warnings };
 }
-export function compileAndGenerate(source, sourceFile) {
+export function compileAndGenerate(source, sourceFile, backend) {
     const result = compileToProgram(source, sourceFile);
     if (!result.success || !result.program) {
         return result;
@@ -85,15 +85,15 @@ export function compileAndGenerate(source, sourceFile) {
         };
     }
     // Generate
-    const files = generate(result.program, result.report, sourceFile, result.index);
+    const files = generate(result.program, result.report, sourceFile, result.index, backend);
     return { ...result, files };
 }
 /** Backward-compatible alias for compileAndGenerate */
-export function compile(source, sourceFile) {
-    return compileAndGenerate(source, sourceFile);
+export function compile(source, sourceFile, backend) {
+    return compileAndGenerate(source, sourceFile, backend);
 }
-export function compileAndWrite(source, sourceFile, outDir) {
-    const result = compile(source, sourceFile);
+export function compileAndWrite(source, sourceFile, outDir, backend) {
+    const result = compile(source, sourceFile, backend);
     if (result.success && result.files) {
         writeFiles(result.files, outDir);
     }

package/dist/errors/diagnostics.d.ts

@@ -16,6 +16,12 @@ export declare class GraftError extends Error {
     readonly location: SourceLocation;
     readonly severity: 'error' | 'warning';
     readonly code?: GraftErrorCode | undefined;
-    constructor(message: string, location: SourceLocation, severity?: 'error' | 'warning', code?: GraftErrorCode | undefined);
-    format(source: string): string;
+    readonly help?: string | undefined;
+    constructor(message: string, location: SourceLocation, severity?: 'error' | 'warning', code?: GraftErrorCode | undefined, help?: string | undefined);
+    format(source: string, filename?: string): string;
 }
+/**
+ * Find the closest match to `name` from `candidates` using Levenshtein distance.
+ * Returns the best match if distance <= maxDistance, otherwise undefined.
+ */
+export declare function didYouMean(name: string, candidates: string[], maxDistance?: number): string | undefined;

package/dist/errors/diagnostics.js

@@ -2,24 +2,81 @@ export class GraftError extends Error {
     location;
     severity;
     code;
-    constructor(message, location, severity = 'error', code) {
+    help;
+    constructor(message, location, severity = 'error', code, help) {
         super(message);
         this.location = location;
         this.severity = severity;
         this.code = code;
+        this.help = help;
         this.name = 'GraftError';
     }
-    format(source) {
+    format(source, filename) {
         const lines = source.split('\n');
         const lineIdx = this.location.line - 1;
         const line = (lineIdx >= 0 && lineIdx < lines.length) ? lines[lineIdx] : '';
         const col = Math.max(0, this.location.column - 1);
-        const pointer = ' '.repeat(col) + '^';
-        return [
-            `Error at line ${this.location.line}:${this.location.column}:`,
-            `    ${line}`,
-            `    ${pointer}`,
-            `    ${this.message}`,
-        ].join('\n');
+        const lineNumStr = String(this.location.line);
+        const gutter = ' '.repeat(lineNumStr.length);
+        // Underline: use length if available, otherwise single caret
+        const underlineLen = this.location.length && this.location.length > 0
+            ? this.location.length
+            : 1;
+        const underline = '^'.repeat(underlineLen);
+        const label = this.severity === 'warning' ? 'warning' : 'error';
+        const codeStr = this.code ? `[${this.code}]` : '';
+        const file = filename || '<source>';
+        const result = [
+            `${label}${codeStr}: ${this.message}`,
+            ` ${gutter}--> ${file}:${this.location.line}:${this.location.column}`,
+            ` ${gutter} |`,
+            ` ${lineNumStr} | ${line}`,
+            ` ${gutter} | ${' '.repeat(col)}${underline}`,
+        ];
+        if (this.help) {
+            result.push(` ${gutter} |`);
+            result.push(` ${gutter} = help: ${this.help}`);
+        }
+        return result.join('\n');
     }
 }
+/**
+ * Find the closest match to `name` from `candidates` using Levenshtein distance.
+ * Returns the best match if distance <= maxDistance, otherwise undefined.
+ */
+export function didYouMean(name, candidates, maxDistance = 3) {
+    let best;
+    let bestDist = maxDistance + 1;
+    for (const candidate of candidates) {
+        const dist = levenshtein(name.toLowerCase(), candidate.toLowerCase());
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = candidate;
+        }
+    }
+    return bestDist <= maxDistance ? best : undefined;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    // Single-row DP
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insert
+            prev[j] + 1, // delete
+            prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}

package/dist/formatter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Graft AST pretty-printer — formats a Program back to .gft source.
+ */
+import { Program } from './parser/ast.js';
+export declare function formatProgram(program: Program): string;

package/dist/formatter.js

@@ -0,0 +1,170 @@
+import { formatExpr } from './format.js';
+export function formatProgram(program) {
+    const sections = [];
+    // Imports
+    for (const imp of program.imports) {
+        sections.push(formatImport(imp));
+    }
+    // Memories
+    for (const mem of program.memories) {
+        sections.push(formatMemory(mem));
+    }
+    // Contexts
+    for (const ctx of program.contexts) {
+        if (!ctx.sourceFile || ctx.sourceFile === program.contexts[0]?.sourceFile) {
+            sections.push(formatContext(ctx));
+        }
+    }
+    // Nodes
+    for (const node of program.nodes) {
+        if (!node.sourceFile || node.sourceFile === program.nodes[0]?.sourceFile) {
+            sections.push(formatNode(node));
+        }
+    }
+    // Edges
+    for (const edge of program.edges) {
+        sections.push(formatEdge(edge));
+    }
+    // Graphs
+    for (const graph of program.graphs) {
+        sections.push(formatGraph(graph));
+    }
+    return sections.join('\n\n') + '\n';
+}
+function formatImport(imp) {
+    return `import { ${imp.names.join(', ')} } from "${imp.path}"`;
+}
+function formatMemory(mem) {
+    const fields = mem.fields.map(f => `  ${f.name}: ${formatType(f.type)}`).join('\n');
+    return `memory ${mem.name}(max_tokens: ${formatTokens(mem.maxTokens)}, storage: ${mem.storage}) {\n${fields}\n}`;
+}
+function formatContext(ctx) {
+    const fields = ctx.fields.map(f => `  ${f.name}: ${formatType(f.type)}`).join('\n');
+    return `context ${ctx.name}(max_tokens: ${formatTokens(ctx.maxTokens)}) {\n${fields}\n}`;
+}
+function formatNode(node) {
+    const lines = [];
+    lines.push(`node ${node.name}(model: ${node.model}, budget: ${formatTokens(node.budgetIn)}/${formatTokens(node.budgetOut)}) {`);
+    // reads
+    if (node.reads.length > 0) {
+        lines.push(`  reads: [${node.reads.map(formatContextRef).join(', ')}]`);
+    }
+    // tools
+    if (node.tools.length > 0) {
+        lines.push(`  tools: [${node.tools.join(', ')}]`);
+    }
+    // writes
+    if (node.writes.length > 0) {
+        lines.push(`  writes: [${node.writes.map(w => w.field ? `${w.memory}.${w.field}` : w.memory).join(', ')}]`);
+    }
+    // on_failure
+    if (node.onFailure) {
+        lines.push(`  on_failure: ${formatFailure(node.onFailure)}`);
+    }
+    // produces
+    lines.push('');
+    const producesFields = node.produces.fields.map(f => `    ${f.name}: ${formatType(f.type)}`).join('\n');
+    lines.push(`  produces ${node.produces.name} {`);
+    lines.push(producesFields);
+    lines.push(`  }`);
+    lines.push('}');
+    return lines.join('\n');
+}
+function formatEdge(edge) {
+    if (edge.target.kind === 'conditional') {
+        const branches = edge.target.branches.map(b => {
+            if (b.condition) {
+                return `  when ${formatExpr(b.condition)} -> ${b.target}`;
+            }
+            return `  else -> ${b.target}`;
+        }).join('\n');
+        return `edge ${edge.source} -> {\n${branches}\n}`;
+    }
+    let line = `edge ${edge.source} -> ${edge.target.node}`;
+    if (edge.transforms.length > 0) {
+        line += '\n  | ' + edge.transforms.map(formatTransform).join('\n  | ');
+    }
+    return line;
+}
+function formatGraph(graph) {
+    const params = graph.params.length > 0
+        ? `, ${graph.params.map(p => `${p.name}: ${p.type}${p.default !== undefined ? ` = ${p.default}` : ''}`).join(', ')}`
+        : '';
+    const flowStr = formatFlow(graph.flow, 2);
+    return `graph ${graph.name}(input: ${graph.input}, output: ${graph.output}, budget: ${formatTokens(graph.budget)}${params}) {\n${flowStr}\n}`;
+}
+function formatFlow(flow, indent) {
+    const pad = ' '.repeat(indent);
+    const parts = [];
+    for (const step of flow) {
+        switch (step.kind) {
+            case 'node':
+                parts.push(step.name);
+                break;
+            case 'parallel':
+                parts.push(`parallel { ${step.branches.join('  ')} }`);
+                break;
+            case 'foreach': {
+                const body = formatFlow(step.body, indent + 2);
+                parts.push(`foreach ${step.source}.${step.field} as ${step.binding} (max: ${step.maxIterations}) {\n${body}\n${pad}}`);
+                break;
+            }
+            case 'let':
+                parts.push(`let ${step.name} = ${formatExpr(step.value)}`);
+                break;
+            case 'graph_call':
+                parts.push(`${step.name}(${step.args.map(a => `${a.name}: ${formatExpr(a.value)}`).join(', ')})`);
+                break;
+        }
+    }
+    // Join with -> for sequential steps, but done is implicit
+    return pad + parts.join('\n' + pad + '-> ') + '\n' + pad + '-> done';
+}
+function formatTransform(t) {
+    switch (t.type) {
+        case 'select': return `select(${t.fields.join(', ')})`;
+        case 'drop': return `drop(${t.field})`;
+        case 'compact': return 'compact';
+        case 'truncate': return `truncate(${t.tokens})`;
+        case 'filter': return `filter(${t.field}, ${formatExpr(t.condition)})`;
+    }
+}
+function formatContextRef(ref) {
+    if (ref.field && ref.field.length === 1) {
+        return `${ref.context}.${ref.field[0]}`;
+    }
+    if (ref.field && ref.field.length > 1) {
+        return `${ref.context}.{${ref.field.join(', ')}}`;
+    }
+    return ref.context;
+}
+function formatFailure(f) {
+    switch (f.type) {
+        case 'retry': return `retry(${f.max})`;
+        case 'fallback': return `fallback(${f.node})`;
+        case 'retry_then_fallback': return `retry(${f.max}, fallback: ${f.node})`;
+        case 'skip': return 'skip';
+        case 'abort': return 'abort';
+    }
+}
+function formatType(t) {
+    switch (t.kind) {
+        case 'primitive': return t.name;
+        case 'primitive_range': return `${t.name}(${t.min}..${t.max})`;
+        case 'list': return `List<${formatType(t.element)}>`;
+        case 'map': return `Map<${formatType(t.key)}, ${formatType(t.value)}>`;
+        case 'optional': return `Optional<${formatType(t.inner)}>`;
+        case 'token_bounded': return `TokenBounded<${formatType(t.inner)}, ${t.max}>`;
+        case 'enum': return `enum(${t.values.join(', ')})`;
+        case 'struct': {
+            const fields = t.fields.map(f => `${f.name}: ${formatType(f.type)}`).join(', ');
+            return `${t.name} { ${fields} }`;
+        }
+        case 'domain': return t.name;
+    }
+}
+function formatTokens(n) {
+    if (n >= 1000 && n % 1000 === 0)
+        return `${n / 1000}k`;
+    return String(n);
+}

package/dist/generator.d.ts

@@ -0,0 +1,28 @@
+import { GraftError } from './errors/diagnostics.js';
+/** Function that calls the LLM. Injectable for testing. */
+export type LLMCaller = (params: {
+    system: string;
+    userMessage: string;
+}) => Promise<string>;
+export interface GenerateOptions {
+    output?: string;
+    /** Override the LLM caller (for testing). */
+    llmCaller?: LLMCaller;
+}
+export interface GenerateResult {
+    source: string;
+    errors: GraftError[];
+}
+/**
+ * Extract .gft source from an LLM response.
+ * Multi-strategy: (1) ```gft fence, (2) any fence, (3) bare response.
+ */
+export declare function extractGftSource(response: string): string;
+/**
+ * Build the system prompt for .gft generation.
+ */
+export declare function buildSystemPrompt(): string;
+/**
+ * Generate a .gft file from a natural language description.
+ */
+export declare function generateGft(description: string, options?: GenerateOptions): Promise<GenerateResult>;