@ace-sdk/core 2.0.1 → 2.1.0

package/dist/services/bootstrap-stream.js

@@ -0,0 +1,261 @@
+/**
+ * Bootstrap Streaming Client
+ *
+ * Connects to server SSE endpoint for streaming bootstrap progress.
+ * Handles event parsing, timeout, and error recovery.
+ *
+ * Updated to match ACE Server v3.13.0 response format.
+ *
+ * @package @ace-sdk/core
+ */
+import { isTerminalEvent, isDoneEvent, isErrorEvent } from '../types/bootstrap-events.js';
+// =============================================================================
+// Bootstrap Stream Function
+// =============================================================================
+/**
+ * Stream bootstrap progress from ACE Server
+ *
+ * Connects to the server's SSE endpoint and receives progress updates
+ * as the bootstrap processes code blocks.
+ *
+ * @param options - Bootstrap streaming options
+ * @returns Promise that resolves when bootstrap completes or fails
+ *
+ * @example
+ * ```typescript
+ * const result = await bootstrapWithStreaming({
+ *   serverUrl: 'https://ace-api.code-engine.app',
+ *   orgId: 'myorg',
+ *   projectId: 'myproject',
+ *   mode: 'hybrid',
+ *   codeBlocks: ['function foo() { ... }', '// STRATEGY: Use DI'],
+ *   onEvent: (event) => {
+ *     console.log(`[${event.stage}] ${event.message}`);
+ *     if (event.stage === 'done') {
+ *       const stats = event.data as DoneStageData;
+ *       console.log(`Patterns: ${stats.patterns_extracted}`);
+ *     }
+ *   }
+ * });
+ *
+ * if (result.success) {
+ *   console.log(`Bootstrap complete: ${result.playbook?.totalPatterns} patterns`);
+ * }
+ * ```
+ */
+export async function bootstrapWithStreaming(options) {
+    const { serverUrl, orgId, projectId, mode = 'hybrid', codeBlocks, metadata, projectDNA, apiToken, onEvent, onError, timeout = 120000, verbosity = 'compact' } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    let result = { success: false };
+    try {
+        // Build request headers
+        const headers = {
+            'Content-Type': 'application/json',
+            'Accept': 'text/event-stream',
+            'X-ACE-Org': orgId,
+            'X-ACE-Project': projectId
+        };
+        if (apiToken) {
+            headers['Authorization'] = `Bearer ${apiToken}`;
+        }
+        // Build request body (matches server v3.13.0 BootstrapStreamRequest)
+        const body = JSON.stringify({
+            mode,
+            code_blocks: codeBlocks,
+            metadata: metadata || {
+                project_dna: projectDNA
+            },
+            verbosity
+        });
+        // Make streaming request
+        const response = await fetch(`${serverUrl}/bootstrap/stream`, {
+            method: 'POST',
+            headers,
+            body,
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Bootstrap request failed: ${response.status} ${response.statusText}`);
+        }
+        // Get response body reader
+        const reader = response.body?.getReader();
+        const decoder = new TextDecoder();
+        if (!reader) {
+            throw new Error('No response body available');
+        }
+        let buffer = '';
+        // Read SSE stream
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            // Append chunk to buffer
+            buffer += decoder.decode(value, { stream: true });
+            // Parse complete lines from buffer
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || ''; // Keep incomplete line in buffer
+            for (const line of lines) {
+                // Skip empty lines and comments
+                if (!line || line.startsWith(':'))
+                    continue;
+                // Parse SSE data line
+                if (line.startsWith('data: ')) {
+                    const json = line.slice(6);
+                    try {
+                        const event = JSON.parse(json);
+                        // Call user's event handler
+                        onEvent(event);
+                        // Check for terminal events
+                        if (isTerminalEvent(event)) {
+                            if (isDoneEvent(event)) {
+                                const data = event.data;
+                                result = {
+                                    success: data.success,
+                                    statistics: data.bootstrap_statistics,
+                                    playbook: {
+                                        totalPatterns: data.patterns_extracted,
+                                        bySection: data.bootstrap_statistics.by_section
+                                    },
+                                    processingTime: data.analysis_time_seconds
+                                };
+                            }
+                            else if (isErrorEvent(event)) {
+                                const data = event.data;
+                                result = {
+                                    success: false,
+                                    error: {
+                                        code: data.error_code,
+                                        message: data.message,
+                                        retryable: data.retryable
+                                    }
+                                };
+                            }
+                            return result;
+                        }
+                    }
+                    catch (parseError) {
+                        console.warn('Failed to parse SSE event:', json, parseError);
+                    }
+                }
+            }
+        }
+        // Stream ended without terminal event
+        if (!result.success && !result.error) {
+            result = {
+                success: false,
+                error: {
+                    code: 'STREAM_ENDED',
+                    message: 'Stream ended without completion or error event',
+                    retryable: true
+                }
+            };
+        }
+        return result;
+    }
+    catch (error) {
+        const err = error;
+        // Handle abort (timeout)
+        if (err.name === 'AbortError') {
+            result = {
+                success: false,
+                error: {
+                    code: 'TIMEOUT',
+                    message: `Bootstrap timed out after ${timeout}ms`,
+                    retryable: true
+                }
+            };
+        }
+        else {
+            result = {
+                success: false,
+                error: {
+                    code: 'NETWORK_ERROR',
+                    message: err.message,
+                    retryable: true
+                }
+            };
+        }
+        // Call error handler if provided
+        if (onError) {
+            onError(err);
+        }
+        return result;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+// =============================================================================
+// Fallback: Non-Streaming Bootstrap
+// =============================================================================
+/**
+ * Non-streaming bootstrap fallback
+ *
+ * For servers that don't support SSE streaming, this function
+ * makes a regular POST request and waits for the response.
+ *
+ * @param options - Bootstrap options (same as streaming but without onEvent)
+ * @returns Promise that resolves with bootstrap result
+ */
+export async function bootstrapWithoutStreaming(options) {
+    const { serverUrl, orgId, projectId, mode = 'hybrid', codeBlocks, metadata, projectDNA, apiToken, onError, timeout = 120000 } = options;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-ACE-Org': orgId,
+            'X-ACE-Project': projectId
+        };
+        if (apiToken) {
+            headers['Authorization'] = `Bearer ${apiToken}`;
+        }
+        const body = JSON.stringify({
+            mode,
+            code_blocks: codeBlocks,
+            metadata: metadata || {
+                project_dna: projectDNA
+            }
+        });
+        const response = await fetch(`${serverUrl}/bootstrap`, {
+            method: 'POST',
+            headers,
+            body,
+            signal: controller.signal
+        });
+        if (!response.ok) {
+            throw new Error(`Bootstrap request failed: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        // Handle both old and new response formats
+        const totalPatterns = data.patterns_extracted || data.total_patterns || 0;
+        const bySection = data.bootstrap_statistics?.by_section || data.by_section || {};
+        return {
+            success: true,
+            statistics: data.bootstrap_statistics,
+            playbook: {
+                totalPatterns,
+                bySection
+            }
+        };
+    }
+    catch (error) {
+        const err = error;
+        if (onError) {
+            onError(err);
+        }
+        return {
+            success: false,
+            error: {
+                code: err.name === 'AbortError' ? 'TIMEOUT' : 'NETWORK_ERROR',
+                message: err.message,
+                retryable: true
+            }
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+//# sourceMappingURL=bootstrap-stream.js.map

package/dist/services/bootstrap-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-stream.js","sourceRoot":"","sources":["../../src/services/bootstrap-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAqE1F,gFAAgF;AAChF,4BAA4B;AAC5B,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAA+B;IAE/B,MAAM,EACJ,SAAS,EACT,KAAK,EACL,SAAS,EACT,IAAI,GAAG,QAAQ,EACf,UAAU,EACV,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,OAAO,EACP,OAAO,EACP,OAAO,GAAG,MAAM,EAChB,SAAS,GAAG,SAAS,EACtB,GAAG,OAAO,CAAC;IAEZ,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;IAEhE,IAAI,MAAM,GAA0B,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAEvD,IAAI,CAAC;QACH,wBAAwB;QACxB,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,QAAQ,EAAE,mBAAmB;YAC7B,WAAW,EAAE,KAAK;YAClB,eAAe,EAAE,SAAS;SAC3B,CAAC;QAEF,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,QAAQ,EAAE,CAAC;QAClD,CAAC;QAED,qEAAqE;QACrE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,IAAI;YACJ,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,QAAQ,IAAI;gBACpB,WAAW,EAAE,UAAU;aACxB;YACD,SAAS;SACV,CAAC,CAAC;QAEH,yBAAyB;QACzB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,mBAAmB,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI;YACJ,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QACzF,CAAC;QAED,2BAA2B;QAC3B,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;QAElC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QAED,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,kBAAkB;QAClB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAE5C,IAAI,IAAI;gBAAE,MAAM;YAEhB,yBAAyB;YACzB,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;YAElD,mCAAmC;YACnC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjC,MAAM,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAE,iCAAiC;YAE9D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,gCAAgC;gBAChC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAE5C,sBAAsB;gBACtB,IAAI,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC9B,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBAE3B,IAAI,CAAC;wBACH,MAAM,KAAK,GAAsB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;wBAElD,4BAA4B;wBAC5B,OAAO,CAAC,KAAK,CAAC,CAAC;wBAEf,4BAA4B;wBAC5B,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;4BAC3B,IAAI,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gCACvB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAqB,CAAC;gCACzC,MAAM,GAAG;oCACP,OAAO,EAAE,IAAI,CAAC,OAAO;oCACrB,UAAU,EAAE,IAAI,CAAC,oBAAoB;oCACrC,QAAQ,EAAE;wCACR,aAAa,EAAE,IAAI,CAAC,kBAAkB;wCACtC,SAAS,EAAE,IAAI,CAAC,oBAAoB,CAAC,UAAU;qCAChD;oCACD,cAAc,EAAE,IAAI,CAAC,qBAAqB;iCAC3C,CAAC;4BACJ,CAAC;iCAAM,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gCAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAsB,CAAC;gCAC1C,MAAM,GAAG;oCACP,OAAO,EAAE,KAAK;oCACd,KAAK,EAAE;wCACL,IAAI,EAAE,IAAI,CAAC,UAAU;wCACrB,OAAO,EAAE,IAAI,CAAC,OAAO;wCACrB,SAAS,EAAE,IAAI,CAAC,SAAS;qCAC1B;iCACF,CAAC;4BACJ,CAAC;4BACD,OAAO,MAAM,CAAC;wBAChB,CAAC;oBACH,CAAC;oBAAC,OAAO,UAAU,EAAE,CAAC;wBACpB,OAAO,CAAC,IAAI,CAAC,4BAA4B,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;oBAC/D,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,sCAAsC;QACtC,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YACrC,MAAM,GAAG;gBACP,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,gDAAgD;oBACzD,SAAS,EAAE,IAAI;iBAChB;aACF,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAc,CAAC;QAE3B,yBAAyB;QACzB,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;YAC9B,MAAM,GAAG;gBACP,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,SAAS;oBACf,OAAO,EAAE,6BAA6B,OAAO,IAAI;oBACjD,SAAS,EAAE,IAAI;iBAChB;aACF,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,GAAG;gBACP,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,eAAe;oBACrB,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,SAAS,EAAE,IAAI;iBAChB;aACF,CAAC;QACJ,CAAC;QAED,iCAAiC;QACjC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAED,gFAAgF;AAChF,oCAAoC;AACpC,gFAAgF;AAEhF;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAgD;IAEhD,MAAM,EACJ,SAAS,EACT,KAAK,EACL,SAAS,EACT,IAAI,GAAG,QAAQ,EACf,UAAU,EACV,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,OAAO,EACP,OAAO,GAAG,MAAM,EACjB,GAAG,OAAO,CAAC;IAEZ,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,OAAO,CAAC,CAAC;IAEhE,IAAI,CAAC;QACH,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,WAAW,EAAE,KAAK;YAClB,eAAe,EAAE,SAAS;SAC3B,CAAC;QAEF,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,QAAQ,EAAE,CAAC;QAClD,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;YAC1B,IAAI;YACJ,WAAW,EAAE,UAAU;YACvB,QAAQ,EAAE,QAAQ,IAAI;gBACpB,WAAW,EAAE,UAAU;aACxB;SACF,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,YAAY,EAAE;YACrD,MAAM,EAAE,MAAM;YACd,OAAO;YACP,IAAI;YACJ,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC;QACzF,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAK/B,CAAC;QAEF,2CAA2C;QAC3C,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,IAAI,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC;QAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,oBAAoB,EAAE,UAAU,IAAI,IAAI,CAAC,UAAU,IAAI,EAAqC,CAAC;QAEpH,OAAO;YACL,OAAO,EAAE,IAAI;YACb,UAAU,EAAE,IAAI,CAAC,oBAAoB;YACrC,QAAQ,EAAE;gBACR,aAAa;gBACb,SAAS;aACV;SACF,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAc,CAAC;QAE3B,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,GAAG,CAAC,CAAC;QACf,CAAC;QAED,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI,EAAE,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,eAAe;gBAC7D,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,SAAS,EAAE,IAAI;aAChB;SACF,CAAC;IACJ,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,SAAS,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/services/import-graph.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Import Graph Analysis Service
+ *
+ * Uses Skott for JS/TS dependency graph analysis with dead code detection.
+ * Routes to appropriate analyzer based on primary language.
+ *
+ * @package @ace-sdk/core
+ */
+import type { GraphMetrics, CodeHealthMetrics } from '../types/project-dna.js';
+/**
+ * Represents a node in the import graph
+ */
+export interface FileNode {
+    /** File path relative to repo root */
+    path: string;
+    /** Files this file imports */
+    imports: string[];
+    /** Files that import this file */
+    importedBy: string[];
+    /** Has no dependents (entry point) */
+    isEntryPoint: boolean;
+    /** Has 5+ importers */
+    isHub: boolean;
+    /** Has no dependencies */
+    isLeaf: boolean;
+}
+/**
+ * Complete import graph analysis result
+ */
+export interface ImportGraph {
+    /** All file nodes in the graph */
+    nodes: Map<string, FileNode>;
+    /** Files with no dependents */
+    entryPoints: string[];
+    /** Files with 5+ importers */
+    hubFiles: string[];
+    /** Files with no dependencies */
+    leafFiles: string[];
+    /** Circular dependency chains */
+    circularDeps: string[][];
+    /** Dead code files (never imported) */
+    deadCode: string[];
+    /** Unused dependencies from package.json */
+    unusedDeps: string[];
+}
+/**
+ * Options for building import graph
+ */
+export interface ImportGraphOptions {
+    /** Root path to analyze */
+    repoPath: string;
+    /** Entry points to start from (optional) */
+    entryPoints?: string[];
+    /** Paths to ignore */
+    ignorePaths?: string[];
+    /** Maximum files to analyze */
+    maxFiles?: number;
+}
+/**
+ * Default paths to ignore during analysis
+ */
+export declare const DEFAULT_IGNORE_PATHS: string[];
+/**
+ * Minimum number of importers to be considered a hub
+ */
+export declare const HUB_THRESHOLD = 5;
+/**
+ * Build import graph with language-based routing
+ *
+ * Routes to the best analyzer based on primary language:
+ * - TypeScript/JavaScript: Skott (fast, dead code detection)
+ * - Other languages: Git co-occurrence fallback
+ *
+ * @param options - Import graph options
+ * @returns Complete import graph analysis
+ *
+ * @example
+ * ```typescript
+ * const graph = await buildImportGraph({ repoPath: '/path/to/repo' });
+ *
+ * console.log(`Entry points: ${graph.entryPoints.length}`);
+ * console.log(`Hub files: ${graph.hubFiles.length}`);
+ * console.log(`Dead code: ${graph.deadCode.length}`);
+ * console.log(`Circular deps: ${graph.circularDeps.length}`);
+ * ```
+ */
+export declare function buildImportGraph(options: ImportGraphOptions): Promise<ImportGraph>;
+/**
+ * Select priority files from import graph for bootstrap
+ *
+ * Priority order:
+ * 1. Entry points (always include)
+ * 2. Hub files (most imported - high value)
+ * 3. Files in circular deps (need attention)
+ * 4. Leaf files with many exports (API surface)
+ * 5. Fill remaining with diverse sampling
+ *
+ * @param graph - Import graph to select from
+ * @param maxFiles - Maximum files to select
+ * @returns Array of priority file paths
+ */
+export declare function selectPriorityFiles(graph: ImportGraph, maxFiles: number): string[];
+/**
+ * Convert import graph to GraphMetrics for ProjectDNA
+ */
+export declare function graphToMetrics(graph: ImportGraph): GraphMetrics;
+/**
+ * Calculate code health metrics from import graph
+ */
+export declare function calculateHealthMetrics(graph: ImportGraph, totalFiles: number, avgFileSize: number, maxFileSize: number): CodeHealthMetrics;
+//# sourceMappingURL=import-graph.d.ts.map

package/dist/services/import-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-graph.d.ts","sourceRoot":"","sources":["../../src/services/import-graph.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAM/E;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,kCAAkC;IAClC,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,sCAAsC;IACtC,YAAY,EAAE,OAAO,CAAC;IACtB,uBAAuB;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,0BAA0B;IAC1B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,kCAAkC;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC7B,+BAA+B;IAC/B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iCAAiC;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iCAAiC;IACjC,YAAY,EAAE,MAAM,EAAE,EAAE,CAAC;IACzB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sBAAsB;IACtB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;GAEG;AACH,eAAO,MAAM,oBAAoB,UAWhC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AA+J/B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsBxF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA6ClF;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAQ/D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,EAClB,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAClB,iBAAiB,CAYnB"}

package/dist/services/import-graph.js

@@ -0,0 +1,292 @@
+/**
+ * Import Graph Analysis Service
+ *
+ * Uses Skott for JS/TS dependency graph analysis with dead code detection.
+ * Routes to appropriate analyzer based on primary language.
+ *
+ * @package @ace-sdk/core
+ */
+import skott from 'skott';
+import { LanguageDetector } from './language-detector.js';
+// =============================================================================
+// Constants
+// =============================================================================
+/**
+ * Default paths to ignore during analysis
+ */
+export const DEFAULT_IGNORE_PATHS = [
+    'node_modules',
+    'dist',
+    'build',
+    '.git',
+    '.next',
+    'coverage',
+    '__tests__',
+    '__mocks__',
+    '*.test.*',
+    '*.spec.*'
+];
+/**
+ * Minimum number of importers to be considered a hub
+ */
+export const HUB_THRESHOLD = 5;
+// =============================================================================
+// Import Graph Builder
+// =============================================================================
+/**
+ * Build import graph using Skott for JS/TS projects
+ */
+async function buildSkottGraph(options) {
+    const { repoPath, ignorePaths = DEFAULT_IGNORE_PATHS } = options;
+    const graph = {
+        nodes: new Map(),
+        entryPoints: [],
+        hubFiles: [],
+        leafFiles: [],
+        circularDeps: [],
+        deadCode: [],
+        unusedDeps: []
+    };
+    try {
+        // Run Skott analysis with config
+        const skottInstance = await skott({
+            cwd: repoPath,
+            entrypoint: options.entryPoints?.[0],
+            includeBaseDir: false,
+            ignorePatterns: ignorePaths,
+            dependencyTracking: {
+                thirdParty: true,
+                builtin: false,
+                typeOnly: true
+            },
+            fileExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+            tsConfigPath: 'tsconfig.json',
+            manifestPath: 'package.json',
+            incremental: false,
+            circularMaxDepth: 10,
+            verbose: false
+        });
+        // Get structure from the instance
+        const structure = skottInstance.getStructure();
+        const { files, graph: skottGraph } = structure;
+        // Get circular dependencies and unused deps from graph API
+        const graphApi = skottInstance.useGraph();
+        const circularDependencies = graphApi.findCircularDependencies();
+        const unusedDependencies = await skottInstance.findUnusedDependencies();
+        // Build our graph from Skott's output
+        // SkottNode has: { id, adjacentTo: string[], body: { size, thirdPartyDependencies, builtinDependencies } }
+        for (const file of files) {
+            const node = skottGraph[file];
+            const deps = node?.adjacentTo || [];
+            graph.nodes.set(file, {
+                path: file,
+                imports: deps,
+                importedBy: [],
+                isEntryPoint: false,
+                isHub: false,
+                isLeaf: deps.length === 0
+            });
+        }
+        // Build reverse mapping (who imports this file)
+        for (const [filePath, node] of graph.nodes) {
+            for (const dep of node.imports) {
+                const depNode = graph.nodes.get(dep);
+                if (depNode) {
+                    depNode.importedBy.push(filePath);
+                }
+            }
+        }
+        // Identify entry points, hubs, and dead code
+        for (const [filePath, node] of graph.nodes) {
+            // Entry point: no one imports this file
+            if (node.importedBy.length === 0) {
+                node.isEntryPoint = true;
+                graph.entryPoints.push(filePath);
+            }
+            // Hub: many files import this
+            if (node.importedBy.length >= HUB_THRESHOLD) {
+                node.isHub = true;
+                graph.hubFiles.push(filePath);
+            }
+            // Leaf: no dependencies
+            if (node.isLeaf) {
+                graph.leafFiles.push(filePath);
+            }
+        }
+        // Dead code: files that are never imported (but not entry points)
+        // Use Skott's circular dependencies detection
+        graph.circularDeps = circularDependencies || [];
+        // Unused npm dependencies (thirdParty is the property containing unused deps)
+        graph.unusedDeps = unusedDependencies?.thirdParty || [];
+        // Find orphan files (not entry points but never imported)
+        for (const [filePath, node] of graph.nodes) {
+            if (node.importedBy.length === 0 && !isLikelyEntryPoint(filePath)) {
+                graph.deadCode.push(filePath);
+            }
+        }
+        return graph;
+    }
+    catch (error) {
+        console.error('Skott analysis failed:', error);
+        return graph;
+    }
+}
+/**
+ * Check if a file is likely an entry point
+ */
+function isLikelyEntryPoint(filePath) {
+    const entryPatterns = [
+        /^index\.[jt]sx?$/,
+        /^main\.[jt]sx?$/,
+        /^app\.[jt]sx?$/,
+        /^server\.[jt]sx?$/,
+        /^cli\.[jt]sx?$/,
+        /\/index\.[jt]sx?$/,
+        /\/main\.[jt]sx?$/,
+        /src\/index\.[jt]sx?$/,
+        /src\/main\.[jt]sx?$/
+    ];
+    return entryPatterns.some(pattern => pattern.test(filePath));
+}
+/**
+ * Build import graph using git co-occurrence for non-JS/TS projects
+ * (Fallback when no static analyzer is available)
+ */
+async function buildGitCooccurrenceGraph(_options) {
+    // For non-JS/TS projects, we can't do static analysis
+    // Return empty graph - future: implement git co-occurrence analysis
+    return {
+        nodes: new Map(),
+        entryPoints: [],
+        hubFiles: [],
+        leafFiles: [],
+        circularDeps: [],
+        deadCode: [],
+        unusedDeps: []
+    };
+}
+// =============================================================================
+// Main Export
+// =============================================================================
+/**
+ * Build import graph with language-based routing
+ *
+ * Routes to the best analyzer based on primary language:
+ * - TypeScript/JavaScript: Skott (fast, dead code detection)
+ * - Other languages: Git co-occurrence fallback
+ *
+ * @param options - Import graph options
+ * @returns Complete import graph analysis
+ *
+ * @example
+ * ```typescript
+ * const graph = await buildImportGraph({ repoPath: '/path/to/repo' });
+ *
+ * console.log(`Entry points: ${graph.entryPoints.length}`);
+ * console.log(`Hub files: ${graph.hubFiles.length}`);
+ * console.log(`Dead code: ${graph.deadCode.length}`);
+ * console.log(`Circular deps: ${graph.circularDeps.length}`);
+ * ```
+ */
+export async function buildImportGraph(options) {
+    const detector = new LanguageDetector();
+    const primaryLang = await detector.getPrimaryLanguage(options.repoPath);
+    // Route to best analyzer for this language
+    switch (primaryLang) {
+        case 'TypeScript':
+        case 'JavaScript':
+        case 'TSX':
+        case 'JSX':
+            return buildSkottGraph(options);
+        // Future: Add support for other languages
+        // case 'Java':
+        // case 'Python':
+        // case 'Go':
+        //   return buildDependsGraph(options);
+        default:
+            // Fallback to git co-occurrence
+            return buildGitCooccurrenceGraph(options);
+    }
+}
+/**
+ * Select priority files from import graph for bootstrap
+ *
+ * Priority order:
+ * 1. Entry points (always include)
+ * 2. Hub files (most imported - high value)
+ * 3. Files in circular deps (need attention)
+ * 4. Leaf files with many exports (API surface)
+ * 5. Fill remaining with diverse sampling
+ *
+ * @param graph - Import graph to select from
+ * @param maxFiles - Maximum files to select
+ * @returns Array of priority file paths
+ */
+export function selectPriorityFiles(graph, maxFiles) {
+    const priority = [];
+    const seen = new Set();
+    const addUnique = (files, limit) => {
+        let added = 0;
+        for (const file of files) {
+            if (!seen.has(file)) {
+                seen.add(file);
+                priority.push(file);
+                added++;
+                if (limit && added >= limit)
+                    break;
+            }
+        }
+    };
+    // 1. Entry points (always include)
+    addUnique(graph.entryPoints, 10);
+    // 2. Hub files (most imported - high value)
+    const sortedHubs = [...graph.hubFiles].sort((a, b) => {
+        const aNode = graph.nodes.get(a);
+        const bNode = graph.nodes.get(b);
+        return (bNode?.importedBy.length || 0) - (aNode?.importedBy.length || 0);
+    });
+    addUnique(sortedHubs, 20);
+    // 3. Files in circular deps (need attention)
+    const circularFiles = graph.circularDeps.flat();
+    addUnique(circularFiles, 10);
+    // 4. Leaf files with many exports (API surface)
+    const apiSurface = [...graph.nodes.entries()]
+        .filter(([_, n]) => n.isLeaf && n.importedBy.length > 0)
+        .sort((a, b) => b[1].importedBy.length - a[1].importedBy.length)
+        .map(([p]) => p);
+    addUnique(apiSurface, 20);
+    // 5. Fill remaining with diverse sampling
+    if (priority.length < maxFiles) {
+        const remaining = [...graph.nodes.keys()].filter(p => !seen.has(p));
+        addUnique(remaining, maxFiles - priority.length);
+    }
+    return priority.slice(0, maxFiles);
+}
+/**
+ * Convert import graph to GraphMetrics for ProjectDNA
+ */
+export function graphToMetrics(graph) {
+    return {
+        totalFiles: graph.nodes.size,
+        hubFiles: graph.hubFiles.slice(0, 20),
+        entryPoints: graph.entryPoints.slice(0, 10),
+        leafNodes: graph.leafFiles.slice(0, 20),
+        circularDeps: graph.circularDeps.slice(0, 10)
+    };
+}
+/**
+ * Calculate code health metrics from import graph
+ */
+export function calculateHealthMetrics(graph, totalFiles, avgFileSize, maxFileSize) {
+    const deadCodePercentage = totalFiles > 0
+        ? (graph.deadCode.length / totalFiles) * 100
+        : 0;
+    return {
+        deadCodePercentage,
+        circularDepsCount: graph.circularDeps.length,
+        unusedDepsCount: graph.unusedDeps.length,
+        avgFileSize,
+        maxFileSize
+    };
+}
+//# sourceMappingURL=import-graph.js.map