nuclie 1.0.0

package/dist/core/errors/hero-errors.js

@@ -0,0 +1,269 @@
+/**
+ * Hero Errors System
+ *
+ * Provides rich, contextual error messages with:
+ * - File chain visualization
+ * - Graph explanation
+ * - Suggested fixes
+ * - Related documentation
+ *
+ * Never show "Build failed" without context.
+ */
+import kleur from 'kleur';
+export class HeroError extends Error {
+    constructor(context) {
+        super(context.message);
+        this.name = 'HeroError';
+        this.context = context;
+    }
+    /**
+     * Format error for display with rich context
+     */
+    format() {
+        const lines = [];
+        const { context } = this;
+        const width = process.stdout.columns || 80;
+        // 1. Header (Minimal & Urgent)
+        lines.push('');
+        lines.push(kleur.bgRed().bold().white(` ${context.code} `) + ' ' + kleur.red(context.message));
+        lines.push('');
+        // 2. Code Frame (The most important part)
+        if (context.file && context.line) {
+            lines.push(kleur.cyan(`╭─[${context.file}:${context.line}:${context.column || 1}]`));
+            try {
+                const fs = require('fs');
+                if (fs.existsSync(context.file)) {
+                    const content = fs.readFileSync(context.file, 'utf-8');
+                    const fileLines = content.split('\n');
+                    const start = Math.max(0, context.line - 3);
+                    const end = Math.min(fileLines.length, context.line + 2);
+                    for (let i = start; i < end; i++) {
+                        const lineNum = i + 1;
+                        const isErrorLine = lineNum === context.line;
+                        const gutter = isErrorLine ? kleur.red(` ${lineNum} │ `) : kleur.dim(` ${lineNum} │ `);
+                        const code = fileLines[i];
+                        if (isErrorLine) {
+                            lines.push(gutter + code);
+                            if (context.column) {
+                                // Add pointer
+                                const padding = ' '.repeat(String(lineNum).length + 3 + context.column - 1);
+                                lines.push(kleur.red(padding + '^'));
+                            }
+                        }
+                        else {
+                            lines.push(gutter + kleur.dim(code));
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                // Ignore code frame errors
+            }
+            lines.push(kleur.cyan('╰────'));
+            lines.push('');
+        }
+        // 3. Causality & Hints
+        if (context.graphExplanation) {
+            lines.push(kleur.yellow('Caused by:'));
+            lines.push(kleur.dim(`  ${context.graphExplanation}`));
+            lines.push('');
+        }
+        if (context.suggestedFix) {
+            lines.push(kleur.green('💡 Suggestion:'));
+            context.suggestedFix.split('\n').forEach(line => {
+                lines.push(`  ${line}`);
+            });
+            lines.push('');
+        }
+        if (context.relatedDocs && context.relatedDocs.length > 0) {
+            lines.push(kleur.blue('📚 Docs: ') + kleur.underline(context.relatedDocs[0]));
+        }
+        lines.push('');
+        return lines.join('\n');
+    }
+    /**
+     * Display error to console
+     */
+    display() {
+        console.error(this.format());
+    }
+}
+/**
+ * Error Registry - 10 High-Impact Errors
+ */
+// 1. Module Not Found
+export function createModuleNotFoundError(modulePath, importedFrom, fileChain) {
+    return new HeroError({
+        code: 'MODULE_NOT_FOUND',
+        message: `Cannot resolve module '${modulePath}'`,
+        file: importedFrom,
+        fileChain,
+        graphExplanation: `The module '${modulePath}' was imported but could not be found in the dependency graph. This breaks the module resolution chain.`,
+        suggestedFix: `1. Check if the file exists at: ${modulePath}\n2. Verify the import path is correct\n3. If it's an npm package, run: npm install ${modulePath}\n4. Check your nuclie.config resolve.alias settings`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/module-resolution',
+            'https://nuclie.dev/docs/troubleshooting#module-not-found'
+        ],
+        severity: 'error'
+    });
+}
+// 2. Circular Dependency Detected
+export function createCircularDependencyError(cycle) {
+    return new HeroError({
+        code: 'CIRCULAR_DEPENDENCY',
+        message: 'Circular dependency detected in module graph',
+        fileChain: cycle,
+        graphExplanation: `A circular dependency creates an infinite loop in the module graph. This can cause runtime errors and unpredictable behavior.`,
+        suggestedFix: `1. Refactor to break the circular dependency\n2. Extract shared code into a separate module\n3. Use dependency injection or lazy loading\n4. Consider using dynamic imports: import('./module')`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/circular-dependencies',
+            'https://nuclie.dev/docs/best-practices#module-design'
+        ],
+        severity: 'error'
+    });
+}
+// 3. CSS Import Failed
+export function createCSSImportError(cssFile, reason, importedFrom) {
+    return new HeroError({
+        code: 'CSS_IMPORT_FAILED',
+        message: `Failed to process CSS file: ${cssFile}`,
+        file: cssFile,
+        fileChain: importedFrom ? [importedFrom, cssFile] : [cssFile],
+        graphExplanation: `CSS files are first-class nodes in Nuclie's dependency graph. This CSS file could not be processed, breaking the graph.`,
+        suggestedFix: `1. Check CSS syntax: ${reason}\n2. Verify PostCSS config if using preprocessors\n3. Check for missing @import files\n4. Run: nuclie verify --explain to diagnose`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/css-handling',
+            'https://nuclie.dev/docs/postcss-integration'
+        ],
+        severity: 'error'
+    });
+}
+// 4. Framework Adapter Missing
+export function createFrameworkAdapterMissingError(framework) {
+    return new HeroError({
+        code: 'FRAMEWORK_ADAPTER_MISSING',
+        message: `Framework adapter not found: ${framework}`,
+        graphExplanation: `Nuclie requires a framework adapter to transform framework-specific code. The adapter for '${framework}' is not installed.`,
+        suggestedFix: `1. Install the adapter: npm install @nuclie/framework-${framework.toLowerCase()}\n2. Add to nuclie.config:\n   import ${framework.toLowerCase()} from '@nuclie/framework-${framework.toLowerCase()}';\n   export default { framework: ${framework.toLowerCase()}() }`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/framework-adapters',
+            `https://nuclie.dev/docs/frameworks/${framework.toLowerCase()}`
+        ],
+        severity: 'error'
+    });
+}
+// 5. Invalid Config
+export function createInvalidConfigError(configPath, validationErrors) {
+    return new HeroError({
+        code: 'INVALID_CONFIG',
+        message: 'Configuration file is invalid',
+        file: configPath,
+        graphExplanation: `The nuclie.config file failed validation. This prevents the build from starting.`,
+        suggestedFix: `Fix the following validation errors:\n${validationErrors.map((e, i) => `${i + 1}. ${e}`).join('\n')}\n\nRun: nuclie verify --explain for detailed diagnostics`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/configuration',
+            'https://nuclie.dev/docs/config-schema'
+        ],
+        severity: 'error'
+    });
+}
+// 6. Build Cache Corrupted
+export function createCacheCorruptedError(cachePath) {
+    return new HeroError({
+        code: 'CACHE_CORRUPTED',
+        message: 'Build cache is corrupted',
+        file: cachePath,
+        graphExplanation: `The SQLite build cache has become corrupted. This can happen due to interrupted builds or disk errors.`,
+        suggestedFix: `1. Delete the cache: rm -rf ${cachePath}\n2. Rebuild: nuclie build\n3. If issue persists, check disk health\n4. Consider disabling cache temporarily: nuclie build --no-cache`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/caching',
+            'https://nuclie.dev/docs/troubleshooting#cache-issues'
+        ],
+        severity: 'warning'
+    });
+}
+// 7. HMR Connection Failed
+export function createHMRConnectionError(port, reason) {
+    return new HeroError({
+        code: 'HMR_CONNECTION_FAILED',
+        message: `Hot Module Replacement connection failed on port ${port}`,
+        graphExplanation: `The HMR WebSocket connection could not be established. This prevents live updates during development.`,
+        suggestedFix: `1. Check if port ${port} is available\n2. Verify firewall settings\n3. Try a different port: nuclie dev --port ${port + 1}\n4. Check browser console for WebSocket errors\n\nReason: ${reason}`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/hmr',
+            'https://nuclie.dev/docs/dev-server#troubleshooting'
+        ],
+        severity: 'warning'
+    });
+}
+// 8. Asset Resolution Failed
+export function createAssetResolutionError(assetPath, importedFrom) {
+    return new HeroError({
+        code: 'ASSET_RESOLUTION_FAILED',
+        message: `Cannot resolve asset: ${assetPath}`,
+        file: importedFrom,
+        fileChain: [importedFrom, assetPath],
+        graphExplanation: `Assets (images, fonts, etc.) are tracked in the dependency graph. This asset could not be found.`,
+        suggestedFix: `1. Check if file exists: ${assetPath}\n2. Verify the path is correct\n3. Check public directory configuration\n4. Ensure file extension is supported`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/assets',
+            'https://nuclie.dev/docs/static-assets'
+        ],
+        severity: 'error'
+    });
+}
+// 9. TypeScript Compilation Error
+export function createTypeScriptError(file, line, column, message, code) {
+    return new HeroError({
+        code: 'TYPESCRIPT_ERROR',
+        message: `TypeScript compilation failed: ${message}`,
+        file,
+        line,
+        column,
+        graphExplanation: `TypeScript type checking failed. While Nuclie uses esbuild for fast transpilation, type errors indicate potential runtime issues.`,
+        suggestedFix: `1. Fix the type error at ${file}:${line}:${column}\n2. Run: npx tsc --noEmit for full type checking\n3. Check tsconfig.json settings\n4. Error code: ${code}`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/typescript',
+            `https://www.typescriptlang.org/docs/handbook/error.html#${code}`
+        ],
+        severity: 'error'
+    });
+}
+// 10. Plugin Hook Error
+export function createPluginHookError(pluginName, hookName, error) {
+    return new HeroError({
+        code: 'PLUGIN_HOOK_ERROR',
+        message: `Plugin '${pluginName}' failed in '${hookName}' hook`,
+        graphExplanation: `A plugin hook threw an error during the build process. This indicates a bug in the plugin or incompatibility.`,
+        suggestedFix: `1. Check plugin version compatibility\n2. Review plugin configuration\n3. Try disabling the plugin temporarily\n4. Report issue to plugin author\n\nOriginal error: ${error.message}`,
+        relatedDocs: [
+            'https://nuclie.dev/docs/plugins',
+            'https://nuclie.dev/docs/plugin-api'
+        ],
+        severity: 'error',
+        stack: error.stack
+    });
+}
+/**
+ * Wrap any error in a HeroError with context
+ */
+export function wrapError(error, context) {
+    if (error instanceof HeroError) {
+        return error;
+    }
+    return new HeroError({
+        code: 'UNKNOWN_ERROR',
+        message: error.message,
+        stack: error.stack,
+        severity: 'error',
+        suggestedFix: 'This is an unexpected error. Please report it to: https://github.com/Avinash-1994/nuclie/issues',
+        relatedDocs: ['https://nuclie.dev/docs/troubleshooting'],
+        ...context
+    });
+}
+/**
+ * Print a Hero Error to the console
+ */
+export function printHeroError(error) {
+    error.display();
+}

