retiam 1.0.0 → 1.0.2

package/bin/lint.js

@@ -1,354 +1,354 @@
-#!/usr/bin/env node
-
-// =========================================================================
-// File: bin/lint.js - Retiam Agent-Native Scene Linter & Static Analyzer
-// =========================================================================
-
-import fs from 'fs';
-import path from 'path';
-import ts from 'typescript';
-
-const args = process.argv.slice(2);
-let targetFile = null;
-let jsonOutput = false;
-
-const isHelp = args.includes('--help') || args.includes('-h') || args.includes('help');
-if (isHelp) {
-    console.log(`
-🔍 Retiam WebGPU Engine - Scene Linter & Static Analyzer
-
-Usage:
-  npx retiam lint <path/to/Scene.ts> [options]
-
-Arguments:
-  <file>                    Target scene file to statically analyze (e.g. src/scenes/AStarScene.ts)
-
-Options:
-  --json                    Output structured machine-readable JSON for agents and CI
-  --help, -h                Show this help message and exit
-
-Checks:
-  - Validates Scene class structure and async run() contract
-  - Detects un-awaited this.play() or this.wait() timing races
-  - Warns about dangling entities not attached to scene graph
-  - Catches Three.js / Python Manim hallucinations
-  - Flags extreme world coordinates exceeding standard camera frustum
-
-Examples:
-  npx retiam lint src/scenes/AStarScene.ts
-  npx retiam lint src/scenes/AStarScene.ts --json
-`);
-    process.exit(0);
-}
-
-for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--json') {
-        jsonOutput = true;
-    } else if (!args[i].startsWith('-') && !targetFile) {
-        targetFile = args[i];
-    }
-}
-
-if (!targetFile) {
-    if (jsonOutput) {
-        console.log(JSON.stringify({ status: 'error', message: 'No target scene file specified.' }));
-    } else {
-        console.error('❌ Error: No target scene file specified.');
-        console.log('Usage: npx retiam lint <path/to/Scene.ts> [--json]');
-    }
-    process.exit(1);
-}
-
-const resolvedPath = path.resolve(process.cwd(), targetFile);
-if (!fs.existsSync(resolvedPath)) {
-    if (jsonOutput) {
-        console.log(JSON.stringify({ status: 'error', message: `File not found: ${targetFile}` }));
-    } else {
-        console.error(`❌ Error: File not found: ${resolvedPath}`);
-    }
-    process.exit(1);
-}
-
-const sourceCode = fs.readFileSync(resolvedPath, 'utf8');
-const sourceFile = ts.createSourceFile(
-    resolvedPath,
-    sourceCode,
-    ts.ScriptTarget.Latest,
-    true
-);
-
-const diagnostics = [];
-const lines = sourceCode.split('\n');
-
-function addDiagnostic(type, rule, line, col, message, suggestion, codeSnippet) {
-    diagnostics.push({
-        type, // 'error' | 'warning'
-        rule,
-        line,
-        col,
-        message,
-        suggestion,
-        codeSnippet: codeSnippet || (lines[line - 1] ? lines[line - 1].trim() : '')
-    });
-}
-
-function getLineAndCol(node) {
-    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
-    return { line: line + 1, col: character + 1 };
-}
-
-// Known Retiam Entity classes
-const ENTITY_CLASSES = new Set([
-    'Circle', 'Rect', 'Line', 'Arrow', 'Polygon', 'RegularPolygon',
-    'Arc', 'Sector', 'Annulus', 'Dot', 'GlowDot', 'Path', 'SVGShape', 'SVG',
-    'SDFText', 'Tex', 'Code', 'Axes', 'NumberLine', 'Graph', 'BarChart',
-    'PieChart', 'Model', 'Sphere', 'Box3D', 'Cylinder', 'Cone', 'Plane',
-    'Mesh', 'MorphModel', 'TracePath', 'VBox', 'HBox', 'Group'
-]);
-
-// Track instantiated entities to check if they are added
-const instantiatedEntities = new Map(); // name -> { line, col, className }
-const referencedIdentifiers = new Set();
-let hasSceneClass = false;
-let hasRunMethod = false;
-let hasCameraSetup = false;
-
-function checkNode(node) {
-    // 1. Check for Scene Class & run() method
-    if (ts.isClassDeclaration(node)) {
-        if (node.heritageClauses) {
-            for (const clause of node.heritageClauses) {
-                if (clause.token === ts.SyntaxKind.ExtendsKeyword) {
-                    for (const type of clause.types) {
-                        if (type.expression.getText(sourceFile) === 'Scene') {
-                            hasSceneClass = true;
-                        }
-                    }
-                }
-            }
-        }
-
-        // Check for run() method
-        for (const member of node.members) {
-            if (ts.isMethodDeclaration(member)) {
-                const name = member.name.getText(sourceFile);
-                if (name === 'run') {
-                    hasRunMethod = true;
-                    const isAsync = member.modifiers && member.modifiers.some(m => m.kind === ts.SyntaxKind.AsyncKeyword);
-                    if (!isAsync) {
-                        const { line, col } = getLineAndCol(member);
-                        addDiagnostic('error', 'retiam/async-run-required', line, col,
-                            'The run() method of a Scene must be async.',
-                            'Change signature to: public async run(): Promise<void>'
-                        );
-                    }
-                }
-            }
-        }
-    }
-
-    // 2. Check for missing await on this.play() or this.wait()
-    if (ts.isCallExpression(node)) {
-        const exprText = node.expression.getText(sourceFile);
-        const isPlayCall = exprText === 'this.play' || exprText === 'scene.play' || exprText.endsWith('.play');
-        const isWaitCall = exprText === 'this.wait' || exprText === 'scene.wait' || exprText.endsWith('.wait');
-
-        if (isPlayCall || isWaitCall) {
-            // Check if parent is an AwaitExpression
-            let parent = node.parent;
-            // Handle parentheses or expressions
-            while (parent && ts.isParenthesizedExpression(parent)) {
-                parent = parent.parent;
-            }
-
-            if (!parent || !ts.isAwaitExpression(parent)) {
-                // If it's part of a Promise.all or array, it might be fine, but standalone call without await causes sync race
-                const isInPromiseAll = parent && ts.isArrayLiteralExpression(parent) && parent.parent &&
-                    ts.isCallExpression(parent.parent) && parent.parent.expression.getText(sourceFile).includes('Promise.all');
-
-                if (!isInPromiseAll) {
-                    const { line, col } = getLineAndCol(node);
-                    const callName = isPlayCall ? 'play()' : 'wait()';
-                    addDiagnostic(
-                        'error',
-                        'retiam/missing-await',
-                        line,
-                        col,
-                        `Calling ${callName} without 'await'. Animation steps will execute concurrently out of sequence.`,
-                        `Add 'await' before ${node.getText(sourceFile)}`,
-                        node.getText(sourceFile)
-                    );
-                }
-            }
-        }
-
-        // Check camera setup
-        if (exprText.includes('camera.position') || exprText.includes('this.camera')) {
-            hasCameraSetup = true;
-        }
-
-        // Track entities added to scene or containers
-        if (exprText === 'this.add' || exprText === 'scene.add' || exprText.endsWith('.add') || exprText.endsWith('.append')) {
-            for (const arg of node.arguments) {
-                referencedIdentifiers.add(arg.getText(sourceFile));
-            }
-        }
-    }
-
-    // 3. Track variable assignments with `new EntityClass(...)`
-    if (ts.isVariableDeclaration(node) && node.initializer && ts.isNewExpression(node.initializer)) {
-        const className = node.initializer.expression.getText(sourceFile);
-        if (ENTITY_CLASSES.has(className) && ts.isIdentifier(node.name)) {
-            const varName = node.name.text;
-            const { line, col } = getLineAndCol(node);
-            instantiatedEntities.set(varName, { line, col, className });
-        }
-    }
-
-    // 4. Check for Three.js or Python Manim hallucinations
-    if (ts.isIdentifier(node)) {
-        const text = node.text;
-        if (text === 'THREE') {
-            const { line, col } = getLineAndCol(node);
-            addDiagnostic(
-                'error',
-                'retiam/no-threejs',
-                line,
-                col,
-                'Detected Three.js reference. Retiam uses native WebGPU entities (e.g. Model, Sphere, Box3D).',
-                'Use Retiam 3D primitives: import { Model, Sphere, Box3D } from "retiam"'
-            );
-        }
-    }
-
-    // 5. Check for extreme coordinates in Vector arrays: e.g. [150, 200, 0]
-    if (ts.isArrayLiteralExpression(node) && node.elements.length >= 2 && node.elements.length <= 4) {
-        const parentExpr = node.parent ? node.parent.getText(sourceFile) : '';
-        if (parentExpr.includes('position') || parentExpr.includes('shift') || parentExpr.includes('set')) {
-            for (const elem of node.elements) {
-                if (ts.isNumericLiteral(elem)) {
-                    const val = parseFloat(elem.text);
-                    if (Math.abs(val) > 40) {
-                        const { line, col } = getLineAndCol(elem);
-                        addDiagnostic(
-                            'warning',
-                            'retiam/extreme-coordinate',
-                            line,
-                            col,
-                            `Coordinate value ${val} is very large. Standard Retiam camera view is typically between -10 and 10 world units.`,
-                            'Verify camera distance or use auto-layout/nextTo for positioning.'
-                        );
-                        break;
-                    }
-                }
-            }
-        }
-    }
-
-    // Continue recursive AST traversal
-    ts.forEachChild(node, checkNode);
-}
-
-// Traverse the AST
-checkNode(sourceFile);
-
-// Check if instantiated entities were ever added to the scene graph
-for (const [varName, info] of instantiatedEntities.entries()) {
-    // If not referenced in an .add() call or as child
-    if (!referencedIdentifiers.has(varName)) {
-        // Also check if used in animations like `new Create(circle)`
-        const regex = new RegExp(`\\b${varName}\\b`, 'g');
-        const matches = (sourceCode.match(regex) || []).length;
-        // If it only appeared once (the declaration) or twice without being in this.add
-        if (matches <= 2) {
-            addDiagnostic(
-                'warning',
-                'retiam/dangling-entity',
-                info.line,
-                info.col,
-                `Entity '${varName}' (${info.className}) is created but might not be added to the scene.`,
-                `Ensure you call 'this.add(${varName})' or add it to a container (VBox/HBox).`
-            );
-        }
-    }
-}
-
-// Check Scene class presence
-if (!hasSceneClass) {
-    addDiagnostic(
-        'error',
-        'retiam/missing-scene-class',
-        1,
-        1,
-        'No class extending "Scene" found in file.',
-        'Export a Scene class: export default class MyScene extends Scene { ... }'
-    );
-} else if (!hasRunMethod) {
-    addDiagnostic(
-        'error',
-        'retiam/missing-run-method',
-        1,
-        1,
-        'The Scene class does not implement a run() method.',
-        'Implement: public async run(): Promise<void> { ... }'
-    );
-}
-
-if (!hasCameraSetup && hasSceneClass) {
-    addDiagnostic(
-        'warning',
-        'retiam/no-camera-setup',
-        1,
-        1,
-        'No camera position configuration detected in the scene.',
-        'Initialize camera: this.camera.position.set([0, 0, 14]);'
-    );
-}
-
-// Compute results
-const errors = diagnostics.filter(d => d.type === 'error');
-const warnings = diagnostics.filter(d => d.type === 'warning');
-const isValid = errors.length === 0;
-
-if (jsonOutput) {
-    const result = {
-        file: targetFile,
-        valid: isValid,
-        summary: {
-            errors: errors.length,
-            warnings: warnings.length,
-            total: diagnostics.length
-        },
-        diagnostics
-    };
-    console.log(JSON.stringify(result, null, 2));
-} else {
-    console.log(`\n🔍 Retiam Scene Linter: ${targetFile}`);
-    console.log('='.repeat(60));
-
-    if (diagnostics.length === 0) {
-        console.log('✅ All checks passed! Scene is syntactically and structurally sound.\n');
-    } else {
-        for (const diag of diagnostics) {
-            const icon = diag.type === 'error' ? '❌ [ERROR]' : '⚠️  [WARN]';
-            console.log(`\n${icon} Line ${diag.line}:${diag.col} (${diag.rule})`);
-            console.log(`   Message:    ${diag.message}`);
-            if (diag.codeSnippet) {
-                console.log(`   Snippet:    ${diag.codeSnippet}`);
-            }
-            if (diag.suggestion) {
-                console.log(`   💡 Fix:     ${diag.suggestion}`);
-            }
-        }
-
-        console.log('\n' + '-'.repeat(60));
-        console.log(`Found ${errors.length} error(s), ${warnings.length} warning(s).`);
-        if (!isValid) {
-            console.log('❌ Scene has critical errors that may prevent proper animation playback.\n');
-        } else {
-            console.log('✨ No critical errors found. Please review the warnings above.\n');
-        }
-    }
-}
-
-process.exit(isValid ? 0 : 1);
+#!/usr/bin/env node
+
+// =========================================================================
+// File: bin/lint.js - Retiam Agent-Native Scene Linter & Static Analyzer
+// =========================================================================
+
+import fs from 'fs';
+import path from 'path';
+import ts from 'typescript';
+
+const args = process.argv.slice(2);
+let targetFile = null;
+let jsonOutput = false;
+
+const isHelp = args.includes('--help') || args.includes('-h') || args.includes('help');
+if (isHelp) {
+    console.log(`
+🔍 Retiam WebGPU Engine - Scene Linter & Static Analyzer
+
+Usage:
+  npx retiam lint <path/to/Scene.ts> [options]
+
+Arguments:
+  <file>                    Target scene file to statically analyze (e.g. src/scenes/AStarScene.ts)
+
+Options:
+  --json                    Output structured machine-readable JSON for agents and CI
+  --help, -h                Show this help message and exit
+
+Checks:
+  - Validates Scene class structure and async run() contract
+  - Detects un-awaited this.play() or this.wait() timing races
+  - Warns about dangling entities not attached to scene graph
+  - Catches Three.js / Python Manim hallucinations
+  - Flags extreme world coordinates exceeding standard camera frustum
+
+Examples:
+  npx retiam lint src/scenes/AStarScene.ts
+  npx retiam lint src/scenes/AStarScene.ts --json
+`);
+    process.exit(0);
+}
+
+for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--json') {
+        jsonOutput = true;
+    } else if (!args[i].startsWith('-') && !targetFile) {
+        targetFile = args[i];
+    }
+}
+
+if (!targetFile) {
+    if (jsonOutput) {
+        console.log(JSON.stringify({ status: 'error', message: 'No target scene file specified.' }));
+    } else {
+        console.error('❌ Error: No target scene file specified.');
+        console.log('Usage: npx retiam lint <path/to/Scene.ts> [--json]');
+    }
+    process.exit(1);
+}
+
+const resolvedPath = path.resolve(process.cwd(), targetFile);
+if (!fs.existsSync(resolvedPath)) {
+    if (jsonOutput) {
+        console.log(JSON.stringify({ status: 'error', message: `File not found: ${targetFile}` }));
+    } else {
+        console.error(`❌ Error: File not found: ${resolvedPath}`);
+    }
+    process.exit(1);
+}
+
+const sourceCode = fs.readFileSync(resolvedPath, 'utf8');
+const sourceFile = ts.createSourceFile(
+    resolvedPath,
+    sourceCode,
+    ts.ScriptTarget.Latest,
+    true
+);
+
+const diagnostics = [];
+const lines = sourceCode.split('\n');
+
+function addDiagnostic(type, rule, line, col, message, suggestion, codeSnippet) {
+    diagnostics.push({
+        type, // 'error' | 'warning'
+        rule,
+        line,
+        col,
+        message,
+        suggestion,
+        codeSnippet: codeSnippet || (lines[line - 1] ? lines[line - 1].trim() : '')
+    });
+}
+
+function getLineAndCol(node) {
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return { line: line + 1, col: character + 1 };
+}
+
+// Known Retiam Entity classes
+const ENTITY_CLASSES = new Set([
+    'Circle', 'Rect', 'Line', 'Arrow', 'Polygon', 'RegularPolygon',
+    'Arc', 'Sector', 'Annulus', 'Dot', 'GlowDot', 'Path', 'SVGShape', 'SVG',
+    'SDFText', 'Tex', 'Code', 'Axes', 'NumberLine', 'Graph', 'BarChart',
+    'PieChart', 'Model', 'Sphere', 'Box3D', 'Cylinder', 'Cone', 'Plane',
+    'Mesh', 'MorphModel', 'TracePath', 'VBox', 'HBox', 'Group'
+]);
+
+// Track instantiated entities to check if they are added
+const instantiatedEntities = new Map(); // name -> { line, col, className }
+const referencedIdentifiers = new Set();
+let hasSceneClass = false;
+let hasRunMethod = false;
+let hasCameraSetup = false;
+
+function checkNode(node) {
+    // 1. Check for Scene Class & run() method
+    if (ts.isClassDeclaration(node)) {
+        if (node.heritageClauses) {
+            for (const clause of node.heritageClauses) {
+                if (clause.token === ts.SyntaxKind.ExtendsKeyword) {
+                    for (const type of clause.types) {
+                        if (type.expression.getText(sourceFile) === 'Scene') {
+                            hasSceneClass = true;
+                        }
+                    }
+                }
+            }
+        }
+
+        // Check for run() method
+        for (const member of node.members) {
+            if (ts.isMethodDeclaration(member)) {
+                const name = member.name.getText(sourceFile);
+                if (name === 'run') {
+                    hasRunMethod = true;
+                    const isAsync = member.modifiers && member.modifiers.some(m => m.kind === ts.SyntaxKind.AsyncKeyword);
+                    if (!isAsync) {
+                        const { line, col } = getLineAndCol(member);
+                        addDiagnostic('error', 'retiam/async-run-required', line, col,
+                            'The run() method of a Scene must be async.',
+                            'Change signature to: public async run(): Promise<void>'
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    // 2. Check for missing await on this.play() or this.wait()
+    if (ts.isCallExpression(node)) {
+        const exprText = node.expression.getText(sourceFile);
+        const isPlayCall = exprText === 'this.play' || exprText === 'scene.play' || exprText.endsWith('.play');
+        const isWaitCall = exprText === 'this.wait' || exprText === 'scene.wait' || exprText.endsWith('.wait');
+
+        if (isPlayCall || isWaitCall) {
+            // Check if parent is an AwaitExpression
+            let parent = node.parent;
+            // Handle parentheses or expressions
+            while (parent && ts.isParenthesizedExpression(parent)) {
+                parent = parent.parent;
+            }
+
+            if (!parent || !ts.isAwaitExpression(parent)) {
+                // If it's part of a Promise.all or array, it might be fine, but standalone call without await causes sync race
+                const isInPromiseAll = parent && ts.isArrayLiteralExpression(parent) && parent.parent &&
+                    ts.isCallExpression(parent.parent) && parent.parent.expression.getText(sourceFile).includes('Promise.all');
+
+                if (!isInPromiseAll) {
+                    const { line, col } = getLineAndCol(node);
+                    const callName = isPlayCall ? 'play()' : 'wait()';
+                    addDiagnostic(
+                        'error',
+                        'retiam/missing-await',
+                        line,
+                        col,
+                        `Calling ${callName} without 'await'. Animation steps will execute concurrently out of sequence.`,
+                        `Add 'await' before ${node.getText(sourceFile)}`,
+                        node.getText(sourceFile)
+                    );
+                }
+            }
+        }
+
+        // Check camera setup
+        if (exprText.includes('camera.position') || exprText.includes('this.camera')) {
+            hasCameraSetup = true;
+        }
+
+        // Track entities added to scene or containers
+        if (exprText === 'this.add' || exprText === 'scene.add' || exprText.endsWith('.add') || exprText.endsWith('.append')) {
+            for (const arg of node.arguments) {
+                referencedIdentifiers.add(arg.getText(sourceFile));
+            }
+        }
+    }
+
+    // 3. Track variable assignments with `new EntityClass(...)`
+    if (ts.isVariableDeclaration(node) && node.initializer && ts.isNewExpression(node.initializer)) {
+        const className = node.initializer.expression.getText(sourceFile);
+        if (ENTITY_CLASSES.has(className) && ts.isIdentifier(node.name)) {
+            const varName = node.name.text;
+            const { line, col } = getLineAndCol(node);
+            instantiatedEntities.set(varName, { line, col, className });
+        }
+    }
+
+    // 4. Check for Three.js or Python Manim hallucinations
+    if (ts.isIdentifier(node)) {
+        const text = node.text;
+        if (text === 'THREE') {
+            const { line, col } = getLineAndCol(node);
+            addDiagnostic(
+                'error',
+                'retiam/no-threejs',
+                line,
+                col,
+                'Detected Three.js reference. Retiam uses native WebGPU entities (e.g. Model, Sphere, Box3D).',
+                'Use Retiam 3D primitives: import { Model, Sphere, Box3D } from "retiam"'
+            );
+        }
+    }
+
+    // 5. Check for extreme coordinates in Vector arrays: e.g. [150, 200, 0]
+    if (ts.isArrayLiteralExpression(node) && node.elements.length >= 2 && node.elements.length <= 4) {
+        const parentExpr = node.parent ? node.parent.getText(sourceFile) : '';
+        if (parentExpr.includes('position') || parentExpr.includes('shift') || parentExpr.includes('set')) {
+            for (const elem of node.elements) {
+                if (ts.isNumericLiteral(elem)) {
+                    const val = parseFloat(elem.text);
+                    if (Math.abs(val) > 40) {
+                        const { line, col } = getLineAndCol(elem);
+                        addDiagnostic(
+                            'warning',
+                            'retiam/extreme-coordinate',
+                            line,
+                            col,
+                            `Coordinate value ${val} is very large. Standard Retiam camera view is typically between -10 and 10 world units.`,
+                            'Verify camera distance or use auto-layout/nextTo for positioning.'
+                        );
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    // Continue recursive AST traversal
+    ts.forEachChild(node, checkNode);
+}
+
+// Traverse the AST
+checkNode(sourceFile);
+
+// Check if instantiated entities were ever added to the scene graph
+for (const [varName, info] of instantiatedEntities.entries()) {
+    // If not referenced in an .add() call or as child
+    if (!referencedIdentifiers.has(varName)) {
+        // Also check if used in animations like `new Create(circle)`
+        const regex = new RegExp(`\\b${varName}\\b`, 'g');
+        const matches = (sourceCode.match(regex) || []).length;
+        // If it only appeared once (the declaration) or twice without being in this.add
+        if (matches <= 2) {
+            addDiagnostic(
+                'warning',
+                'retiam/dangling-entity',
+                info.line,
+                info.col,
+                `Entity '${varName}' (${info.className}) is created but might not be added to the scene.`,
+                `Ensure you call 'this.add(${varName})' or add it to a container (VBox/HBox).`
+            );
+        }
+    }
+}
+
+// Check Scene class presence
+if (!hasSceneClass) {
+    addDiagnostic(
+        'error',
+        'retiam/missing-scene-class',
+        1,
+        1,
+        'No class extending "Scene" found in file.',
+        'Export a Scene class: export default class MyScene extends Scene { ... }'
+    );
+} else if (!hasRunMethod) {
+    addDiagnostic(
+        'error',
+        'retiam/missing-run-method',
+        1,
+        1,
+        'The Scene class does not implement a run() method.',
+        'Implement: public async run(): Promise<void> { ... }'
+    );
+}
+
+if (!hasCameraSetup && hasSceneClass) {
+    addDiagnostic(
+        'warning',
+        'retiam/no-camera-setup',
+        1,
+        1,
+        'No camera position configuration detected in the scene.',
+        'Initialize camera: this.camera.position.set([0, 0, 14]);'
+    );
+}
+
+// Compute results
+const errors = diagnostics.filter(d => d.type === 'error');
+const warnings = diagnostics.filter(d => d.type === 'warning');
+const isValid = errors.length === 0;
+
+if (jsonOutput) {
+    const result = {
+        file: targetFile,
+        valid: isValid,
+        summary: {
+            errors: errors.length,
+            warnings: warnings.length,
+            total: diagnostics.length
+        },
+        diagnostics
+    };
+    console.log(JSON.stringify(result, null, 2));
+} else {
+    console.log(`\n🔍 Retiam Scene Linter: ${targetFile}`);
+    console.log('='.repeat(60));
+
+    if (diagnostics.length === 0) {
+        console.log('✅ All checks passed! Scene is syntactically and structurally sound.\n');
+    } else {
+        for (const diag of diagnostics) {
+            const icon = diag.type === 'error' ? '❌ [ERROR]' : '⚠️  [WARN]';
+            console.log(`\n${icon} Line ${diag.line}:${diag.col} (${diag.rule})`);
+            console.log(`   Message:    ${diag.message}`);
+            if (diag.codeSnippet) {
+                console.log(`   Snippet:    ${diag.codeSnippet}`);
+            }
+            if (diag.suggestion) {
+                console.log(`   💡 Fix:     ${diag.suggestion}`);
+            }
+        }
+
+        console.log('\n' + '-'.repeat(60));
+        console.log(`Found ${errors.length} error(s), ${warnings.length} warning(s).`);
+        if (!isValid) {
+            console.log('❌ Scene has critical errors that may prevent proper animation playback.\n');
+        } else {
+            console.log('✨ No critical errors found. Please review the warnings above.\n');
+        }
+    }
+}
+
+process.exit(isValid ? 0 : 1);