@jsleekr/graft 5.8.0 → 6.0.0

package/dist/runtime/result-validator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Runtime result validator — checks pipeline output against .gft schema.
+ */
+import { Program } from '../parser/ast.js';
+import { RunResult } from './executor.js';
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+export interface Check {
+    status: CheckStatus;
+    category: 'schema' | 'type' | 'range' | 'empty' | 'budget';
+    node: string;
+    field?: string;
+    message: string;
+}
+export interface QualityReport {
+    score: number;
+    checks: Check[];
+    passed: number;
+    warned: number;
+    failed: number;
+}
+/**
+ * Validate a RunResult against the Program's produces schemas.
+ */
+export declare function validateResult(result: RunResult, program: Program): QualityReport;
+/**
+ * Format a QualityReport for human-readable output.
+ */
+export declare function formatQualityReport(report: QualityReport): string;

package/dist/runtime/result-validator.js

@@ -0,0 +1,129 @@
+import { ProgramIndex } from '../program-index.js';
+/**
+ * Validate a RunResult against the Program's produces schemas.
+ */
+export function validateResult(result, program) {
+    const checks = [];
+    const index = new ProgramIndex(program);
+    // Validate each node's output
+    for (const nr of result.nodeResults) {
+        if (!nr.success) {
+            checks.push({ status: 'fail', category: 'schema', node: nr.node, message: `Node failed: ${nr.error ?? 'unknown error'}` });
+            continue;
+        }
+        const nodeDecl = index.nodeMap.get(nr.node);
+        if (!nodeDecl)
+            continue;
+        validateNodeOutput(nr, nodeDecl, checks);
+    }
+    // Budget check
+    if (result.tokenUsage) {
+        const { fraction } = result.tokenUsage;
+        if (fraction > 0.95) {
+            checks.push({ status: 'fail', category: 'budget', node: '*', message: `Token budget nearly exhausted: ${Math.round(fraction * 100)}%` });
+        }
+        else if (fraction > 0.8) {
+            checks.push({ status: 'warn', category: 'budget', node: '*', message: `Token budget high: ${Math.round(fraction * 100)}%` });
+        }
+        else {
+            checks.push({ status: 'pass', category: 'budget', node: '*', message: `Token budget OK: ${Math.round(fraction * 100)}%` });
+        }
+    }
+    const passed = checks.filter(c => c.status === 'pass').length;
+    const warned = checks.filter(c => c.status === 'warn').length;
+    const failed = checks.filter(c => c.status === 'fail').length;
+    const total = checks.length;
+    const score = total > 0 ? passed / total : 1.0;
+    return { score, checks, passed, warned, failed };
+}
+function validateNodeOutput(nr, nodeDecl, checks) {
+    const output = nr.output;
+    if (output === null || output === undefined) {
+        checks.push({ status: 'fail', category: 'schema', node: nr.node, message: 'Output is null' });
+        return;
+    }
+    if (typeof output !== 'object' || Array.isArray(output)) {
+        checks.push({ status: 'fail', category: 'schema', node: nr.node, message: `Output is ${typeof output}, expected object` });
+        return;
+    }
+    const obj = output;
+    const fields = nodeDecl.produces.fields;
+    // Check each declared field
+    for (const field of fields) {
+        const value = obj[field.name];
+        // Schema: field exists?
+        if (value === undefined) {
+            checks.push({ status: 'fail', category: 'schema', node: nr.node, field: field.name, message: `Missing field: ${field.name}` });
+            continue;
+        }
+        // Type check
+        const typeCheck = checkType(value, field.type);
+        if (typeCheck !== null) {
+            checks.push({ status: 'fail', category: 'type', node: nr.node, field: field.name, message: typeCheck });
+            continue;
+        }
+        // Empty check
+        if (isEmpty(value)) {
+            checks.push({ status: 'warn', category: 'empty', node: nr.node, field: field.name, message: `Field '${field.name}' is empty` });
+            continue;
+        }
+        // Range check for Float(min..max)
+        if (field.type.kind === 'primitive_range' && typeof value === 'number') {
+            if (value < field.type.min || value > field.type.max) {
+                checks.push({
+                    status: 'fail', category: 'range', node: nr.node, field: field.name,
+                    message: `Value ${value} out of range [${field.type.min}..${field.type.max}]`,
+                });
+                continue;
+            }
+        }
+        checks.push({ status: 'pass', category: 'schema', node: nr.node, field: field.name, message: `${field.name} OK` });
+    }
+}
+function checkType(value, type) {
+    switch (type.kind) {
+        case 'primitive':
+            switch (type.name) {
+                case 'String': return typeof value === 'string' ? null : `Expected String, got ${typeof value}`;
+                case 'Int': return typeof value === 'number' && Number.isInteger(value) ? null : `Expected Int, got ${typeof value}`;
+                case 'Float': return typeof value === 'number' ? null : `Expected Float, got ${typeof value}`;
+                case 'Bool': return typeof value === 'boolean' ? null : `Expected Bool, got ${typeof value}`;
+                default: return null; // Unknown primitive, skip
+            }
+        case 'primitive_range':
+            return typeof value === 'number' ? null : `Expected Float, got ${typeof value}`;
+        case 'list':
+            return Array.isArray(value) ? null : `Expected List, got ${typeof value}`;
+        case 'map':
+            return (typeof value === 'object' && value !== null && !Array.isArray(value)) ? null : `Expected Map, got ${typeof value}`;
+        case 'optional':
+            return null; // null is valid for Optional
+        default:
+            return null; // Unknown type, skip
+    }
+}
+function isEmpty(value) {
+    if (value === null || value === undefined || value === '')
+        return true;
+    if (Array.isArray(value) && value.length === 0)
+        return true;
+    if (typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0)
+        return true;
+    return false;
+}
+/**
+ * Format a QualityReport for human-readable output.
+ */
+export function formatQualityReport(report) {
+    const lines = [];
+    lines.push('\u2500\u2500 Quality Check ' + '\u2500'.repeat(33));
+    for (const check of report.checks) {
+        const icon = check.status === 'pass' ? '\u2713' : check.status === 'warn' ? '\u26a0' : '\u2717';
+        const fieldStr = check.field ? ` ${check.node}.${check.field}` : '';
+        lines.push(`  ${icon} ${check.message}${fieldStr ? ` [${check.node}.${check.field}]` : ''}`);
+    }
+    lines.push('\u2500'.repeat(48));
+    const pct = Math.round(report.score * 100);
+    lines.push(`Quality: ${pct}% (${report.passed}/${report.passed + report.warned + report.failed} checks passed)`);
+    return lines.join('\n');
+}

