@jsleekr/graft 5.7.0

package/dist/constants.js

@@ -0,0 +1,13 @@
+export const MODEL_MAP = {
+    sonnet: 'claude-sonnet-4-20250514',
+    opus: 'claude-opus-4-20250514',
+    haiku: 'claude-haiku-4-5-20251001',
+};
+/** Fraction of tokens estimated for a single-field read (vs full context). */
+export const PARTIAL_FIELD_FACTOR = 0.3;
+/** Budget fraction at which to emit a warning. */
+export const BUDGET_WARNING_THRESHOLD = 0.8;
+/** Budget fraction at which to emit a critical warning. */
+export const BUDGET_CRITICAL_THRESHOLD = 0.9;
+/** Maximum depth for conditional chain traversal in both estimation and runtime. */
+export const MAX_CONDITIONAL_HOPS = 10;

package/dist/errors/diagnostics.d.ts

@@ -0,0 +1,21 @@
+export interface SourceLocation {
+    line: number;
+    column: number;
+    offset: number;
+    length?: number;
+}
+export type ParseErrorCode = 'PARSE_UNEXPECTED_TOKEN' | 'PARSE_MISSING_FIELD';
+export type ScopeErrorCode = 'SCOPE_DUPLICATE_NAME' | 'SCOPE_UNDEFINED_REF' | 'SCOPE_FIELD_NOT_FOUND' | 'SCOPE_INVALID_WRITES' | 'SCOPE_INVALID_FOREACH' | 'SCOPE_PARALLEL_WRITES' | 'SCOPE_MAX_TOKENS_INVALID' | 'SCOPE_INVALID_FALLBACK' | 'SCOPE_FALLBACK_CYCLE' | 'SCOPE_BINDING_COLLISION' | 'SCOPE_VAR_COLLISION' | 'SCOPE_VAR_UNDECLARED' | 'SCOPE_VAR_ORDER' | 'SCOPE_GRAPH_RECURSION' | 'SCOPE_GRAPH_PARAM_MISSING' | 'SCOPE_GRAPH_PARAM_TYPE' | 'SCOPE_UNKNOWN_FUNCTION';
+export type TypeErrorCode = 'TYPE_FIELD_NOT_FOUND' | 'TYPE_SCHEMA_MISMATCH' | 'TYPE_WRITE_FIELD_OVERLAP' | 'TYPE_CONDITION_MISMATCH' | 'TYPE_EXPR_MISMATCH' | 'TYPE_VAR_CONDITION' | 'TYPE_FUNC_ARITY' | 'TYPE_CONDITIONAL_MISMATCH';
+export type BudgetErrorCode = 'BUDGET_EXCEEDED' | 'BUDGET_NODE_EXCEEDED' | 'BUDGET_CHAIN_CYCLE' | 'BUDGET_CHAIN_DEPTH';
+export type ImportErrorCode = 'IMPORT_CIRCULAR' | 'IMPORT_NOT_FOUND' | 'IMPORT_NAME_NOT_FOUND' | 'IMPORT_DUPLICATE_NAME' | 'IMPORT_INVALID_PATH' | 'IMPORT_PARSE_ERROR';
+export type GraphErrorCode = 'GRAPH_MISSING' | 'GRAPH_MULTIPLE';
+export type ConfigErrorCode = 'CONFIG_UNKNOWN_BACKEND';
+export type GraftErrorCode = ParseErrorCode | ScopeErrorCode | TypeErrorCode | BudgetErrorCode | ImportErrorCode | GraphErrorCode | ConfigErrorCode;
+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;
+}

package/dist/errors/diagnostics.js

