nuclie 1.0.0

package/dist/core/engine/config.js

@@ -0,0 +1,158 @@
+/**
+ * Engine Configuration and Initialization
+ *
+ * @internal - This is part of the core engine and NOT a public API.
+ */
+import { InMemoryBuildCache, PersistentBuildCache } from './cache.js';
+import { DependencyGraph } from '../../resolve/graph.js';
+import { explainReporter } from './events.js';
+import { canonicalHash } from './hash.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { PluginManager } from '../plugins/manager.js';
+import { getInfrastructurePreset } from '../../presets/infrastructure.js';
+// Stage 1: Initialization
+export async function initBuild(userConfig, mode, rootDir) {
+    explainReporter.report('init', 'initialize', 'Starting build initialization');
+    const engine = {
+        name: "Nuclie",
+        version: "0.1.3", // Should normally come from package.json
+        buildTime: new Date().toISOString()
+    };
+    const config = resolveConfig(userConfig, rootDir, mode);
+    const useCache = userConfig.cache !== false;
+    const cache = useCache ? new PersistentBuildCache(rootDir) : new InMemoryBuildCache();
+    const pluginManager = new PluginManager();
+    // 1. Register Infrastructure (Phase B2)
+    const infraPlugins = getInfrastructurePreset(rootDir, config.outputDir, config);
+    for (const p of infraPlugins) {
+        await pluginManager.register(p);
+    }
+    // 2. Register User Plugins (Phase F2)
+    if (userConfig.plugins) {
+        for (const p of userConfig.plugins) {
+            await pluginManager.register(p);
+        }
+    }
+    explainReporter.report('init', 'config_resolved', 'Config frozen', { config });
+    return {
+        engine,
+        mode,
+        rootDir,
+        env: process.env,
+        target: userConfig.platform || 'browser',
+        graph: new DependencyGraph(), // Empty initially
+        graphHash: '', // Placeholder
+        cache,
+        config,
+        pluginManager
+    };
+}
+function resolveConfig(userConfig, rootDir, mode) {
+    const sourcemap = userConfig.build?.sourcemap;
+    return {
+        entryPoints: userConfig.entry,
+        outputDir: path.isAbsolute(userConfig.outDir || 'dist')
+            ? userConfig.outDir
+            : path.resolve(rootDir, userConfig.outDir || 'dist'),
+        publicPath: '/',
+        splittingStrategy: userConfig.build?.splitting ? 'module' : 'route',
+        hashing: 'content',
+        sourceMaps: sourcemap === 'none' ? false : (sourcemap === undefined ? 'external' : sourcemap),
+        minify: userConfig.build?.minify ?? (mode === 'production' || mode === 'build'),
+        cssModules: userConfig.build?.cssModules ?? false,
+        federation: userConfig.federation,
+    };
+}
+// Stage 2: Input Fingerprinting
+export async function computeInputFingerprint(ctx) {
+    explainReporter.report('fingerprint', 'start', 'Computing input fingerprint');
+    // 1. Hash Config
+    // Normalize absolute paths to ensure deterministic hash across environments (CI vs Local)
+    const normalizedConfig = {
+        ...ctx.config,
+        outputDir: path.relative(ctx.rootDir, ctx.config.outputDir)
+    };
+    const configHash = canonicalHash(normalizedConfig);
+    // 2. Hash Engine
+    // We strictly use version/name, NOT buildTime for semantic hash
+    const engineFingerprint = canonicalHash({ name: ctx.engine.name, version: ctx.engine.version });
+    // 3. Hash Source Files (Entry points initially, full graph later? 
+    // SPEC SAYS: "Hash all source files". 
+    // However, we haven't built the graph yet in the main flow? 
+    // Actually Stage 2 is "Input Fingerprinting", Stage 3 is "Attach Graph".
+    // Usually we need the graph to know *which* files are source files.
+    // If the spec implies we fingerprint the *entry* concept or the *entire repo*, 
+    // let's assume for now we fingerprint the Configuration + Environment + Entry file paths.
+    // Real source content hashing usually happens *during* graph build or *after* graph build.
+    // BUT the spec says Stage 2 -> Stage 3. This implies we might scan the directory or just fingerprint known inputs.
+    // Let's fingerprint the config and entry points for now. The graph content hash comes later.
+    // Correction: In a pure build system, "Inputs" are files. If we don't have the graph, we don't know the inputs.
+    // Maybe "InputFingerprint" at this stage is just "Configuration & Environment"?
+    // Or maybe we treat *all* files in src as inputs? 
+    // Let's stick to Config + Entry Paths for the 'Input' definition at this precise millisecond.
+    // We will update it if we move this stage after graph. 
+    // Wait, the spec says: "Hash all source files" inside `computeInputFingerprint`.
+    // Valid implementation: We might need to walk the tree *now* or defer this until after graph?
+    // Spec Order: Init -> Fingerprint -> Attach Graph.
+    // This implies we fingerprint based on *what we know*. 
+    // Let's fingerprint the Entry Files themselves if they exist.
+    // 3. Hash Source Files (High-Parallelism Scan)
+    const excludes = new Set(['node_modules', '.git', 'dist', 'build_output', 'coverage', '.DS_Store', '.nuclie_cache']);
+    if (ctx.config.outputDir)
+        excludes.add(path.basename(ctx.config.outputDir));
+    const sourceFiles = [];
+    const tasks = [];
+    async function scan(dir) {
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const dirent of entries) {
+            if (excludes.has(dirent.name))
+                continue;
+            const fullPath = path.join(dir, dirent.name);
+            if (dirent.isDirectory()) {
+                tasks.push(scan(fullPath));
+            }
+            else if (/\.(ts|tsx|js|jsx|json|css|html|vue|svelte)$/i.test(dirent.name)) {
+                tasks.push((async () => {
+                    const content = await fs.readFile(fullPath);
+                    sourceFiles.push({ path: path.relative(ctx.rootDir, fullPath), contentHash: canonicalHash(content) });
+                })());
+            }
+        }
+    }
+    await scan(ctx.rootDir);
+    await Promise.all(tasks);
+    sourceFiles.sort((a, b) => a.path.localeCompare(b.path));
+    const inputsToHash = {
+        config: configHash,
+        engine: engineFingerprint,
+        sources: sourceFiles
+    };
+    const inputHash = canonicalHash(inputsToHash);
+    explainReporter.report('fingerprint', 'computed', 'Input fingerprint ready', { inputHash });
+    return {
+        sourceFiles,
+        configHash,
+        engineFingerprint,
+        inputHash
+    };
+}
+// Stage 3: Attach Graph
+export function attachGraph(ctx, graph) {
+    explainReporter.report('graph', 'attached', 'Dependency graph attached');
+    // Compute Graph Hash
+    const nodesObj = {};
+    for (const [key, val] of graph.nodes.entries()) {
+        const deps = val.edges.map(e => e.to).sort();
+        nodesObj[key] = {
+            id: val.id,
+            deps: deps
+        };
+    }
+    const graphHash = canonicalHash(nodesObj);
+    return {
+        ...ctx,
+        graph,
+        graphHash
+    };
+}