package/dist/core/framework-detector.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Framework Detector
+ * Automatically detects which framework(s) are being used in the project
+ */
+export type Framework = 'react' | 'vue' | 'svelte' | 'angular' | 'solid' | 'preact' | 'qwik' | 'lit' | 'astro' | 'next' | 'nuxt' | 'remix' | 'vanilla';
+export interface FrameworkInfo {
+    name: Framework;
+    version?: string;
+    detected: boolean;
+    confidence: number;
+}
+export declare class FrameworkDetector {
+    private root;
+    private packageJson;
+    constructor(root: string);
+    detect(): Promise<FrameworkInfo[]>;
+    detectPrimary(): Promise<Framework>;
+    getFrameworkVersion(framework: Framework): Promise<string | undefined>;
+}
+export declare function detectFramework(root: string): Promise<Framework>;

package/dist/core/framework-detector.js

@@ -0,0 +1,148 @@
+/**
+ * Framework Detector
+ * Automatically detects which framework(s) are being used in the project
+ */
+import fs from 'fs/promises';
+import path from 'path';
+export class FrameworkDetector {
+    constructor(root) {
+        this.root = root;
+    }
+    async detect() {
+        // Read package.json
+        try {
+            const pkgPath = path.join(this.root, 'package.json');
+            const content = await fs.readFile(pkgPath, 'utf-8');
+            this.packageJson = JSON.parse(content);
+        }
+        catch (error) {
+            return [{ name: 'vanilla', detected: true, confidence: 1.0 }];
+        }
+        const frameworks = [];
+        const deps = {
+            ...this.packageJson.dependencies,
+            ...this.packageJson.devDependencies
+        };
+        // Detect frameworks based on dependencies
+        // Meta-frameworks first (they include their base framework)
+        if (deps['next']) {
+            frameworks.push({
+                name: 'next',
+                version: deps['next'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['nuxt']) {
+            frameworks.push({
+                name: 'nuxt',
+                version: deps['nuxt'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['@remix-run/react']) {
+            frameworks.push({
+                name: 'remix',
+                version: deps['@remix-run/react'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['astro']) {
+            frameworks.push({
+                name: 'astro',
+                version: deps['astro'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        // Base frameworks
+        if (deps['react'] && !frameworks.some(f => f.name === 'next' || f.name === 'remix')) {
+            frameworks.push({
+                name: 'react',
+                version: deps['react'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['vue'] && !frameworks.some(f => f.name === 'nuxt')) {
+            frameworks.push({
+                name: 'vue',
+                version: deps['vue'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['svelte']) {
+            frameworks.push({
+                name: 'svelte',
+                version: deps['svelte'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['@angular/core']) {
+            frameworks.push({
+                name: 'angular',
+                version: deps['@angular/core'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['solid-js']) {
+            frameworks.push({
+                name: 'solid',
+                version: deps['solid-js'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['preact']) {
+            frameworks.push({
+                name: 'preact',
+                version: deps['preact'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['qwik'] || deps['@builder.io/qwik']) {
+            frameworks.push({
+                name: 'qwik',
+                version: deps['qwik'] || deps['@builder.io/qwik'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        if (deps['lit']) {
+            frameworks.push({
+                name: 'lit',
+                version: deps['lit'],
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        // If no framework detected, it's vanilla JS/TS
+        if (frameworks.length === 0) {
+            frameworks.push({
+                name: 'vanilla',
+                detected: true,
+                confidence: 1.0
+            });
+        }
+        return frameworks;
+    }
+    async detectPrimary() {
+        const frameworks = await this.detect();
+        // Return the first detected framework (highest priority)
+        return frameworks[0]?.name || 'vanilla';
+    }
+    async getFrameworkVersion(framework) {
+        const frameworks = await this.detect();
+        return frameworks.find(f => f.name === framework)?.version;
+    }
+}
+export async function detectFramework(root) {
+    const detector = new FrameworkDetector(root);
+    return detector.detectPrimary();
+}

package/dist/core/graph/js-graph-analyzer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * JavaScript Graph Analyzer (for benchmarking against Rust)
+ *
+ * Pure TypeScript implementation of graph algorithms
+ * Used to measure performance gains from Rust native module
+ */
+export interface CircularDependency {
+    cycle: string[];
+    entryPoint: string;
+}
+export interface GraphAnalysisResult {
+    hasCycles: boolean;
+    cycles: CircularDependency[];
+    orphanedNodes: string[];
+    entryPoints: string[];
+    totalNodes: number;
+    totalEdges: number;
+}
+export declare class JSGraphAnalyzer {
+    private nodes;
+    addNode(id: string, dependencies: string[]): void;
+    /**
+     * Detect circular dependencies using DFS
+     * Time complexity: O(V + E)
+     */
+    /**
+     * Detect circular dependencies using Iterative DFS
+     * Time complexity: O(V + E)
+     *
+     * Rewritten to be Iterative to avoid Stack Overflow on large graphs.
+     * Complies with "No Recursive Traversal" rule.
+     */
+    detectCycles(): CircularDependency[];
+    /**
+     * Find orphaned nodes using BFS
+     * Time complexity: O(V + E)
+     */
+    findOrphanedNodes(entryPoints: string[]): string[];
+    /**
+     * Topological sort using Kahn's algorithm
+     * Time complexity: O(V + E)
+     */
+    topologicalSort(): string[] | null;
+    /**
+     * Complete graph analysis
+     */
+    analyze(entryPoints: string[]): GraphAnalysisResult;
+    nodeCount(): number;
+    edgeCount(): number;
+    clear(): void;
+}

package/dist/core/graph/js-graph-analyzer.js

@@ -0,0 +1,178 @@
+/**
+ * JavaScript Graph Analyzer (for benchmarking against Rust)
+ *
+ * Pure TypeScript implementation of graph algorithms
+ * Used to measure performance gains from Rust native module
+ */
+export class JSGraphAnalyzer {
+    constructor() {
+        this.nodes = new Map();
+    }
+    addNode(id, dependencies) {
+        this.nodes.set(id, dependencies);
+    }
+    /**
+     * Detect circular dependencies using DFS
+     * Time complexity: O(V + E)
+     */
+    /**
+     * Detect circular dependencies using Iterative DFS
+     * Time complexity: O(V + E)
+     *
+     * Rewritten to be Iterative to avoid Stack Overflow on large graphs.
+     * Complies with "No Recursive Traversal" rule.
+     */
+    detectCycles() {
+        const cycles = [];
+        const visited = new Set();
+        const onStack = new Set();
+        const path = [];
+        // Stack mimics the recursion: { node, childIndex }
+        // Using explicit stack allows scaling to heap limits instead of stack limits
+        const stack = [];
+        for (const startNode of this.nodes.keys()) {
+            if (visited.has(startNode))
+                continue;
+            // Start DFS
+            stack.push({ node: startNode, childIndex: 0 });
+            visited.add(startNode);
+            onStack.add(startNode);
+            path.push(startNode);
+            while (stack.length > 0) {
+                const peek = stack[stack.length - 1];
+                const { node, childIndex } = peek;
+                const deps = this.nodes.get(node) || [];
+                if (childIndex < deps.length) {
+                    // Process next child
+                    peek.childIndex++; // Move to next child for when we return
+                    const dep = deps[childIndex];
+                    if (!visited.has(dep)) {
+                        visited.add(dep);
+                        onStack.add(dep);
+                        path.push(dep);
+                        stack.push({ node: dep, childIndex: 0 });
+                    }
+                    else if (onStack.has(dep)) {
+                        // Cycle detected
+                        const cycleStart = path.indexOf(dep);
+                        if (cycleStart !== -1) {
+                            cycles.push({
+                                cycle: path.slice(cycleStart),
+                                entryPoint: dep
+                            });
+                        }
+                    }
+                }
+                else {
+                    // Finished processing all children
+                    onStack.delete(node);
+                    path.pop();
+                    stack.pop();
+                }
+            }
+        }
+        return cycles;
+    }
+    // Removed recursive dfsDetectCycle helper
+    /**
+     * Find orphaned nodes using BFS
+     * Time complexity: O(V + E)
+     */
+    findOrphanedNodes(entryPoints) {
+        const reachable = new Set();
+        const queue = [...entryPoints];
+        // BFS from all entry points
+        for (const entry of entryPoints) {
+            reachable.add(entry);
+        }
+        while (queue.length > 0) {
+            const node = queue.shift();
+            const deps = this.nodes.get(node) || [];
+            for (const dep of deps) {
+                if (!reachable.has(dep)) {
+                    reachable.add(dep);
+                    queue.push(dep);
+                }
+            }
+        }
+        // Find orphaned nodes
+        const orphaned = [];
+        for (const node of this.nodes.keys()) {
+            if (!reachable.has(node)) {
+                orphaned.push(node);
+            }
+        }
+        return orphaned;
+    }
+    /**
+     * Topological sort using Kahn's algorithm
+     * Time complexity: O(V + E)
+     */
+    topologicalSort() {
+        const inDegree = new Map();
+        const result = [];
+        const queue = [];
+        // Calculate in-degrees
+        for (const node of this.nodes.keys()) {
+            inDegree.set(node, 0);
+        }
+        for (const deps of this.nodes.values()) {
+            for (const dep of deps) {
+                inDegree.set(dep, (inDegree.get(dep) || 0) + 1);
+            }
+        }
+        // Find nodes with in-degree 0
+        for (const [node, degree] of inDegree.entries()) {
+            if (degree === 0) {
+                queue.push(node);
+            }
+        }
+        // Process nodes
+        while (queue.length > 0) {
+            const node = queue.shift();
+            result.push(node);
+            const deps = this.nodes.get(node) || [];
+            for (const dep of deps) {
+                const degree = inDegree.get(dep) - 1;
+                inDegree.set(dep, degree);
+                if (degree === 0) {
+                    queue.push(dep);
+                }
+            }
+        }
+        // If result doesn't contain all nodes, there's a cycle
+        return result.length === this.nodes.size ? result : null;
+    }
+    /**
+     * Complete graph analysis
+     */
+    analyze(entryPoints) {
+        const cycles = this.detectCycles();
+        const orphanedNodes = this.findOrphanedNodes(entryPoints);
+        let totalEdges = 0;
+        for (const deps of this.nodes.values()) {
+            totalEdges += deps.length;
+        }
+        return {
+            hasCycles: cycles.length > 0,
+            cycles,
+            orphanedNodes,
+            entryPoints,
+            totalNodes: this.nodes.size,
+            totalEdges
+        };
+    }
+    nodeCount() {
+        return this.nodes.size;
+    }
+    edgeCount() {
+        let count = 0;
+        for (const deps of this.nodes.values()) {
+            count += deps.length;
+        }
+        return count;
+    }
+    clear() {
+        this.nodes.clear();
+    }
+}

package/dist/core/graph/serializer.d.ts

@@ -0,0 +1,7 @@
+export declare class ShortIdMap {
+    private map;
+    private counter;
+    get(path: string, isProduction?: boolean): string;
+    toRuntime(): string;
+    getInverse(shortId: string): string | undefined;
+}