gradient-script 0.1.0 → 0.3.0

package/dist/dsl/Errors.d.ts

@@ -2,8 +2,13 @@ export declare class ParseError extends Error {
     line: number;
     column: number;
     token?: string | undefined;
-    constructor(message: string, line: number, column: number, token?: string | undefined);
+    sourceContext?: string | undefined;
+    constructor(message: string, line: number, column: number, token?: string | undefined, sourceContext?: string | undefined);
 }
+/**
+ * Format a user-friendly error message with source context
+ */
+export declare function formatParseError(error: ParseError, sourceCode: string, verbose?: boolean): string;
 export declare class TypeError extends Error {
     expression: string;
     expectedType?: string | undefined;

package/dist/dsl/Errors.js

@@ -2,14 +2,83 @@ export class ParseError extends Error {
     line;
     column;
     token;
-    constructor(message, line, column, token) {
+    sourceContext;
+    constructor(message, line, column, token, sourceContext) {
         super(`Parse error at ${line}:${column}: ${message}`);
         this.line = line;
         this.column = column;
         this.token = token;
+        this.sourceContext = sourceContext;
         this.name = 'ParseError';
     }
 }
+/**
+ * Format a user-friendly error message with source context
+ */
+export function formatParseError(error, sourceCode, verbose = false) {
+    const lines = sourceCode.split('\n');
+    const errorLine = lines[error.line - 1];
+    let output = `Error: ${error.message.replace(/^Parse error at \d+:\d+: /, '')}\n`;
+    // Show the source line with the error
+    if (errorLine) {
+        output += `\n  ${errorLine}\n`;
+        // Add caret pointing to error position
+        const caretPos = Math.max(0, error.column - 1);
+        output += `  ${' '.repeat(caretPos)}^\n`;
+    }
+    // Add helpful tips based on the error
+    output += formatErrorGuidance(error);
+    // Only show stack trace in verbose mode
+    if (verbose && error.stack) {
+        output += '\n\nStack trace:\n' + error.stack;
+    }
+    return output;
+}
+/**
+ * Provide contextual guidance based on error patterns
+ */
+function formatErrorGuidance(error) {
+    const msg = error.message.toLowerCase();
+    const token = error.token;
+    // Semicolon error
+    if (token === ';') {
+        return `
+Semicolons are not part of gradient-script syntax.
+Each statement should be on its own line.
+
+Correct syntax:
+  function example(x∇, y∇) {
+    result = x + y
+    return result
+  }
+
+💡 Tip: gradient-script uses newline-delimited statements (like Python),
+        not semicolons (like JavaScript/C#).
+`;
+    }
+    // Missing colon in type annotation
+    if (msg.includes("expected ':'")) {
+        return `
+Type annotations require a colon before the type.
+
+Correct syntax:
+  function distance(point∇: {x, y}) {
+                          ^
+
+💡 Tip: Parameters marked with ∇ need type annotations to specify structure.
+`;
+    }
+    // Missing gradient marker suggestion
+    if (msg.includes('expected parameter name') || msg.includes('unexpected')) {
+        return `
+💡 Tip: Make sure all parameters are properly formatted.
+        Variables that need gradients must be marked with ∇.
+
+        Example: function f(a∇: {x, y}, b) { ... }
+`;
+    }
+    return '';
+}
 export class TypeError extends Error {
     expression;
     expectedType;

package/dist/dsl/Expander.js

@@ -2,6 +2,7 @@
  * Expander for GradientScript DSL
  * Expands built-in functions and struct operations into scalar operations
  */
+import { DifferentiationError } from './Errors.js';
 /**
  * Expand built-in function calls to scalar expressions
  */
@@ -15,13 +16,15 @@ export function expandBuiltIn(call) {
         case 'magnitude2d':
             return expandMagnitude2d(args[0]);
         case 'normalize2d':
-            throw new Error('normalize2d not yet supported in differentiation');
+            throw new DifferentiationError('normalize2d not yet supported', 'normalize2d', 'Vector normalization requires special handling for zero-length vectors. ' +
+                'Use magnitude2d() and division for now.');
         case 'distance2d':
             return expandDistance2d(args[0], args[1]);
         case 'dot3d':
             return expandDot3d(args[0], args[1]);
         case 'cross3d':
-            throw new Error('cross3d returns vector - not yet supported');
+            throw new DifferentiationError('cross3d returns vector - not yet supported', 'cross3d', 'Cross product returns a 3D vector, which requires structured gradient support. ' +
+                'This feature is not yet implemented.');
         case 'magnitude3d':
             return expandMagnitude3d(args[0]);
         default:

package/dist/dsl/ExpressionUtils.d.ts

@@ -53,3 +53,17 @@ export declare function containsVariable(expr: Expression, varName: string): boo
  * Calculate the maximum nesting depth of an expression
  */
 export declare function expressionDepth(expr: Expression): number;
+/**
+ * Serializes an expression to structural string representation.
+ * Used for exact expression comparison - operand order matters.
+ *
+ * This ensures consistent string representation of expressions across different
+ * parts of the codebase.
+ */
+export declare function serializeExpression(expr: Expression): string;
+/**
+ * Serializes an expression to canonical form for CSE matching.
+ * Commutative operations (+ and *) have operands sorted lexicographically,
+ * so a*b and b*a produce the same canonical string.
+ */
+export declare function serializeCanonical(expr: Expression): string;

package/dist/dsl/ExpressionUtils.js

@@ -173,3 +173,59 @@ export function expressionDepth(expr) {
             return 1 + expressionDepth(expr.object);
     }
 }
+/**
+ * Serializes an expression to structural string representation.
+ * Used for exact expression comparison - operand order matters.
+ *
+ * This ensures consistent string representation of expressions across different
+ * parts of the codebase.
+ */
+export function serializeExpression(expr) {
+    switch (expr.kind) {
+        case 'number':
+            return `num(${expr.value})`;
+        case 'variable':
+            return `var(${expr.name})`;
+        case 'binary':
+            return `bin(${expr.operator},${serializeExpression(expr.left)},${serializeExpression(expr.right)})`;
+        case 'unary':
+            return `un(${expr.operator},${serializeExpression(expr.operand)})`;
+        case 'call':
+            const args = expr.args.map(arg => serializeExpression(arg)).join(',');
+            return `call(${expr.name},${args})`;
+        case 'component':
+            return `comp(${serializeExpression(expr.object)},${expr.component})`;
+    }
+}
+/**
+ * Serializes an expression to canonical form for CSE matching.
+ * Commutative operations (+ and *) have operands sorted lexicographically,
+ * so a*b and b*a produce the same canonical string.
+ */
+export function serializeCanonical(expr) {
+    switch (expr.kind) {
+        case 'number':
+            return `num(${expr.value})`;
+        case 'variable':
+            return `var(${expr.name})`;
+        case 'binary': {
+            const leftStr = serializeCanonical(expr.left);
+            const rightStr = serializeCanonical(expr.right);
+            // For commutative operations, sort operands lexicographically
+            if (expr.operator === '+' || expr.operator === '*') {
+                const [first, second] = leftStr <= rightStr ? [leftStr, rightStr] : [rightStr, leftStr];
+                return `bin(${expr.operator},${first},${second})`;
+            }
+            // Non-commutative: preserve order
+            return `bin(${expr.operator},${leftStr},${rightStr})`;
+        }
+        case 'unary':
+            return `un(${expr.operator},${serializeCanonical(expr.operand)})`;
+        case 'call': {
+            const args = expr.args.map(arg => serializeCanonical(arg)).join(',');
+            return `call(${expr.name},${args})`;
+        }
+        case 'component':
+            return `comp(${serializeCanonical(expr.object)},${expr.component})`;
+    }
+}

package/dist/dsl/GradientChecker.d.ts

@@ -17,9 +17,25 @@ type NumValue = number | {
 export interface GradCheckResult {
     passed: boolean;
     errors: GradCheckError[];
+    singularities: GradCheckSingularity[];
     maxError: number;
     meanError: number;
+    totalChecks: number;
 }
+/**
+ * Singularity detected during gradient checking
+ * When both analytical and numerical produce NaN/Inf, it's a singularity, not a bug
+ */
+export interface GradCheckSingularity {
+    parameter: string;
+    component?: string;
+    analytical: number;
+    numerical: number;
+}
+/**
+ * Format gradient check results as a human-readable string
+ */
+export declare function formatGradCheckResult(result: GradCheckResult, funcName: string): string;
 export interface GradCheckError {
     parameter: string;
     component?: string;
@@ -39,6 +55,11 @@ export declare class GradientChecker {
      * Check gradients for a function
      */
     check(func: FunctionDef, gradients: GradientResult, env: TypeEnv, testPoint: Map<string, NumValue>): GradCheckResult;
+    /**
+     * Compare analytical and numerical gradients
+     * Distinguishes between: pass, error (mismatch), and singularity (both NaN/Inf)
+     */
+    private compareGradients;
     /**
      * Compute numerical gradient for scalar parameter using finite differences
      */

package/dist/dsl/GradientChecker.js

@@ -4,6 +4,47 @@
  */
 import { Types } from './Types.js';
 import { expandBuiltIn, shouldExpand } from './Expander.js';
+/**
+ * Format gradient check results as a human-readable string
+ */
+export function formatGradCheckResult(result, funcName) {
+    const singularityCount = result.singularities.length;
+    const verifiedCount = result.totalChecks - result.errors.length - singularityCount;
+    if (result.passed) {
+        let msg = `✓ ${funcName}: ${verifiedCount} gradients verified (max error: ${result.maxError.toExponential(2)})`;
+        if (singularityCount > 0) {
+            msg += `\n  ⚠ ${singularityCount} singularities detected (both analytical and numerical produce NaN/Inf)`;
+        }
+        return msg;
+    }
+    const lines = [
+        `✗ ${funcName}: ${result.errors.length}/${result.totalChecks} gradients FAILED`
+    ];
+    // Group errors by parameter
+    const byParam = new Map();
+    for (const err of result.errors) {
+        const key = err.parameter;
+        if (!byParam.has(key))
+            byParam.set(key, []);
+        byParam.get(key).push(err);
+    }
+    for (const [param, errs] of byParam) {
+        if (errs.length === 1 && !errs[0].component) {
+            // Scalar parameter
+            const e = errs[0];
+            lines.push(`  ${param}: analytical=${e.analytical.toFixed(6)}, numerical=${e.numerical.toFixed(6)}, error=${e.error.toExponential(2)}`);
+        }
+        else {
+            // Structured parameter - show on one line if possible
+            const components = errs.map(e => `${e.component}:${e.error.toExponential(1)}`).join(', ');
+            lines.push(`  ${param}: {${components}}`);
+        }
+    }
+    if (singularityCount > 0) {
+        lines.push(`  ⚠ ${singularityCount} singularities also detected`);
+    }
+    return lines.join('\n');
+}
 /**
  * Gradient checker
  */
@@ -19,6 +60,9 @@ export class GradientChecker {
      */
     check(func, gradients, env, testPoint) {
         const errors = [];
+        const singularities = [];
+        let totalChecks = 0;
+        let maxError = 0;
         // For each parameter that has gradients
         for (const [paramName, gradient] of gradients.gradients.entries()) {
             const paramType = env.getOrThrow(paramName);
@@ -28,21 +72,21 @@ export class GradientChecker {
             }
             if (Types.isScalar(paramType)) {
                 // Scalar parameter
+                totalChecks++;
                 if (typeof paramValue !== 'number') {
                     throw new Error(`Expected scalar value for ${paramName}`);
                 }
                 const analytical = this.evaluateExpression(gradient, testPoint);
                 const numerical = this.numericalGradientScalar(func, testPoint, paramName);
-                const error = Math.abs(analytical - numerical);
-                const relativeError = Math.abs(error / (numerical + 1e-10));
-                if (error > this.tolerance && relativeError > this.tolerance) {
-                    errors.push({
-                        parameter: paramName,
-                        analytical,
-                        numerical,
-                        error,
-                        relativeError
-                    });
+                const checkResult = this.compareGradients(analytical, numerical, paramName);
+                if (checkResult.type === 'singularity') {
+                    singularities.push(checkResult.singularity);
+                }
+                else if (checkResult.type === 'error') {
+                    errors.push(checkResult.error);
+                }
+                else if (checkResult.error) {
+                    maxError = Math.max(maxError, checkResult.error.error);
                 }
             }
             else {
@@ -52,32 +96,74 @@ export class GradientChecker {
                 }
                 const structGrad = gradient;
                 for (const [comp, expr] of structGrad.components.entries()) {
+                    totalChecks++;
                     const analytical = this.evaluateExpression(expr, testPoint);
                     const numerical = this.numericalGradientComponent(func, testPoint, paramName, comp);
-                    const error = Math.abs(analytical - numerical);
-                    const relativeError = Math.abs(error / (numerical + 1e-10));
-                    if (error > this.tolerance && relativeError > this.tolerance) {
-                        errors.push({
-                            parameter: paramName,
-                            component: comp,
-                            analytical,
-                            numerical,
-                            error,
-                            relativeError
-                        });
+                    const checkResult = this.compareGradients(analytical, numerical, paramName, comp);
+                    if (checkResult.type === 'singularity') {
+                        singularities.push(checkResult.singularity);
+                    }
+                    else if (checkResult.type === 'error') {
+                        errors.push(checkResult.error);
+                    }
+                    else if (checkResult.error) {
+                        maxError = Math.max(maxError, checkResult.error.error);
                     }
                 }
             }
         }
-        const maxError = errors.length > 0 ? Math.max(...errors.map(e => e.error)) : 0;
         const meanError = errors.length > 0
             ? errors.reduce((sum, e) => sum + e.error, 0) / errors.length
             : 0;
         return {
             passed: errors.length === 0,
             errors,
+            singularities,
             maxError,
-            meanError
+            meanError,
+            totalChecks
+        };
+    }
+    /**
+     * Compare analytical and numerical gradients
+     * Distinguishes between: pass, error (mismatch), and singularity (both NaN/Inf)
+     */
+    compareGradients(analytical, numerical, parameter, component) {
+        const analyticalBad = !isFinite(analytical);
+        const numericalBad = !isFinite(numerical);
+        // Both produce NaN/Inf: singularity (not a bug)
+        if (analyticalBad && numericalBad) {
+            return {
+                type: 'singularity',
+                singularity: { parameter, component, analytical, numerical }
+            };
+        }
+        // One produces NaN/Inf, the other doesn't: actual bug
+        if (analyticalBad || numericalBad) {
+            return {
+                type: 'error',
+                error: {
+                    parameter,
+                    component,
+                    analytical,
+                    numerical,
+                    error: Infinity,
+                    relativeError: Infinity
+                }
+            };
+        }
+        // Both finite: compare values
+        const error = Math.abs(analytical - numerical);
+        const relativeError = Math.abs(error / (Math.abs(numerical) + 1e-10));
+        if (error > this.tolerance && relativeError > this.tolerance) {
+            return {
+                type: 'error',
+                error: { parameter, component, analytical, numerical, error, relativeError }
+            };
+        }
+        return {
+            type: 'pass',
+            error: { parameter, component, analytical, numerical, error, relativeError }
         };
     }
     /**

package/dist/dsl/Guards.d.ts

@@ -8,6 +8,8 @@ export interface Guard {
     expression: Expression;
     description: string;
     suggestion: string;
+    variableName?: string;
+    line?: number;
 }
 export interface GuardAnalysisResult {
     guards: Guard[];
@@ -20,7 +22,7 @@ export declare function analyzeGuards(func: FunctionDef): GuardAnalysisResult;
 /**
  * Format guard analysis for display
  */
-export declare function formatGuardWarnings(result: GuardAnalysisResult): string;
+export declare function formatGuardWarnings(result: GuardAnalysisResult, asComments?: boolean): string;
 /**
  * Generate guard code snippets for common cases
  */

package/dist/dsl/Guards.js

@@ -8,11 +8,11 @@
 export function analyzeGuards(func) {
     const guards = [];
     // Analyze return expression
-    collectGuards(func.returnExpr, guards);
+    collectGuards(func.returnExpr, guards, undefined);
     // Analyze intermediate expressions
     for (const stmt of func.body) {
         if (stmt.kind === 'assignment') {
-            collectGuards(stmt.expression, guards);
+            collectGuards(stmt.expression, guards, stmt.variable, stmt.loc?.line);
         }
     }
     return {
@@ -23,7 +23,7 @@ export function analyzeGuards(func) {
 /**
  * Collect potential guards from an expression
  */
-function collectGuards(expr, guards) {
+function collectGuards(expr, guards, variableName, line) {
     switch (expr.kind) {
         case 'binary':
             if (expr.operator === '/') {
@@ -31,47 +31,60 @@ function collectGuards(expr, guards) {
                     type: 'division_by_zero',
                     expression: expr.right,
                     description: `Division by zero if denominator becomes zero`,
-                    suggestion: `Add check: if (denominator === 0) return { value: 0, gradients: {...} };`
+                    suggestion: `Add check: if (Math.abs(denominator) < epsilon) return {...};`,
+                    variableName,
+                    line: line || expr.loc?.line
                 });
             }
-            collectGuards(expr.left, guards);
-            collectGuards(expr.right, guards);
+            collectGuards(expr.left, guards, variableName, line);
+            collectGuards(expr.right, guards, variableName, line);
             break;
         case 'unary':
-            collectGuards(expr.operand, guards);
+            collectGuards(expr.operand, guards, variableName, line);
             break;
         case 'call':
-            analyzeCallGuards(expr, guards);
+            analyzeCallGuards(expr, guards, variableName, line || expr.loc?.line);
             for (const arg of expr.args) {
-                collectGuards(arg, guards);
+                collectGuards(arg, guards, variableName, line);
             }
             break;
         case 'component':
-            collectGuards(expr.object, guards);
+            collectGuards(expr.object, guards, variableName, line);
             break;
     }
 }
 /**
  * Analyze function calls for specific edge cases
  */
-function analyzeCallGuards(expr, guards) {
+function analyzeCallGuards(expr, guards, variableName, line) {
     switch (expr.name) {
         case 'sqrt':
+            // Check if it's sqrt of sum of squares (always safe)
+            const arg = expr.args[0];
+            const isSumOfSquares = arg.kind === 'binary' && arg.operator === '+' &&
+                isSqExpression(arg.left) && isSqExpression(arg.right);
             guards.push({
                 type: 'sqrt_negative',
                 expression: expr.args[0],
-                description: `sqrt of negative number produces NaN`,
-                suggestion: `Add check: Math.max(0, value) or abs(value)`
+                description: isSumOfSquares
+                    ? `sqrt of sum of squares (safe, but can be zero)`
+                    : `sqrt of negative number produces NaN`,
+                suggestion: isSumOfSquares
+                    ? `Add epsilon for numerical stability: sqrt(max(dx*dx + dy*dy, epsilon))`
+                    : `Guard negative values: sqrt(max(0, value))`,
+                variableName,
+                line
             });
             break;
         case 'magnitude2d':
         case 'magnitude3d':
-            // magnitude uses sqrt internally
             guards.push({
                 type: 'sqrt_negative',
                 expression: expr,
-                description: `magnitude of vector (uses sqrt internally)`,
-                suggestion: `Ensure vector components are valid`
+                description: `magnitude uses sqrt internally (safe, but can be zero)`,
+                suggestion: `Gradients may have division by zero when magnitude is zero`,
+                variableName,
+                line
             });
             break;
         case 'normalize2d':
@@ -80,15 +93,19 @@ function analyzeCallGuards(expr, guards) {
                 type: 'normalize_zero',
                 expression: expr,
                 description: `Normalizing zero vector causes division by zero`,
-                suggestion: `Check if magnitude > epsilon before normalizing`
+                suggestion: `if (magnitude < epsilon) return zero vector or skip normalization`,
+                variableName,
+                line
             });
             break;
         case 'atan2':
             guards.push({
                 type: 'atan2_zero',
                 expression: expr,
-                description: `atan2(0, 0) is undefined`,
-                suggestion: `Check if both arguments are zero: if (y === 0 && x === 0) return 0;`
+                description: `atan2(0, 0) is undefined and gradients have division by zero`,
+                suggestion: `if (y === 0 && x === 0) return 0 with zero gradients`,
+                variableName,
+                line
             });
             break;
         case 'log':
@@ -96,7 +113,9 @@ function analyzeCallGuards(expr, guards) {
                 type: 'division_by_zero',
                 expression: expr.args[0],
                 description: `log(0) is -Infinity, log(negative) is NaN`,
-                suggestion: `Add check: Math.max(epsilon, value)`
+                suggestion: `Clamp to positive: log(max(epsilon, value))`,
+                variableName,
+                line
             });
             break;
         case 'asin':
@@ -105,42 +124,66 @@ function analyzeCallGuards(expr, guards) {
                 type: 'division_by_zero',
                 expression: expr.args[0],
                 description: `${expr.name} requires argument in [-1, 1]`,
-                suggestion: `Clamp value: Math.max(-1, Math.min(1, value))`
+                suggestion: `Clamp: ${expr.name}(max(-1, min(1, value)))`,
+                variableName,
+                line
             });
             break;
     }
 }
+/**
+ * Check if expression is a squared term (x^2 or x*x)
+ */
+function isSqExpression(expr) {
+    if (expr.kind === 'binary') {
+        if (expr.operator === '*') {
+            // Check if x * x
+            if (expr.left.kind === 'variable' && expr.right.kind === 'variable') {
+                return expr.left.name === expr.right.name;
+            }
+        }
+        else if (expr.operator === '^' || expr.operator === '**') {
+            // Check if x^2
+            if (expr.right.kind === 'number' && expr.right.value === 2) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
 /**
  * Format guard analysis for display
  */
-export function formatGuardWarnings(result) {
+export function formatGuardWarnings(result, asComments = false) {
     if (!result.hasIssues) {
         return '';
     }
+    const prefix = asComments ? '// ' : '';
     const lines = [];
-    lines.push('⚠️  EDGE CASE WARNINGS:');
-    lines.push('');
-    lines.push('The generated code may encounter edge cases that produce');
-    lines.push('NaN, Infinity, or incorrect results:');
-    lines.push('');
-    // Group by type
-    const byType = new Map();
+    lines.push(`${prefix}⚠️  EDGE CASE WARNINGS:`);
+    lines.push(prefix);
+    lines.push(`${prefix}The generated code may encounter edge cases that produce`);
+    lines.push(`${prefix}NaN, Infinity, or incorrect gradients:`);
+    lines.push(prefix);
+    // Show each guard individually with context
     for (const guard of result.guards) {
-        const existing = byType.get(guard.type) || [];
-        existing.push(guard);
-        byType.set(guard.type, existing);
-    }
-    for (const [type, guards] of byType.entries()) {
-        const typeLabel = formatGuardType(type);
-        lines.push(`  • ${typeLabel} (${guards.length} occurrence${guards.length > 1 ? 's' : ''})`);
-        // Show first occurrence
-        const first = guards[0];
-        lines.push(`    ${first.description}`);
-        lines.push(`    💡 ${first.suggestion}`);
-        lines.push('');
+        const typeLabel = formatGuardType(guard.type);
+        // Show location and variable if available
+        let location = `${prefix}  •`;
+        if (guard.line) {
+            location += ` Line ${guard.line}:`;
+        }
+        if (guard.variableName) {
+            location += ` ${guard.variableName} =`;
+        }
+        lines.push(location);
+        lines.push(`${prefix}    ${typeLabel}: ${guard.description}`);
+        lines.push(`${prefix}    💡 Fix: ${guard.suggestion}`);
+        lines.push(prefix);
     }
-    lines.push('Consider adding runtime checks or ensuring inputs are within valid ranges.');
-    lines.push('');
+    lines.push(`${prefix}Add runtime checks or ensure inputs are within valid ranges.`);
+    lines.push(`${prefix}Use --guards --epsilon 1e-10 to automatically emit epsilon guards.`);
+    lines.push(prefix);
     return lines.join('\n');
 }
 function formatGuardType(type) {

package/dist/dsl/Inliner.d.ts

@@ -8,3 +8,8 @@ import { Expression, FunctionDef } from './AST.js';
  * Returns a new expression with all intermediate variables substituted
  */
 export declare function inlineIntermediateVariables(func: FunctionDef): Expression;
+/**
+ * Inline an expression using a substitution map
+ * Used to get the fully-expanded form of forward pass expressions
+ */
+export declare function inlineExpression(expr: Expression, substitutions: Map<string, Expression>): Expression;