@@ -0,0 +1,25 @@
+export class GraftError extends Error {
+    location;
+    severity;
+    code;
+    constructor(message, location, severity = 'error', code) {
+        super(message);
+        this.location = location;
+        this.severity = severity;
+        this.code = code;
+        this.name = 'GraftError';
+    }
+    format(source) {
+        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');
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,12 @@
+import { TokenReport } from './analyzer/estimator.js';
+import { Expr } from './parser/ast.js';
+export interface FormatOptions {
+    /** Include budget comparison on best/worst path lines */
+    showBudget?: boolean;
+}
+/**
+ * Format a TokenReport into human-readable lines for CLI output.
+ * Returns a single string with newlines.
+ */
+export declare function formatTokenReport(report: TokenReport, options?: FormatOptions): string;
+export declare function formatExpr(expr: Expr): string;

package/dist/format.js

@@ -0,0 +1,46 @@
+/**
+ * Format a TokenReport into human-readable lines for CLI output.
+ * Returns a single string with newlines.
+ */
+export function formatTokenReport(report, options) {
+    const lines = [];
+    const showBudget = options?.showBudget ?? false;
+    for (const node of report.nodes) {
+        lines.push(`    ${node.name.padEnd(20)} in ~${node.estimatedIn.toLocaleString('en-US').padStart(6)}  out ~${node.estimatedOut.toLocaleString('en-US').padStart(6)}`);
+    }
+    if (showBudget) {
+        const bestOk = report.bestCase <= report.budget;
+        const worstOk = report.worstCase <= report.budget;
+        lines.push(`    Best path:  ${report.bestCase.toLocaleString('en-US').padStart(8)} tokens ${bestOk ? '\u2713' : '\u2717'} ${bestOk ? 'within' : 'exceeds'} budget (${report.budget.toLocaleString('en-US')})`);
+        lines.push(`    Worst path: ${report.worstCase.toLocaleString('en-US').padStart(8)} tokens ${worstOk ? '\u2713' : '\u26A0'} ${worstOk ? 'within' : 'exceeds'} budget (${report.budget.toLocaleString('en-US')})`);
+    }
+    else {
+        lines.push(`    Best path:  ${report.bestCase.toLocaleString('en-US').padStart(8)} tokens`);
+        lines.push(`    Worst path: ${report.worstCase.toLocaleString('en-US').padStart(8)} tokens`);
+    }
+    return lines.join('\n');
+}
+export function formatExpr(expr) {
+    switch (expr.kind) {
+        case 'literal':
+            return typeof expr.value === 'string' ? `"${expr.value}"` : String(expr.value);
+        case 'field_access':
+            return expr.segments.join('.');
+        case 'binary':
+            return `${formatExpr(expr.left)} ${expr.op} ${formatExpr(expr.right)}`;
+        case 'unary':
+            return `${expr.op}${formatExpr(expr.operand)}`;
+        case 'group':
+            return `(${formatExpr(expr.inner)})`;
+        case 'call':
+            return `${expr.name}(${expr.args.map(formatExpr).join(', ')})`;
+        case 'template':
+            return '"' + expr.parts.map(p => p.kind === 'text' ? p.value : `\${${formatExpr(p.value)}}`).join('') + '"';
+        case 'conditional':
+            return `if ${formatExpr(expr.condition)} then ${formatExpr(expr.consequent)} else ${formatExpr(expr.alternate)}`;
+        default: {
+            const _exhaustive = expr;
+            return _exhaustive;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { compile, compileAndWrite } from './compiler.js';
+import { VERSION } from './version.js';
+import { formatTokenReport } from './format.js';
+const KNOWN_BACKENDS = new Set(['claude']);
+const program = new Command();
+program
+    .name('graft')
+    .description('Graft compiler — graph-native language for AI agent harness engineering')
+    .version(VERSION);
+program
+    .command('compile')
+    .description('Compile .gft source to Claude Code harness structure')
+    .argument('<file>', '.gft source file')
+    .option('--out-dir <dir>', 'output directory', '.')
+    .option('--backend <name>', 'codegen backend', 'claude')
+    .action((file, opts) => {
+    if (!KNOWN_BACKENDS.has(opts.backend)) {
+        console.error(`Error: unknown backend '${opts.backend}'. Available: ${[...KNOWN_BACKENDS].join(', ')}`);
+        process.exit(1);
+    }
+    const source = readSource(file);
+    let result;
+    try {
+        result = compileAndWrite(source, path.resolve(file), path.resolve(opts.outDir));
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    if (!result.success) {
+        console.error('\n✗ Compilation failed:\n');
+        for (const err of result.errors) {
+            console.error(err.format(source));
+            console.error('');
+        }
+        process.exit(1);
+    }
+    console.log('\n✓ Parse OK');
+    console.log('✓ Scope check OK');
+    console.log('✓ Type check OK');
+    if (result.report) {
+        console.log('✓ Token analysis:');
+        console.log(formatTokenReport(result.report, { showBudget: true }));
+    }
+    for (const w of result.warnings) {
+        console.log(`\n⚠ ${w.message}`);
+    }
+    if (result.files) {
+        console.log('\nGenerated:');
+        for (const f of result.files) {
+            console.log(`  ${f.path}`);
+        }
+    }
+    console.log('');
+});
+program
+    .command('check')
+    .description('Validate .gft source without writing files')
+    .argument('<file>', '.gft source file')
+    .action((file) => {
+    const source = readSource(file);
+    const result = compile(source, path.resolve(file));
+    if (!result.success) {
+        console.error('\n✗ Check failed:\n');
+        for (const err of result.errors) {
+            console.error(err.format(source));
+            console.error('');
+        }
+        process.exit(1);
+    }
+    console.log('\n✓ Parse OK');
+    console.log('✓ Scope check OK');
+    console.log('✓ Type check OK');
+    if (result.report) {
+        console.log('✓ Token analysis:');
+        console.log(formatTokenReport(result.report));
+    }
+    for (const w of result.warnings) {
+        console.log(`\n⚠ ${w.message}`);
+    }
+    console.log('');
+});
+program
+    .command('run')
+    .description('Compile and execute a .gft pipeline')
+    .argument('<file>', '.gft source file')
+    .option('--input <file>', 'input JSON file')
+    .option('--dry-run', 'simulate execution without spawning subprocesses')
+    .option('--verbose', 'print execution details')
+    .option('--timeout <seconds>', 'subprocess timeout in seconds', '300')
+    .option('--work-dir <dir>', 'working directory for execution')
+    .action(async (file, opts) => {
+    const { run } = await import('./runner.js');
+    const result = await run({
+        sourceFile: file,
+        inputFile: opts.input,
+        workDir: opts.workDir,
+        dryRun: opts.dryRun,
+        verbose: opts.verbose,
+        timeoutMs: parseInt(opts.timeout, 10) * 1000,
+    });
+    if (!result.success) {
+        console.error('\nExecution failed:');
+        for (const err of result.errors)
+            console.error(`  ${err}`);
+        process.exit(1);
+    }
+    console.log(`\nGraph '${result.graph}' completed in ${result.totalDurationMs}ms`);
+    console.log(`Nodes executed: ${result.nodeResults.length}`);
+    for (const nr of result.nodeResults) {
+        const status = nr.success ? 'OK' : 'FAILED';
+        console.log(`  ${nr.node.padEnd(20)} ${status.padEnd(8)} ${nr.durationMs}ms`);
+    }
+    if (result.finalOutput !== null) {
+        console.log('\nFinal output:');
+        console.log(JSON.stringify(result.finalOutput, null, 2));
+    }
+    console.log('');
+});
+program
+    .command('init')
+    .description('Scaffold a new Graft project')
+    .argument('<name>', 'project name')
+    .action((name) => {
+    const dir = path.resolve(name);
+    if (fs.existsSync(dir)) {
+        console.error(`Error: directory '${name}' already exists`);
+        process.exit(1);
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    const baseName = path.basename(name);
+    const safeName = baseName.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_+|_+$/g, '') || 'pipeline';
+    fs.writeFileSync(path.join(dir, 'pipeline.gft'), `// ${safeName} — a simple two-node pipeline
+
+context Input(max_tokens: 500) {
+  question: String
+}
+
+node Analyst(model: sonnet, budget: 4k/2k) {
+  reads: [Input]
+  produces Analysis {
+    answer: String
+    confidence: Float(0..1)
+  }
+}
+
+node Reviewer(model: haiku, budget: 2k/1k) {
+  reads: [Analysis]
+  produces Output {
+    final_answer: String
+    approved: Bool
+  }
+}
+
+edge Analyst -> Reviewer | select(answer, confidence) | compact
+
+graph ${safeName}(input: Input, output: Output, budget: 10k) {
+  Analyst -> Reviewer -> done
+}
+`);
+    console.log(`\nCreated ${name}/`);
+    console.log(`  pipeline.gft`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${name}`);
+    console.log(`  graft compile pipeline.gft`);
+    console.log(`  # Open in Claude Code to run the pipeline`);
+    console.log('');
+});
+function readSource(file) {
+    const resolved = path.resolve(file);
+    if (!fs.existsSync(resolved)) {
+        console.error(`Error: file not found: ${resolved}`);
+        process.exit(1);
+    }
+    return fs.readFileSync(resolved, 'utf-8');
+}
+program.parse();

package/dist/lexer/lexer.d.ts

@@ -0,0 +1,23 @@
+import { Token } from './tokens.js';
+export declare class Lexer {
+    private readonly source;
+    private pos;
+    private line;
+    private column;
+    private tokens;
+    constructor(source: string);
+    tokenize(): Token[];
+    private skipWhitespace;
+    private skipLineComment;
+    private skipBlockComment;
+    private readString;
+    private readNumber;
+    private readIdentifierOrKeyword;
+    private readSymbol;
+    private matchTwoChar;
+    private peek;
+    private location;
+    private isDigit;
+    private isAlpha;
+    private isAlphaNumeric;
+}

package/dist/lexer/lexer.js

@@ -0,0 +1,268 @@
+import { TokenType, KEYWORDS } from './tokens.js';
+import { GraftError } from '../errors/diagnostics.js';
+const SINGLE_CHAR = {
+    '{': TokenType.LBrace,
+    '}': TokenType.RBrace,
+    '(': TokenType.LParen,
+    ')': TokenType.RParen,
+    '[': TokenType.LBracket,
+    ']': TokenType.RBracket,
+    ':': TokenType.Colon,
+    ',': TokenType.Comma,
+    '.': TokenType.Dot,
+    '|': TokenType.Pipe,
+    '/': TokenType.Slash,
+    '*': TokenType.Star,
+    '%': TokenType.Percent,
+    '+': TokenType.Plus,
+    '-': TokenType.Minus,
+    '!': TokenType.Bang,
+    '=': TokenType.Equals,
+    '>': TokenType.Greater,
+    '<': TokenType.Less,
+};
+export class Lexer {
+    source;
+    pos = 0;
+    line = 1;
+    column = 1;
+    tokens = [];
+    constructor(source) {
+        this.source = source;
+    }
+    tokenize() {
+        this.tokens = [];
+        while (this.pos < this.source.length) {
+            this.skipWhitespace();
+            if (this.pos >= this.source.length)
+                break;
+            const ch = this.source[this.pos];
+            // Comments
+            if (ch === '/' && this.peek(1) === '/') {
+                this.skipLineComment();
+                continue;
+            }
+            if (ch === '/' && this.peek(1) === '*') {
+                this.skipBlockComment();
+                continue;
+            }
+            // String literals
+            if (ch === '"') {
+                this.readString();
+                continue;
+            }
+            // Numbers (integer, k-integer, float)
+            if (this.isDigit(ch)) {
+                this.readNumber();
+                continue;
+            }
+            // Identifiers and keywords
+            if (this.isAlpha(ch)) {
+                this.readIdentifierOrKeyword();
+                continue;
+            }
+            // Symbols
+            if (this.readSymbol()) {
+                continue;
+            }
+            throw new GraftError(`Unexpected character '${ch}'`, this.location());
+        }
+        this.tokens.push({ type: TokenType.EOF, value: '', location: this.location() });
+        return this.tokens;
+    }
+    skipWhitespace() {
+        while (this.pos < this.source.length) {
+            const ch = this.source[this.pos];
+            if (ch === '\n') {
+                this.pos++;
+                this.line++;
+                this.column = 1;
+            }
+            else if (ch === '\r') {
+                this.pos++;
+                if (this.pos < this.source.length && this.source[this.pos] === '\n') {
+                    this.pos++;
+                }
+                this.line++;
+                this.column = 1;
+            }
+            else if (ch === ' ' || ch === '\t') {
+                this.pos++;
+                this.column++;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    skipLineComment() {
+        this.pos += 2;
+        this.column += 2;
+        while (this.pos < this.source.length && this.source[this.pos] !== '\n') {
+            this.pos++;
+            this.column++;
+        }
+    }
+    skipBlockComment() {
+        const loc = this.location();
+        this.pos += 2;
+        this.column += 2;
+        while (this.pos < this.source.length) {
+            if (this.source[this.pos] === '*' && this.peek(1) === '/') {
+                this.pos += 2;
+                this.column += 2;
+                return;
+            }
+            if (this.source[this.pos] === '\n') {
+                this.line++;
+                this.column = 1;
+                this.pos++;
+            }
+            else {
+                this.pos++;
+                this.column++;
+            }
+        }
+        throw new GraftError('Unterminated block comment', loc);
+    }
+    readString() {
+        const loc = this.location();
+        this.pos++;
+        this.column++;
+        let value = '';
+        let hasInterpolation = false;
+        while (this.pos < this.source.length && this.source[this.pos] !== '"') {
+            if (this.source[this.pos] === '\n') {
+                throw new GraftError('Unterminated string literal', loc);
+            }
+            // Check for escape: \${ produces literal ${
+            if (this.source[this.pos] === '\\' && this.pos + 1 < this.source.length && this.source[this.pos + 1] === '$' && this.pos + 2 < this.source.length && this.source[this.pos + 2] === '{') {
+                value += '${';
+                this.pos += 3;
+                this.column += 3;
+                continue;
+            }
+            // Check for interpolation: ${ marks this as a template string
+            if (this.source[this.pos] === '$' && this.pos + 1 < this.source.length && this.source[this.pos + 1] === '{') {
+                hasInterpolation = true;
+            }
+            value += this.source[this.pos];
+            this.pos++;
+            this.column++;
+        }
+        if (this.pos >= this.source.length) {
+            throw new GraftError('Unterminated string literal', loc);
+        }
+        this.pos++;
+        this.column++;
+        const type = hasInterpolation ? TokenType.TemplateString : TokenType.StringLiteral;
+        this.tokens.push({ type, value, location: { ...loc, length: value.length + 2 } });
+    }
+    readNumber() {
+        const loc = this.location();
+        let value = '';
+        while (this.pos < this.source.length && this.isDigit(this.source[this.pos])) {
+            value += this.source[this.pos];
+            this.pos++;
+            this.column++;
+        }
+        // Check for k-suffix
+        if (this.pos < this.source.length && this.source[this.pos] === 'k') {
+            value += 'k';
+            this.pos++;
+            this.column++;
+            this.tokens.push({ type: TokenType.KIntegerLiteral, value, location: { ...loc, length: value.length } });
+            return;
+        }
+        // Check for float (requires digit after dot; dot-dot is range operator)
+        if (this.pos < this.source.length &&
+            this.source[this.pos] === '.' &&
+            this.peek(1) !== undefined &&
+            this.isDigit(this.peek(1))) {
+            value += '.';
+            this.pos++;
+            this.column++;
+            while (this.pos < this.source.length && this.isDigit(this.source[this.pos])) {
+                value += this.source[this.pos];
+                this.pos++;
+                this.column++;
+            }
+            this.tokens.push({ type: TokenType.FloatLiteral, value, location: { ...loc, length: value.length } });
+            return;
+        }
+        this.tokens.push({ type: TokenType.IntegerLiteral, value, location: { ...loc, length: value.length } });
+    }
+    readIdentifierOrKeyword() {
+        const loc = this.location();
+        let value = '';
+        while (this.pos < this.source.length && this.isAlphaNumeric(this.source[this.pos])) {
+            value += this.source[this.pos];
+            this.pos++;
+            this.column++;
+        }
+        const keywordType = KEYWORDS[value];
+        this.tokens.push({
+            type: keywordType ?? TokenType.Identifier,
+            value,
+            location: { ...loc, length: value.length },
+        });
+    }
+    readSymbol() {
+        const loc = this.location();
+        const ch = this.source[this.pos];
+        const next = this.peek(1);
+        // Two-character symbols first (maximal munch)
+        const twoChar = this.matchTwoChar(ch, next);
+        if (twoChar) {
+            this.tokens.push({ type: twoChar[0], value: twoChar[1], location: { ...loc, length: 2 } });
+            this.pos += 2;
+            this.column += 2;
+            return true;
+        }
+        // Single-character symbols
+        const singleType = SINGLE_CHAR[ch];
+        if (singleType !== undefined) {
+            this.tokens.push({ type: singleType, value: ch, location: { ...loc, length: 1 } });
+            this.pos++;
+            this.column++;
+            return true;
+        }
+        return false;
+    }
+    matchTwoChar(ch, next) {
+        if (ch === '-' && next === '>')
+            return [TokenType.Arrow, '->'];
+        if (ch === '.' && next === '.')
+            return [TokenType.DotDot, '..'];
+        if (ch === '>' && next === '=')
+            return [TokenType.GreaterEqual, '>='];
+        if (ch === '<' && next === '=')
+            return [TokenType.LessEqual, '<='];
+        if (ch === '=' && next === '=')
+            return [TokenType.EqualEqual, '=='];
+        if (ch === '!' && next === '=')
+            return [TokenType.BangEqual, '!='];
+        if (ch === '&' && next === '&')
+            return [TokenType.AmpAmp, '&&'];
+        if (ch === '|' && next === '|')
+            return [TokenType.PipePipe, '||'];
+        if (ch === '?' && next === '?')
+            return [TokenType.QuestionQuestion, '??'];
+        return null;
+    }
+    peek(offset) {
+        return this.source[this.pos + offset];
+    }
+    location() {
+        return { line: this.line, column: this.column, offset: this.pos };
+    }
+    isDigit(ch) {
+        return ch >= '0' && ch <= '9';
+    }
+    isAlpha(ch) {
+        return (ch >= 'a' && ch <= 'z') || (ch >= 'A' && ch <= 'Z') || ch === '_';
+    }
+    isAlphaNumeric(ch) {
+        return this.isAlpha(ch) || this.isDigit(ch);
+    }
+}