package/dist/test-runner.d.ts

@@ -0,0 +1,33 @@
+import { ContextDecl, Field, TypeExpr } from './parser/ast.js';
+/**
+ * Generate minimal valid test data for a TypeExpr.
+ */
+export declare function generateTestValue(type: TypeExpr): unknown;
+/**
+ * Generate a minimal valid JSON object from a context declaration's field schema.
+ */
+export declare function generateTestInput(context: ContextDecl): Record<string, unknown>;
+/**
+ * Validate that an output object matches the expected field schema.
+ * Returns an array of error strings (empty if valid).
+ */
+export declare function validateOutput(output: unknown, fields: Field[], prefix?: string): string[];
+export interface TestInput {
+    source: string;
+    sourceFile: string;
+    input?: Record<string, unknown>;
+    verbose?: boolean;
+}
+export interface NodeTestResult {
+    node: string;
+    passed: boolean;
+    output: unknown;
+    validationErrors: string[];
+}
+export interface TestResult {
+    success: boolean;
+    inputUsed: Record<string, unknown>;
+    nodeResults: NodeTestResult[];
+    compileErrors: string[];
+}
+export declare function runTest(opts: TestInput): Promise<TestResult>;

package/dist/test-runner.js

@@ -0,0 +1,223 @@
+import { compileToProgram } from './compiler.js';
+import { ProgramIndex } from './program-index.js';
+import { generateMockOutput } from './runtime/prompt-builder.js';
+import { executeFlowNodes } from './runtime/flow-runner.js';
+// --- Test input generation ---
+/**
+ * Generate minimal valid test data for a TypeExpr.
+ */
+export function generateTestValue(type) {
+    switch (type.kind) {
+        case 'primitive':
+            switch (type.name) {
+                case 'String': return 'test';
+                case 'Int': return 1;
+                case 'Float': return 0.5;
+                case 'Bool': return true;
+            }
+            break;
+        case 'primitive_range':
+            return (type.min + type.max) / 2;
+        case 'list':
+            return [generateTestValue(type.element)];
+        case 'map':
+            return { [String(generateTestValue(type.key))]: generateTestValue(type.value) };
+        case 'optional':
+            return null;
+        case 'token_bounded':
+            return generateTestValue(type.inner);
+        case 'enum':
+            return type.values[0];
+        case 'struct':
+            return generateTestInput({ name: '', maxTokens: 0, fields: type.fields, location: { line: 0, column: 0, offset: 0 } });
+        case 'domain':
+            return `test.${type.name.toLowerCase()}`;
+        default: {
+            const _exhaustive = type;
+            return _exhaustive;
+        }
+    }
+}
+/**
+ * Generate a minimal valid JSON object from a context declaration's field schema.
+ */
+export function generateTestInput(context) {
+    const result = {};
+    for (const field of context.fields) {
+        result[field.name] = generateTestValue(field.type);
+    }
+    return result;
+}
+// --- Output validation ---
+/**
+ * Validate that an output object matches the expected field schema.
+ * Returns an array of error strings (empty if valid).
+ */
+export function validateOutput(output, fields, prefix = '') {
+    const errors = [];
+    if (output === null || output === undefined || typeof output !== 'object' || Array.isArray(output)) {
+        errors.push(`${prefix || 'output'}: expected object, got ${output === null ? 'null' : typeof output}`);
+        return errors;
+    }
+    const obj = output;
+    for (const field of fields) {
+        const path = prefix ? `${prefix}.${field.name}` : field.name;
+        if (!(field.name in obj)) {
+            // Optional fields are allowed to be missing
+            if (field.type.kind === 'optional')
+                continue;
+            errors.push(`${path}: missing required field`);
+            continue;
+        }
+        errors.push(...validateValue(obj[field.name], field.type, path));
+    }
+    return errors;
+}
+function validateValue(value, type, path) {
+    const errors = [];
+    switch (type.kind) {
+        case 'primitive':
+            switch (type.name) {
+                case 'String':
+                    if (typeof value !== 'string')
+                        errors.push(`${path}: expected string, got ${typeof value}`);
+                    break;
+                case 'Int':
+                    if (typeof value !== 'number' || !Number.isInteger(value))
+                        errors.push(`${path}: expected integer, got ${typeof value === 'number' ? 'float' : typeof value}`);
+                    break;
+                case 'Float':
+                    if (typeof value !== 'number')
+                        errors.push(`${path}: expected number, got ${typeof value}`);
+                    break;
+                case 'Bool':
+                    if (typeof value !== 'boolean')
+                        errors.push(`${path}: expected boolean, got ${typeof value}`);
+                    break;
+            }
+            break;
+        case 'primitive_range':
+            if (typeof value !== 'number') {
+                errors.push(`${path}: expected number, got ${typeof value}`);
+            }
+            else if (value < type.min || value > type.max) {
+                errors.push(`${path}: value ${value} out of range [${type.min}..${type.max}]`);
+            }
+            break;
+        case 'list':
+            if (!Array.isArray(value)) {
+                errors.push(`${path}: expected array, got ${typeof value}`);
+            }
+            else {
+                for (let i = 0; i < value.length; i++) {
+                    errors.push(...validateValue(value[i], type.element, `${path}[${i}]`));
+                }
+            }
+            break;
+        case 'map':
+            if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+                errors.push(`${path}: expected object (map), got ${typeof value}`);
+            }
+            break;
+        case 'optional':
+            if (value !== null && value !== undefined) {
+                errors.push(...validateValue(value, type.inner, path));
+            }
+            break;
+        case 'token_bounded':
+            errors.push(...validateValue(value, type.inner, path));
+            break;
+        case 'enum':
+            if (typeof value !== 'string' || !type.values.includes(value)) {
+                errors.push(`${path}: expected enum value (${type.values.join(', ')}), got ${JSON.stringify(value)}`);
+            }
+            break;
+        case 'struct':
+            errors.push(...validateOutput(value, type.fields, path));
+            break;
+        case 'domain':
+            if (typeof value !== 'string')
+                errors.push(`${path}: expected string (${type.name}), got ${typeof value}`);
+            break;
+    }
+    return errors;
+}
+export async function runTest(opts) {
+    // Compile the source
+    const compileResult = compileToProgram(opts.source, opts.sourceFile);
+    if (!compileResult.success || !compileResult.program) {
+        return {
+            success: false,
+            inputUsed: opts.input ?? {},
+            nodeResults: [],
+            compileErrors: compileResult.errors.map(e => e.message),
+        };
+    }
+    const program = compileResult.program;
+    const index = compileResult.index ?? new ProgramIndex(program);
+    if (program.graphs.length === 0) {
+        return {
+            success: false,
+            inputUsed: opts.input ?? {},
+            nodeResults: [],
+            compileErrors: ['No graph declaration found'],
+        };
+    }
+    const graph = program.graphs[0];
+    // Generate or use provided input
+    const inputContext = index.contextMap.get(graph.input);
+    const inputUsed = opts.input ?? (inputContext ? generateTestInput(inputContext) : {});
+    // Execute in dry-run mode
+    const outputs = new Map();
+    const nodeResults = [];
+    const executeNode = async (name) => {
+        const nodeDecl = index.nodeMap.get(name);
+        if (!nodeDecl) {
+            const nr = { node: name, passed: false, output: null, validationErrors: [`Node '${name}' not found`] };
+            nodeResults.push(nr);
+            return { node: name, output: null, durationMs: 0, success: false, error: `Node '${name}' not found` };
+        }
+        // Generate mock output
+        const mockOutput = generateMockOutput(nodeDecl);
+        outputs.set(nodeDecl.name, mockOutput);
+        outputs.set(nodeDecl.produces.name, mockOutput);
+        // Validate mock output against produces schema
+        const validationErrors = validateOutput(mockOutput, nodeDecl.produces.fields);
+        const passed = validationErrors.length === 0;
+        const nr = { node: name, passed, output: mockOutput, validationErrors };
+        nodeResults.push(nr);
+        return { node: name, output: mockOutput, durationMs: 0, success: true };
+    };
+    const flowCtx = {
+        executeNode,
+        getFailureStrategy: (name) => index.nodeMap.get(name)?.onFailure,
+        getConditionalEdge: (sourceName) => {
+            const edges = index.edgesBySource.get(sourceName);
+            if (!edges)
+                return null;
+            for (const edge of edges) {
+                if (edge.target.kind === 'conditional') {
+                    return { branches: edge.target.branches, transforms: edge.transforms };
+                }
+            }
+            return null;
+        },
+        outputs,
+        input: inputUsed,
+    };
+    const executionErrors = [];
+    const executionResults = [];
+    try {
+        await executeFlowNodes(graph.flow, executionResults, executionErrors, flowCtx);
+    }
+    catch (e) {
+        executionErrors.push(e instanceof Error ? e.message : String(e));
+    }
+    const allPassed = nodeResults.every(r => r.passed) && executionErrors.length === 0;
+    return {
+        success: allPassed,
+        inputUsed,
+        nodeResults,
+        compileErrors: [],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsleekr/graft",
-  "version": "5.8.0",
+  "version": "6.0.0",
   "description": "Graft compiler — compile .gft graph DSL to Claude Code harness structures",
   "type": "module",
   "license": "MIT",