@jsleekr/graft 5.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JSLEEKR
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,235 @@
+[![npm version](https://img.shields.io/npm/v/@graft-lang/graft.svg)](https://www.npmjs.com/package/@graft-lang/graft)
+[![CI](https://github.com/JSLEEKR/graft/actions/workflows/ci.yml/badge.svg)](https://github.com/JSLEEKR/graft/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/node/v/@graft-lang/graft.svg)](https://nodejs.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+# Graft
+
+**A graph-native language for AI agent pipelines.**
+
+Graft compiles `.gft` files into [Claude Code](https://docs.anthropic.com/en/docs/claude-code) harness structures. Define your multi-agent pipeline declaratively, and the compiler generates the agents, hooks, orchestration, and settings — with compile-time token budget analysis.
+
+## Quick Start
+
+```bash
+npm install -g @graft-lang/graft
+```
+
+Write a pipeline (`hello.gft`):
+
+```graft
+context UserRequest(max_tokens: 500) {
+  question: String
+}
+
+node Researcher(model: sonnet, budget: 2k/1k) {
+  reads: [UserRequest]
+  produces Research {
+    findings: List<String>
+    confidence: Float(0..1)
+  }
+}
+
+node Writer(model: haiku, budget: 1500/800) {
+  reads: [Research.findings]
+  produces Answer { response: String }
+}
+
+edge Researcher -> Writer | select(findings) | compact
+
+graph SimpleQA(input: UserRequest, output: Answer, budget: 6k) {
+  Researcher -> Writer -> done
+}
+```
+
+Compile it:
+
+```
+$ graft compile hello.gft
+
+✓ Parse OK
+✓ Scope check OK
+✓ Type check OK
+✓ Token analysis:
+    Researcher           in ~   500  out ~ 1,000
+    Writer               in ~    63  out ~   800
+    Best path:     2,363 tokens ✓ within budget (6,000)
+
+Generated:
+  .claude/agents/researcher.md     ← agent definition
+  .claude/agents/writer.md         ← agent definition
+  .claude/hooks/researcher-to-writer.js  ← edge transform (Node.js)
+  .claude/CLAUDE.md                ← orchestration plan
+  .claude/settings.json            ← model routing + hooks
+```
+
+Open the project directory in Claude Code — it picks up the generated `.claude/` structure and runs the pipeline.
+
+## What Does Graft Generate?
+
+| Graft Source | Generated Output | Purpose |
+|-------------|-----------------|---------|
+| `node` | `.claude/agents/*.md` | Agent with model, tools, output schema |
+| `edge \| transform` | `.claude/hooks/*.js` | Node.js data transform between nodes |
+| `graph` | `.claude/CLAUDE.md` | Step-by-step orchestration plan |
+| `memory` | `.graft/memory/*.json` | Persistent state across runs |
+| config | `.claude/settings.json` | Model routing, budget, hook registration |
+
+## Why Graft?
+
+Multi-agent systems waste tokens passing full context between agents. Graft fixes this:
+
+- **Edge transforms** extract only what the next agent needs (`select`, `drop`, `compact`, `filter`)
+- **Compile-time token analysis** catches budget overruns before you spend API credits
+- **Typed output schemas** enforce structured JSON communication between agents
+- **Explicit `reads`** declarations prevent context leaks — the compiler verifies scope
+
+## Language Features
+
+### Contexts and Nodes
+
+```graft
+context TaskSpec(max_tokens: 1k) {
+  description: String
+  criteria: List<String>
+}
+
+node Analyzer(model: sonnet, budget: 5k/2k) {
+  reads: [TaskSpec]
+  tools: [file_read, terminal]
+  on_failure: retry(2)
+  produces AnalysisResult {
+    issues: List<Issue { file: FilePath, severity: enum(low, medium, high) }>
+    risk_score: Float(0..1)
+  }
+}
+```
+
+### Edge Transforms
+
+```graft
+edge Analyzer -> Reviewer
+  | filter(issues, severity >= medium)
+  | drop(reasoning_trace)
+  | compact
+```
+
+### Flow Control
+
+```graft
+graph Pipeline(input: TaskSpec, output: Report, budget: 35k) {
+  Planner
+  -> parallel { SecurityReviewer  PerformanceReviewer  StyleReviewer }
+  -> Aggregator -> done
+}
+```
+
+Also supports: `foreach`, `let` variables with expressions, parameterized sub-graphs, conditional edge routing.
+
+### Imports and Memory
+
+```graft
+import { UserMessage, SystemConfig } from "./shared.gft"
+
+memory ConversationLog(max_tokens: 2k, storage: file) {
+  turns: List<Turn { role: String, content: String }>
+  summary: Optional<String>
+}
+
+node Responder(model: sonnet, budget: 4k/2k) {
+  reads: [UserMessage, SystemConfig, ConversationLog]
+  writes: [ConversationLog.turns]
+  produces Response { reply: String }
+}
+```
+
+### Expressions
+
+```graft
+A -> let score = A.risk_score * 2
+   -> let label = "Found ${len(A.items)} items"
+   -> let safe = score >= 50 && score <= 100
+   -> let fallback = A.name ?? "unknown"
+   -> B -> done
+```
+
+Supported: arithmetic (`+`, `-`, `*`, `/`, `%`), comparison (`>`, `>=`, `==`, `!=`), logical (`&&`, `||`), null coalescing (`??`), string interpolation, builtins (`len`, `max`, `min`, `abs`, `round`, `keys`, `str`).
+
+### Type System
+
+```
+String, Int, Float, Float(0..1), Bool       // primitives
+List<T>, Map<K, V>, Optional<T>             // collections
+TokenBounded<String, 100>                   // token-bounded types
+enum(low, medium, high)                     // inline enums
+Issue { file: FilePath, severity: ... }     // inline structs
+```
+
+## CLI
+
+```bash
+graft compile <file.gft> [--out-dir <dir>]   # Compile to .claude/ structure
+graft check <file.gft>                       # Parse + analyze only
+graft run <file.gft> --input <json> [--dry-run] [--verbose]  # Compile and execute
+graft init <name>                            # Scaffold a new project
+```
+
+## Editor Support
+
+### VS Code
+
+The [Graft VS Code extension](editors/vscode/) provides:
+- Syntax highlighting (TextMate grammar)
+- Real-time diagnostics
+- Hover information (types, token budgets)
+- Go-to-definition, find references, rename
+- Completions (keywords, declarations, imports)
+- Code actions (auto-import)
+- Document symbols
+
+## Programmatic API
+
+```typescript
+import { compileToProgram, compile } from '@graft-lang/graft/compiler';
+import { Executor } from '@graft-lang/graft/runtime';
+import type { Program, GraftErrorCode } from '@graft-lang/graft/types';
+
+const result = compileToProgram(source, 'pipeline.gft');
+if (result.success) {
+  console.log(`Parsed ${result.program.nodes.length} nodes`);
+}
+```
+
+## Development
+
+```bash
+git clone https://github.com/JSLEEKR/graft.git
+cd graft && npm install
+npm run build         # Compile TypeScript
+npm test              # Run all 1,344 tests
+```
+
+## Version History
+
+| Version | Highlights |
+|---------|-----------|
+| **v5.3** | Parallel codegen test coverage, hook entry merging |
+| **v5.2** | Parallel→sequential edge transforms, agent input overrides, graceful hooks |
+| **v5.1** | Claude Code compatibility, `graft init`, CI/CD, README rewrite |
+| **v5.0** | Condition-to-Expr AST unification, strict equality, codegen expression display |
+| **v4.9** | Codegen expression display |
+| **v4.8** | LSP expression intelligence — hover, go-to-def, completions |
+| **v4.7** | Null coalescing (`??`), runtime expression hardening |
+| **v4.6** | Logical operators (`&&`, `||`), conditional type warnings |
+| **v4.5** | Comparison operators, conditional expressions |
+| **v4.4** | String interpolation, expression extraction |
+| **v4.0** | Variables, expressions, graph parameters, graph calls |
+| **v3.0** | Pluggable codegen backends, field-level writes, failure strategies |
+| **v2.0** | Import system, persistent memory |
+| **v1.0** | Full compiler pipeline, CLI |
+
+See [CHANGELOG.md](CHANGELOG.md) for full details.
+
+## License
+
+MIT

package/dist/analyzer/estimator.d.ts

@@ -0,0 +1,33 @@
+import { Program } from '../parser/ast.js';
+import { GraftError } from '../errors/diagnostics.js';
+import { ProgramIndex } from '../program-index.js';
+export interface NodeTokenReport {
+    name: string;
+    estimatedIn: number;
+    estimatedOut: number;
+}
+export interface TokenReport {
+    graphName: string;
+    budget: number;
+    bestCase: number;
+    worstCase: number;
+    nodes: NodeTokenReport[];
+    warnings: GraftError[];
+}
+export declare class TokenEstimator {
+    private program;
+    private index;
+    private nodeMap;
+    private edgeMap;
+    private conditionalEdges;
+    constructor(program: Program, index?: ProgramIndex);
+    estimate(): TokenReport;
+    private collectNodeReports;
+    private computeFlowCosts;
+    private getConditionalBranchCosts;
+    private getNodeCost;
+    private getEstimatedIn;
+    private applyTransformReductions;
+    private getRetryMultiplier;
+    private getFallbackCost;
+}

package/dist/analyzer/estimator.js

@@ -0,0 +1,273 @@
+import { GraftError } from '../errors/diagnostics.js';
+import { PARTIAL_FIELD_FACTOR, MAX_CONDITIONAL_HOPS } from '../constants.js';
+import { ProgramIndex } from '../program-index.js';
+export class TokenEstimator {
+    program;
+    index;
+    nodeMap;
+    edgeMap; // "source->target" key
+    conditionalEdges; // source -> branches
+    constructor(program, index) {
+        this.program = program;
+        this.index = index ?? new ProgramIndex(program);
+        this.nodeMap = this.index.nodeMap;
+        this.edgeMap = new Map();
+        this.conditionalEdges = new Map();
+        for (const edge of program.edges) {
+            if (edge.target.kind === 'direct') {
+                this.edgeMap.set(`${edge.source}->${edge.target.node}`, edge);
+            }
+            else {
+                this.conditionalEdges.set(edge.source, edge.target.branches);
+            }
+        }
+    }
+    estimate() {
+        const graph = this.program.graphs[0]; // v1: single graph
+        if (!graph) {
+            return { graphName: '', budget: 0, bestCase: 0, worstCase: 0, nodes: [], warnings: [] };
+        }
+        const warnings = [];
+        const nodeReports = [];
+        // Populate node reports (for display)
+        this.collectNodeReports(graph.flow, nodeReports, warnings);
+        // Compute best/worst case costs
+        const { best, worst } = this.computeFlowCosts(graph.flow, warnings);
+        const bestCase = best;
+        const worstCase = worst;
+        if (worstCase > graph.budget) {
+            warnings.push(new GraftError(`Worst-case token usage (${worstCase}) exceeds budget (${graph.budget})`, graph.location, 'warning', 'BUDGET_EXCEEDED'));
+        }
+        return {
+            graphName: graph.name,
+            budget: graph.budget,
+            bestCase,
+            worstCase,
+            nodes: nodeReports,
+            warnings,
+        };
+    }
+    collectNodeReports(steps, reports, warnings) {
+        for (const step of steps) {
+            switch (step.kind) {
+                case 'node': {
+                    const node = this.nodeMap.get(step.name);
+                    if (!node)
+                        break;
+                    const estimatedIn = this.getEstimatedIn(step.name, node);
+                    if (estimatedIn > node.budgetIn) {
+                        warnings.push(new GraftError(`Node '${step.name}' estimated input (${estimatedIn}) exceeds budgetIn (${node.budgetIn})`, node.location, 'warning', 'BUDGET_NODE_EXCEEDED'));
+                    }
+                    reports.push({ name: step.name, estimatedIn, estimatedOut: node.budgetOut });
+                    break;
+                }
+                case 'parallel':
+                    for (const branchName of step.branches) {
+                        const node = this.nodeMap.get(branchName);
+                        if (!node)
+                            continue;
+                        const estimatedIn = this.getEstimatedIn(branchName, node);
+                        if (estimatedIn > node.budgetIn) {
+                            warnings.push(new GraftError(`Node '${branchName}' estimated input (${estimatedIn}) exceeds budgetIn (${node.budgetIn})`, node.location, 'warning', 'BUDGET_NODE_EXCEEDED'));
+                        }
+                        reports.push({ name: branchName, estimatedIn, estimatedOut: node.budgetOut });
+                    }
+                    break;
+                case 'foreach':
+                    this.collectNodeReports(step.body, reports, warnings);
+                    break;
+                case 'let':
+                    // Let bindings have no token cost
+                    break;
+                case 'graph_call': {
+                    // Recurse into called graph's flow for node reports
+                    const calledGraph = this.index.graphMap.get(step.name);
+                    if (calledGraph) {
+                        this.collectNodeReports(calledGraph.flow, reports, warnings);
+                    }
+                    break;
+                }
+                default: {
+                    const _exhaustive = step;
+                    throw new Error(`Unhandled FlowNode kind: ${_exhaustive.kind}`);
+                }
+            }
+        }
+    }
+    computeFlowCosts(steps, warnings) {
+        let best = 0;
+        let worst = 0;
+        for (const step of steps) {
+            switch (step.kind) {
+                case 'node': {
+                    const node = this.nodeMap.get(step.name);
+                    if (!node)
+                        break;
+                    const cost = this.getNodeCost(step.name, node);
+                    const retryMul = this.getRetryMultiplier(node);
+                    best += cost;
+                    worst += cost * retryMul + this.getFallbackCost(node);
+                    // Add conditional edge branch costs (multi-hop recursive)
+                    const branchCosts = this.getConditionalBranchCosts(step.name, warnings, new Set([step.name]), 0);
+                    best += branchCosts.best;
+                    worst += branchCosts.worst;
+                    break;
+                }
+                case 'parallel': {
+                    // Parallel: all branches run. Total tokens = sum of all branches.
+                    for (const branchName of step.branches) {
+                        const node = this.nodeMap.get(branchName);
+                        if (!node)
+                            continue;
+                        const cost = this.getNodeCost(branchName, node);
+                        const retryMul = this.getRetryMultiplier(node);
+                        best += cost;
+                        worst += cost * retryMul + this.getFallbackCost(node);
+                    }
+                    break;
+                }
+                case 'foreach': {
+                    // Foreach: body runs up to maxIterations times.
+                    // Best case = 1 iteration. Worst case = maxIterations iterations.
+                    const bodyCosts = this.computeFlowCosts(step.body, warnings);
+                    best += bodyCosts.best * 1;
+                    worst += bodyCosts.worst * step.maxIterations;
+                    break;
+                }
+                case 'let':
+                    // Let bindings have zero token cost
+                    break;
+                case 'graph_call': {
+                    // Graph call cost = called graph's flow cost
+                    const calledGraph = this.index.graphMap.get(step.name);
+                    if (calledGraph) {
+                        const subCosts = this.computeFlowCosts(calledGraph.flow, warnings);
+                        best += subCosts.best;
+                        worst += subCosts.worst;
+                    }
+                    break;
+                }
+                default: {
+                    const _exhaustive = step;
+                    throw new Error(`Unhandled FlowNode kind: ${_exhaustive.kind}`);
+                }
+            }
+        }
+        return { best, worst };
+    }
+    getConditionalBranchCosts(source, warnings, visited, depth) {
+        const branches = this.conditionalEdges.get(source);
+        if (!branches)
+            return { best: 0, worst: 0 };
+        if (depth >= MAX_CONDITIONAL_HOPS) {
+            warnings.push(new GraftError(`Conditional chain from '${source}' exceeded maximum depth of ${MAX_CONDITIONAL_HOPS}`, { line: 0, column: 0, offset: 0 }, 'warning', 'BUDGET_CHAIN_DEPTH'));
+            return { best: 0, worst: 0 };
+        }
+        const branchBestCosts = [];
+        const branchWorstCosts = [];
+        for (const branch of branches) {
+            if (branch.target === 'done') {
+                branchBestCosts.push(0);
+                branchWorstCosts.push(0);
+                continue;
+            }
+            if (visited.has(branch.target)) {
+                // Cycle detected
+                warnings.push(new GraftError(`Conditional estimation cycle detected: ${[...visited, branch.target].join(' -> ')}`, { line: 0, column: 0, offset: 0 }, 'warning', 'BUDGET_CHAIN_CYCLE'));
+                branchBestCosts.push(0);
+                branchWorstCosts.push(0);
+                continue;
+            }
+            const node = this.nodeMap.get(branch.target);
+            if (!node)
+                continue; // unknown target, skip
+            const cost = this.getNodeCost(branch.target, node);
+            const retryMul = this.getRetryMultiplier(node);
+            // Per-branch visited set copy (handles diamonds correctly)
+            const branchVisited = new Set(visited);
+            branchVisited.add(branch.target);
+            const chainCosts = this.getConditionalBranchCosts(branch.target, warnings, branchVisited, depth + 1);
+            branchBestCosts.push(cost + chainCosts.best);
+            branchWorstCosts.push(cost * retryMul + chainCosts.worst);
+        }
+        if (branchBestCosts.length === 0)
+            return { best: 0, worst: 0 };
+        return { best: Math.min(...branchBestCosts), worst: Math.max(...branchWorstCosts) };
+    }
+    getNodeCost(nodeName, node) {
+        return this.getEstimatedIn(nodeName, node) + node.budgetOut;
+    }
+    getEstimatedIn(nodeName, node) {
+        let estimatedIn = 0;
+        for (const ref of node.reads) {
+            // If reading a context
+            const ctx = this.index.contextMap.get(ref.context);
+            if (ctx) {
+                estimatedIn += ref.field ? Math.floor(ctx.maxTokens * Math.min(PARTIAL_FIELD_FACTOR * ref.field.length, 1.0)) : ctx.maxTokens;
+                continue;
+            }
+            // If reading a memory
+            const mem = this.index.memoryMap.get(ref.context);
+            if (mem) {
+                estimatedIn += ref.field ? Math.floor(mem.maxTokens * Math.min(PARTIAL_FIELD_FACTOR * ref.field.length, 1.0)) : mem.maxTokens;
+                continue;
+            }
+            // If reading a produces output from upstream node
+            const sourceNode = this.index.producesNodeMap.get(ref.context);
+            if (sourceNode) {
+                let upstreamTokens = sourceNode.budgetOut;
+                // Check for edge transform reductions
+                const edgeKey = `${sourceNode.name}->${nodeName}`;
+                const edge = this.edgeMap.get(edgeKey);
+                if (edge) {
+                    upstreamTokens = this.applyTransformReductions(upstreamTokens, edge.transforms);
+                }
+                estimatedIn += ref.field ? Math.floor(upstreamTokens * Math.min(PARTIAL_FIELD_FACTOR * ref.field.length, 1.0)) : upstreamTokens;
+            }
+        }
+        return estimatedIn;
+    }
+    applyTransformReductions(tokens, transforms) {
+        let result = tokens;
+        for (const t of transforms) {
+            switch (t.type) {
+                case 'select':
+                    result = Math.floor(result * Math.min(PARTIAL_FIELD_FACTOR * t.fields.length, 1.0));
+                    break;
+                case 'filter':
+                    result = Math.floor(result * 0.5); // filter reduces ~50%
+                    break;
+                case 'drop':
+                    result = Math.floor(result * 0.85); // drop one field ~15% savings
+                    break;
+                case 'compact':
+                    result = Math.floor(result * 0.7); // compact ~30% reduction
+                    break;
+                case 'truncate':
+                    result = Math.min(result, t.tokens);
+                    break;
+            }
+        }
+        return result;
+    }
+    getRetryMultiplier(node) {
+        if (!node.onFailure)
+            return 1;
+        switch (node.onFailure.type) {
+            case 'retry':
+                return 1 + node.onFailure.max;
+            case 'retry_then_fallback':
+                return 1 + node.onFailure.max;
+            default:
+                return 1;
+        }
+    }
+    getFallbackCost(node) {
+        if (!node.onFailure || node.onFailure.type !== 'retry_then_fallback')
+            return 0;
+        const fallbackNode = this.nodeMap.get(node.onFailure.node);
+        if (!fallbackNode)
+            return 0;
+        return this.getNodeCost(node.onFailure.node, fallbackNode);
+    }
+}

package/dist/analyzer/graph-checker.d.ts

@@ -0,0 +1,13 @@
+import { FlowNode, Expr, GraphArg, GraphDecl } from '../parser/ast.js';
+import { GraftError, SourceLocation } from '../errors/diagnostics.js';
+import { ProgramIndex } from '../program-index.js';
+export declare function checkVarCollision(name: string, graphName: string, location: SourceLocation, index: ProgramIndex, errors: GraftError[]): void;
+export declare function checkExprSources(expr: Expr, seenNodes: Set<string>, declaredVars: Set<string>, graphName: string, errors: GraftError[]): void;
+export declare function checkGraphCallArgs(args: GraphArg[], graphDecl: GraphDecl, seenNodes: Set<string>, declaredVars: Set<string>, graphName: string, location: SourceLocation, index: ProgramIndex, errors: GraftError[]): void;
+export declare function checkGraphRecursion(graphs: {
+    name: string;
+    flow: FlowNode[];
+    location: SourceLocation;
+}[], index: ProgramIndex, errors: GraftError[]): void;
+export declare function collectGraphCalls(nodes: FlowNode[], calls: Set<string>): void;
+export declare function checkLiteralParamType(value: string | number | boolean, type: 'Node' | 'Int' | 'String' | 'Bool'): boolean;