package/dist/core/engine/emit.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Engine Emission and Fingerprinting Stage
+ *
+ * @internal - This handles FS writes and build auditing. Not for public use.
+ */
+import { BuildArtifact, BuildContext, BuildFingerprint, InputFingerprint, BuildPlan } from './types.js';
+export declare function emit(artifacts: BuildArtifact[], ctx: BuildContext): Promise<BuildArtifact[]>;
+export declare function computeBuildFingerprint(inputFingerprint: InputFingerprint, artifacts: BuildArtifact[], plan: BuildPlan, ctx: BuildContext): BuildFingerprint;

package/dist/core/engine/emit.js

@@ -0,0 +1,60 @@
+/**
+ * Engine Emission and Fingerprinting Stage
+ *
+ * @internal - This handles FS writes and build auditing. Not for public use.
+ */
+import { explainReporter } from './events.js';
+import { canonicalHash } from './hash.js';
+import fs from 'fs/promises';
+import path from 'path';
+// Stage 8: Emit Artifacts
+export async function emit(artifacts, ctx) {
+    explainReporter.report('emit', 'start', 'Starting emit phase');
+    await fs.mkdir(ctx.config.outputDir, { recursive: true });
+    const emitted = [];
+    for (const artifact of artifacts) {
+        if (artifact.source === undefined)
+            continue;
+        const outputPath = path.join(ctx.config.outputDir, artifact.fileName);
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+        explainReporter.report('emit', 'writing', `Writing artifact: ${outputPath}`);
+        await fs.writeFile(outputPath, artifact.source);
+        // Final sanity check of what was written vs what was in memory?
+        // Skipped for performance.
+        emitted.push(artifact);
+    }
+    // Write build-manifest.json (Phase 4.3)
+    const manifest = {
+        timestamp: new Date().toISOString(),
+        target: ctx.target,
+        artifacts: emitted.map(a => ({
+            fileName: a.fileName,
+            hash: a.id,
+            type: a.type
+        }))
+    };
+    await fs.writeFile(path.join(ctx.config.outputDir, 'build-manifest.json'), JSON.stringify(manifest, null, 2));
+    // Write Explain Log
+    const explainLogPath = path.join(ctx.config.outputDir, 'build-explain.json');
+    await fs.writeFile(explainLogPath, JSON.stringify(explainReporter.getEvents(), null, 2));
+    explainReporter.report('emit', 'complete', `Emitted ${emitted.length} artifacts`);
+    return emitted;
+}
+// Stage 9: Output Fingerprinting
+export function computeBuildFingerprint(inputFingerprint, artifacts, plan, ctx) {
+    explainReporter.report('audit', 'start', 'Computing build fingerprint');
+    // Output Hash = Hash of all artifact IDs (content hashes) in order
+    const outputIds = artifacts.map(a => a.id);
+    const outputHash = canonicalHash(outputIds);
+    const fingerprint = {
+        engineVersion: ctx.engine.version,
+        graphHash: ctx.graphHash,
+        planHash: plan.planId,
+        inputHash: inputFingerprint.inputHash,
+        outputHash: outputHash,
+        target: ctx.target,
+        buildTime: new Date().toISOString()
+    };
+    explainReporter.report('audit', 'complete', 'Build fingerprint computed', { outputHash: fingerprint.outputHash });
+    return fingerprint;
+}

