gradient-script 0.1.0 → 0.2.0

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,11 +124,33 @@ 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
  */
@@ -121,25 +162,26 @@ export function formatGuardWarnings(result) {
     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('NaN, Infinity, or incorrect gradients:');
     lines.push('');
-    // Group by type
-    const byType = new Map();
+    // 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}`);
+        const typeLabel = formatGuardType(guard.type);
+        // Show location and variable if available
+        let location = '  •';
+        if (guard.line) {
+            location += ` Line ${guard.line}:`;
+        }
+        if (guard.variableName) {
+            location += ` ${guard.variableName} =`;
+        }
+        lines.push(location);
+        lines.push(`    ${typeLabel}: ${guard.description}`);
+        lines.push(`    💡 Fix: ${guard.suggestion}`);
         lines.push('');
     }
-    lines.push('Consider adding runtime checks or ensuring inputs are within valid ranges.');
+    lines.push('Add runtime checks or ensure inputs are within valid ranges.');
+    lines.push('Use --guards --epsilon 1e-10 to automatically emit epsilon guards.');
     lines.push('');
     return lines.join('\n');
 }

package/dist/dsl/Inliner.js

@@ -6,8 +6,9 @@ import { ExpressionTransformer } from './ExpressionTransformer.js';
 /**
  * Expression transformer that substitutes variables from a substitution map
  * Handles recursive inlining by reprocessing substituted expressions
+ * Used for inlining intermediate variables to eliminate assignments
  */
-class SubstitutionTransformer extends ExpressionTransformer {
+class VariableSubstitutionTransformer extends ExpressionTransformer {
     substitutions;
     constructor(substitutions) {
         super();
@@ -35,6 +36,6 @@ export function inlineIntermediateVariables(func) {
         }
     }
     // Use transformer to inline all variables
-    const transformer = new SubstitutionTransformer(substitutions);
+    const transformer = new VariableSubstitutionTransformer(substitutions);
     return transformer.transform(func.returnExpr);
 }

package/dist/dsl/Lexer.js

@@ -2,6 +2,7 @@
  * Lexer for GradientScript DSL
  * Tokenizes input with support for ∇, ^, **, and structured types
  */
+import { ParseError } from './Errors.js';
 export var TokenType;
 (function (TokenType) {
     // Literals
@@ -126,7 +127,8 @@ export class Lexer {
                 this.advance();
                 return { type: TokenType.NEWLINE, value: '\n', line, column };
         }
-        throw new Error(`Unexpected character '${char}' at line ${line}, column ${column}`);
+        // Create a more helpful error for common mistakes
+        throw new ParseError(`Unexpected character '${char}'`, line, column, char);
     }
     number() {
         const line = this.line;

package/dist/dsl/Parser.js

@@ -123,13 +123,15 @@ export class Parser {
      * variable = expression
      */
     assignment() {
-        const variable = this.consume(TokenType.IDENTIFIER, 'Expected variable name').value;
+        const varToken = this.consume(TokenType.IDENTIFIER, 'Expected variable name');
+        const variable = varToken.value;
         this.consume(TokenType.EQUALS, "Expected '=' in assignment");
         const expression = this.expression();
         return {
             kind: 'assignment',
             variable,
-            expression
+            expression,
+            loc: { line: varToken.line, column: varToken.column }
         };
     }
     /**
@@ -161,13 +163,15 @@ export class Parser {
     multiplicative() {
         let expr = this.power();
         while (this.match(TokenType.MULTIPLY, TokenType.DIVIDE)) {
-            const operator = this.previous().value;
+            const opToken = this.previous();
+            const operator = opToken.value;
             const right = this.power();
             expr = {
                 kind: 'binary',
                 operator,
                 left: expr,
-                right
+                right,
+                loc: { line: opToken.line, column: opToken.column }
             };
         }
         return expr;
@@ -213,6 +217,7 @@ export class Parser {
         while (true) {
             if (this.match(TokenType.LPAREN)) {
                 // Function call
+                const startLoc = expr.loc || { line: this.previous().line, column: this.previous().column };
                 const args = this.argumentList();
                 this.consume(TokenType.RPAREN, "Expected ')' after arguments");
                 if (expr.kind !== 'variable') {
@@ -222,7 +227,8 @@ export class Parser {
                 expr = {
                     kind: 'call',
                     name: expr.name,
-                    args
+                    args,
+                    loc: startLoc
                 };
             }
             else if (this.match(TokenType.DOT)) {

package/dist/dsl/Simplify.js

@@ -116,6 +116,53 @@ class Simplifier extends ExpressionTransformer {
             if (expressionsEqual(left, right)) {
                 return { kind: 'number', value: 1 };
             }
+            // (a + a) / 2 → a
+            if (rightNum === 2 && left.kind === 'binary' && left.operator === '+') {
+                if (expressionsEqual(left.left, left.right)) {
+                    return left.left;
+                }
+            }
+            // (a + a) / (2 * b) → a / b
+            if (right.kind === 'binary' && right.operator === '*') {
+                const rightLeft = right.left;
+                const rightRight = right.right;
+                const rightLeftNum = isNumber(rightLeft) ? rightLeft.value : null;
+                if (rightLeftNum === 2 && left.kind === 'binary' && left.operator === '+') {
+                    if (expressionsEqual(left.left, left.right)) {
+                        return {
+                            kind: 'binary',
+                            operator: '/',
+                            left: left.left,
+                            right: rightRight
+                        };
+                    }
+                    // (-1 * a + a * -1) / (2 * b) → -a / b
+                    const leftLeft = left.left;
+                    const leftRight = left.right;
+                    if (leftLeft.kind === 'binary' && leftLeft.operator === '*' &&
+                        leftRight.kind === 'binary' && leftRight.operator === '*') {
+                        const ll_left = leftLeft.left;
+                        const ll_right = leftLeft.right;
+                        const lr_left = leftRight.left;
+                        const lr_right = leftRight.right;
+                        const ll_leftNum = isNumber(ll_left) ? ll_left.value : null;
+                        const lr_rightNum = isNumber(lr_right) ? lr_right.value : null;
+                        // (-1 * a) + (a * -1)
+                        if (ll_leftNum === -1 && lr_rightNum === -1 && expressionsEqual(ll_right, lr_left)) {
+                            return {
+                                kind: 'unary',
+                                operator: '-',
+                                operand: {
+                                    kind: 'binary',
+                                    operator: '/',
+                                    left: ll_right,
+                                    right: rightRight
+                                }
+                            };
+                        }
+                    }
+                }
+            }
         }
         // Power rules
         if (expr.operator === '^' || expr.operator === '**') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gradient-script",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Symbolic differentiation for structured types with a simple DSL",
   "type": "module",
   "main": "dist/index.js",