package/dist/core/engine/events.d.ts

@@ -0,0 +1,13 @@
+import { ExplainEvent } from './types.js';
+declare class ExplainReporter {
+    private events;
+    record(event: ExplainEvent): void;
+    getEvents(): ExplainEvent[];
+    clear(): void;
+    report(stage: string, decision: string, reason: string, data?: any): void;
+    private marks;
+    startMark(name: string): void;
+    endMark(name: string, stage?: string): void;
+}
+export declare const explainReporter: ExplainReporter;
+export {};

package/dist/core/engine/events.js

@@ -0,0 +1,35 @@
+class ExplainReporter {
+    constructor() {
+        this.events = [];
+        // Performance profiling
+        this.marks = new Map();
+    }
+    record(event) {
+        this.events.push({
+            ...event,
+            timestamp: event.timestamp || Date.now()
+        });
+    }
+    getEvents() {
+        return this.events;
+    }
+    clear() {
+        this.events = [];
+    }
+    // Helper for structured logging
+    report(stage, decision, reason, data) {
+        this.record({ stage, decision, reason, data, timestamp: Date.now() });
+    }
+    startMark(name) {
+        this.marks.set(name, performance.now());
+    }
+    endMark(name, stage = 'profile') {
+        const start = this.marks.get(name);
+        if (start !== undefined) {
+            const duration = performance.now() - start;
+            this.report(stage, 'performance', `${name} took ${duration.toFixed(2)}ms`, { duration });
+            this.marks.delete(name);
+        }
+    }
+}
+export const explainReporter = new ExplainReporter();

package/dist/core/engine/execute.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Engine Execution Stage - Optimized (v2.0.2 World Domination)
+ */
+import { BuildContext, BuildPlan, BuildArtifact, ExecutionPlan } from './types.js';
+export declare function executeParallel(execPlan: ExecutionPlan, buildPlan: BuildPlan, ctx: BuildContext): Promise<BuildArtifact[]>;

package/dist/core/engine/execute.js

@@ -0,0 +1,226 @@
+/**
+ * Engine Execution Stage - Optimized (v2.0.2 World Domination)
+ */
+import { explainReporter } from './events.js';
+import { canonicalHash } from './hash.js';
+import fs from 'fs/promises';
+import path from 'path';
+import { generateModuleId, normalizePath } from '../../resolve/utils.js';
+import { Transformer } from '../transform/transformer.js';
+import { GlobalOptimizer } from '../build/globalOptimizer.js';
+import { ShortIdMap } from '../graph/serializer.js';
+export async function executeParallel(execPlan, buildPlan, ctx) {
+    explainReporter.report('execute', 'start', 'Starting optimized execution');
+    const artifacts = [];
+    const artifactMap = new Map();
+    const isProd = ctx.mode === 'production' || ctx.mode === 'build';
+    // Phase 2: Short Stable IDs (Persist across chunks for consistency)
+    const shortIdMap = new ShortIdMap();
+    const globalOptimizer = new GlobalOptimizer();
+    for (const group of execPlan.parallelGroups) {
+        const tasks = group.map(async (chunkId) => {
+            const chunk = buildPlan.chunks.find(c => c.id === chunkId);
+            if (!chunk)
+                return;
+            const pipelineHash = ctx.pluginManager.getPipelineHash();
+            const moduleHashes = {};
+            for (const modId of chunk.modules) {
+                const node = ctx.graph.nodes.get(modId);
+                if (node)
+                    moduleHashes[modId] = node.contentHash;
+            }
+            const chunkKey = canonicalHash({
+                id: chunk.id,
+                moduleHashes,
+                configHash: canonicalHash(ctx.config),
+                pipelineHash,
+                mode: ctx.mode
+            });
+            // CACHE CHECK
+            const cached = await ctx.cache.get(chunkKey);
+            if (cached) {
+                artifactMap.set(chunk.id, cached.artifact);
+                return;
+            }
+            let bundleContent = '';
+            const isCss = chunk.id.endsWith('_css');
+            // Phase 1: ULTRA-CONDENSED RUNTIME
+            if (!isCss) {
+                bundleContent += isProd
+                    ? `(function(g){const m={};g.d=(i,f)=>m[i]=f;g.r=i=>{if(m[i].z)return m[i].z;const o={e:{}};m[i](o,o.e,g.r);return m[i].z=o.e}})(globalThis);\n`
+                    : `/* Nuclie Runtime */\n(function(g){const m={};g.d=(i,f)=>m[i]=f;g.r=i=>{if(m[i].z)return m[i].z;const o={e:{}};m[i](o,o.e,g.r);return m[i].z=o.e}})(globalThis);\n`;
+            }
+            const artifactModules = [];
+            const transformer = new Transformer();
+            const moduleResults = new Map();
+            const pendingTransform = [];
+            // Parallel Load (Respecting Plugins)
+            await Promise.all(chunk.modules.map(async (modId) => {
+                const node = ctx.graph.nodes.get(modId);
+                const path = node?.path || modId;
+                // Try Plugin LOAD hook first (for assets, etc.)
+                const loadResult = await ctx.pluginManager.runHook('load', { id: modId, path }, ctx);
+                let content;
+                if (loadResult && loadResult.code !== undefined) {
+                    content = loadResult.code;
+                }
+                else {
+                    content = await fs.readFile(path, 'utf-8');
+                }
+                pendingTransform.push({ id: modId, path, content });
+            }));
+            // Phase 3: NATIVE BATCH (SWC Fix applied in transform.rs)
+            if (pendingTransform.length > 0) {
+                const batchResults = await transformer.batchTransform(pendingTransform, ctx);
+                for (const res of batchResults) {
+                    const p = pendingTransform.find(x => x.id === res.id);
+                    moduleResults.set(res.id, { code: res.code, originalSize: Buffer.byteLength(p.content) });
+                }
+            }
+            // Phase 3.5: TREE SHAKING (Production Only - Before Bundling)
+            if (isProd && moduleResults.size > 0) {
+                const { AutoFixEngine } = await import('../../fix/ast-transforms.js');
+                const autoFix = new AutoFixEngine();
+                // Collect modules with REAL paths from dependency graph
+                const modulesForShaking = new Map();
+                const idToPath = new Map();
+                for (const [modId, result] of moduleResults) {
+                    // Get actual file path from graph
+                    const node = ctx.graph.nodes.get(modId);
+                    if (node && node.path) {
+                        modulesForShaking.set(node.path, result.code);
+                        idToPath.set(modId, node.path);
+                    }
+                }
+                if (modulesForShaking.size > 0) {
+                    // Perform tree shaking with real paths
+                    const shakenResults = autoFix.treeShake(modulesForShaking);
+                    // Apply shaken code back to moduleResults using ID mapping
+                    for (const [modId, result] of moduleResults) {
+                        const realPath = idToPath.get(modId);
+                        if (realPath) {
+                            const shakenResult = shakenResults.get(realPath);
+                            if (shakenResult?.success && shakenResult.code) {
+                                const savings = result.code.length - shakenResult.code.length;
+                                if (savings > 0) {
+                                    moduleResults.set(modId, {
+                                        code: shakenResult.code,
+                                        originalSize: result.originalSize
+                                    });
+                                    explainReporter.report('execute', 'tree-shake', `${realPath}: Removed ${shakenResult.changes.length} unused exports, saved ${savings} bytes`);
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            // Phase 2: Assemble with Short IDs
+            for (const modId of chunk.modules) {
+                const res = moduleResults.get(modId);
+                if (!res)
+                    continue;
+                const shortId = shortIdMap.get(modId, isProd);
+                artifactModules.push({ id: modId, shortId, size: res.code.length, originalSize: res.originalSize });
+                if (isCss) {
+                    bundleContent += `\n/* ${modId} */\n${res.code}`;
+                }
+                else {
+                    // Convert any remaining ESM import statements to require calls
+                    // This handles external libraries that may have hash-based imports
+                    let moduleCode = res.code;
+                    // Pattern: import React, { Suspense } from "hash16chars"
+                    moduleCode = moduleCode.replace(/\bimport\s+(\w+)\s*,\s*\{([^}]+)\}\s+from\s+["']([a-f0-9]{16})["'];?/g, (match, defaultImport, namedImports, hash) => {
+                        return `const ${defaultImport} = require("${hash}"); const {${namedImports}} = require("${hash}");`;
+                    });
+                    // Pattern: import { x, y } from "hash16chars"
+                    moduleCode = moduleCode.replace(/\bimport\s+\{([^}]+)\}\s+from\s+["']([a-f0-9]{16})["'];?/g, 'const {$1} = require("$2");');
+                    // Pattern: import x from "hash16chars"
+                    moduleCode = moduleCode.replace(/\bimport\s+(\w+)\s+from\s+["']([a-f0-9]{16})["'];?/g, 'const $1 = require("$2");');
+                    // Pattern: import * as x from "hash16chars"
+                    moduleCode = moduleCode.replace(/\bimport\s+\*\s+as\s+(\w+)\s+from\s+["']([a-f0-9]{16})["'];?/g, 'const $1 = require("$2");');
+                    // Pattern: import "hash16chars"
+                    moduleCode = moduleCode.replace(/\bimport\s+["']([a-f0-9]{16})["'];?/g, 'require("$1");');
+                    // Always use 'globalThis.d' as defined in condensed runtime
+                    bundleContent += `\nglobalThis.d("${shortId}",function(module,exports,require,h){\n${moduleCode}\n});`;
+                }
+            }
+            // Entry Execution
+            if (!isCss && chunk.entry) {
+                const absEntry = path.isAbsolute(chunk.entry)
+                    ? chunk.entry
+                    : path.resolve(ctx.rootDir, chunk.entry);
+                const entryId = generateModuleId('file', normalizePath(absEntry), ctx.rootDir);
+                const shortEntryId = shortIdMap.get(entryId, isProd);
+                bundleContent += `\n\nglobalThis.r("${shortEntryId}");`;
+            }
+            const artifact = {
+                id: canonicalHash(bundleContent).substring(0, 16),
+                type: isCss ? 'css' : 'js',
+                fileName: chunk.outputName,
+                dependencies: [...chunk.modules],
+                source: bundleContent,
+                modules: artifactModules
+            };
+            // Generate source map if enabled
+            if (!isCss && ctx.config.sourceMaps) {
+                const sourceMapContent = {
+                    version: 3,
+                    sources: chunk.modules.map(modId => {
+                        const node = ctx.graph.nodes.get(modId);
+                        return node?.path || modId;
+                    }),
+                    names: [],
+                    mappings: '', // Basic mapping - can be enhanced later
+                    file: chunk.outputName
+                };
+                const sourceMapJson = JSON.stringify(sourceMapContent);
+                if (ctx.config.sourceMaps === 'inline') {
+                    // Inline source map
+                    artifact.source += `\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(sourceMapJson).toString('base64')}`;
+                }
+                else if (ctx.config.sourceMaps === 'external' || ctx.config.sourceMaps === true) {
+                    // External source map file
+                    const mapFileName = chunk.outputName + '.map';
+                    artifact.source += `\n//# sourceMappingURL=${mapFileName}`;
+                    // Create separate map artifact
+                    const mapArtifact = {
+                        id: canonicalHash(sourceMapJson).substring(0, 16),
+                        type: 'map',
+                        fileName: mapFileName,
+                        dependencies: [],
+                        source: sourceMapJson
+                    };
+                    artifactMap.set(chunk.id + '_map', mapArtifact);
+                }
+                // 'hidden' mode: generate map but don't add reference
+            }
+            ctx.cache.set(chunkKey, { hash: chunkKey, artifact });
+            artifactMap.set(chunk.id, artifact);
+        });
+        await Promise.all(tasks);
+    }
+    // Process Final Order
+    for (const id of buildPlan.executionOrder) {
+        const art = artifactMap.get(id);
+        if (art)
+            artifacts.push(art);
+    }
+    // Phase 1: GLOBAL NATIVE MINIFICATION
+    if (isProd) {
+        await globalOptimizer.optimize(artifacts);
+    }
+    // Assets
+    for (const asset of buildPlan.assets) {
+        const node = ctx.graph.nodes.get(asset.id);
+        if (node) {
+            artifacts.push({
+                id: node.contentHash,
+                type: 'asset',
+                fileName: asset.outputName,
+                dependencies: [],
+                source: await fs.readFile(node.path)
+            });
+        }
+    }
+    return artifacts;
+}

package/dist/core/engine/hash.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Single Source of Truth for Hashing
+ *
+ * Guarantees:
+ * - Deterministic output via canonical stringify
+ * - Ultra-fast hashing via Native XXH3 (Phase 4.2)
+ */
+export declare function canonicalHash(value: unknown): string;

package/dist/core/engine/hash.js

@@ -0,0 +1,39 @@
+import { fastHash } from '../../native/index.js';
+/**
+ * Single Source of Truth for Hashing
+ *
+ * Guarantees:
+ * - Deterministic output via canonical stringify
+ * - Ultra-fast hashing via Native XXH3 (Phase 4.2)
+ */
+export function canonicalHash(value) {
+    const canonicalString = stableStringify(value);
+    return fastHash(canonicalString);
+}
+function stableStringify(value) {
+    if (value === null || value === undefined) {
+        return String(value);
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (typeof value === 'string') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    if (typeof value === 'object') {
+        const keys = Object.keys(value).sort();
+        const parts = keys.map(k => {
+            const v = value[k];
+            // Skip undefined values to match JSON behavior or keep them unique?
+            // Usually explicit is better for hashing, but let's stick to standard strictness.
+            if (v === undefined)
+                return '';
+            return `${JSON.stringify(k)}:${stableStringify(v)}`;
+        }).filter(x => x !== '');
+        return '{' + parts.join(',') + '}';
+    }
+    return String(value);
+}

package/dist/core/engine/index.d.ts

@@ -0,0 +1,49 @@
+import { DependencyGraph } from '../../resolve/graph.js';
+import { BuildConfig } from '../../config/index.js';
+import { BuildMode } from './types.js';
+/**
+ * Core Build Engine
+ *
+ * PUBLIC: The main orchestrator for the Nuclie build pipeline.
+ * Use this class to run builds programmatically.
+ *
+ * @public
+ */
+export declare class CoreBuildEngine {
+    /** @internal */
+    private latestGraph;
+    /** @internal */
+    private ctx;
+    /** @public */
+    getGraph(): DependencyGraph | null;
+    /**
+     * Incremental Invalidation (Phase 10)
+     */
+    invalidateFile(filePath: string): Promise<void>;
+    /**
+     * Shutdown and cleanup resources
+     */
+    close(): Promise<void>;
+    /**
+     * Main Entry Point for the Build Engine (Pipeline Orchestrator)
+     */
+    run(userConfig: BuildConfig, mode: BuildMode | undefined, rootDir: string, changedFiles?: string[]): Promise<{
+        success: boolean;
+        fingerprint: import("./types.js").BuildFingerprint;
+        artifacts: import("./types.js").BuildArtifact[];
+        events: import("./types.js").ExplainEvent[];
+        pluginMetrics: any;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: {
+            message: any;
+            code: any;
+            stage: any;
+        };
+        events: import("./types.js").ExplainEvent[];
+        fingerprint?: undefined;
+        artifacts?: undefined;
+        pluginMetrics?: undefined;
+    }>;
+}