codeviz 0.1.0 → 0.1.2

package/dist/index.d.mts

@@ -1,11 +1,737 @@
+import { e as DirectoryNode, d as FileNode, g as SymbolNode, F as FileMetrics, b as SourceLocation, I as ImportEdge, C as CallEdge, i as CodeGraph, d3 as ViewMode, am as Theme, Z as ZoomLevel, r as ZoomLevelConfig, k as MapNode, cQ as IOverlayPort, cx as Overlay, d4 as SigmaTheme, p as CodeMap } from './useOverlayPort-dGxZQTue.mjs';
+export { cl as AbsolutePosition, cL as AgentStatus, cw as AgentWidgetOverlay, cE as AgentWidgetOverlayInput, bM as AggregateNodeComponent, A as AggregateNodeData, c6 as AggregateReactFlowNodeData, ck as AnchorPoint, s as AnimationConfig, cI as AnnotationContentType, cu as AnnotationOverlay, cC as AnnotationOverlayInput, ct as BadgeOverlay, cB as BadgeOverlayInput, cH as BadgeSize, cG as BadgeVariant, cq as BaseOverlay, B as BoundingBox, bQ as BundledEdgeComponent, cb as BundledEdgeData, cS as CalculatedPosition, bP as CallEdgeComponent, ca as CallEdgeData, aU as ClusteringOptions, aV as ClusteringResult, bD as CodeMapComponent, t as CodeMapConfig, b$ as CodeMapProps, h as CodebaseMetadata, ag as ColorPalette, b3 as ComputeLayoutOptions, cr as CursorOverlay, cz as CursorOverlayInput, w as DEFAULT_ANIMATION_CONFIG, x as DEFAULT_CODEMAP_CONFIG, v as DEFAULT_LAYOUT_CONFIG, u as DEFAULT_ZOOM_LEVELS, aQ as DirectoryEdgeAttributes, aW as DirectoryForceOptions, aX as DirectoryForceResult, aT as DirectoryGraphResult, D as DirectoryMetrics, cv as DocumentOverlay, cD as DocumentOverlayInput, cK as DocumentStatus, cJ as DocumentType, aj as EdgeColors, cU as EdgePath, cn as EdgePosition, b0 as EdgeRoutingOptions, c3 as EdgeType, aR as EntityIdMapping, bJ as FileNodeComponent, c4 as FileNodeData, bE as Flow, c0 as FlowProps, a_ as ForcePositioningOptions, aP as GraphEdgeAttributes, aO as GraphNodeAttributes, aS as GraphologyConversionResult, aY as HierarchyOptions, aZ as HierarchyResult, cs as HighlightOverlay, cA as HighlightOverlayInput, cF as HighlightStyle, bO as ImportEdgeComponent, c9 as ImportEdgeData, L as LayoutConfig, cf as LayoutProgress, b4 as LayoutProgressCallback, o as MapEdge, n as MapEdgeType, j as MapNodeData, M as MapNodeType, m as MapScope, l as MapScopeData, cT as NodeBounds, ai as NodeColors, cm as NodePosition, c2 as NodeType, a$ as NoverlapOptions, cN as OverlayBatchUpdate, cO as OverlayClickHandler, ak as OverlayColors, cM as OverlayFilter, cP as OverlayHoverHandler, cy as OverlayInput, cY as OverlayLayer, cR as OverlayLayerProps, cW as OverlayPort, co as OverlayPosition, cp as OverlayType, a as Padding, c_ as PortalOverlayLayer, P as Position, af as RGBAColor, ae as RGBColor, cc as ReactFlowEdgeData, c8 as ReactFlowNodeData, d7 as RendererType, cZ as SVGOverlayLayer, ah as ScopeDepthColors, bK as ScopeNodeComponent, c7 as ScopeNodeData, c1 as ScopeNodeProps, d6 as SigmaEdgeAttributes, d9 as SigmaEdgeColors, da as SigmaHighlightConfig, db as SigmaLabelConfig, d5 as SigmaNodeAttributes, d8 as SigmaNodeColors, S as Size, f as SymbolKind, c as SymbolMetrics, bL as SymbolNodeComponent, c5 as SymbolNodeData, an as ThemeContextValue, bF as ThemeProvider, ao as ThemeProviderProps, al as UIColors, cg as UseLayoutOptions, ch as UseLayoutResult, ci as UseOverlayPortOptions, cj as UseOverlayPortResult, cV as ViewportTransform, b2 as ZoomLevelData, q as ZoomLevelName, b1 as ZoomPrecomputeOptions, be as assignClusterColors, W as boundingBoxFromCorners, _ as boundingBoxesOverlap, b6 as buildDirectoryGraph, bq as calculateNodeSize, c$ as calculateOverlayPosition, a4 as clampPosition, b5 as codeGraphToGraphology, bY as codeMapToReactFlowEdges, bX as codeMapToReactFlowNodes, bg as computeDirectoryForces, bt as computeEdges, bk as computeHierarchy, bC as computeLayout, bw as computeZoomLevels, V as createBoundingBox, cX as createOverlayPort, aM as createScopeColorGetter, aq as darkTheme, aB as darken, bb as detectCommunities, ab as detectLanguage, a2 as distance, bR as edgeTypes, a0 as expandBoundingBox, bW as formatLoc, bV as formatNumber, H as generateCallEdgeId, z as generateDirectoryId, y as generateFileId, G as generateImportEdgeId, aH as generateScopeDepthColors, E as generateSymbolId, d0 as getAnchorOffset, Q as getBasename, X as getBoundingBoxCenter, bm as getChildScopes, bd as getClusterStats, aJ as getContrastRatio, bZ as getDefaultExpandedScopes, au as getDefaultTheme, K as getDirectory, ba as getDirectoryConnectionWeight, bi as getDirectoryPosition, bv as getEdgeLabel, bu as getEdgesAtZoomLevel, b7 as getEntityId, O as getExtension, bS as getFileIcon, N as getFilename, b9 as getFilesInDirectory, ad as getIconName, aI as getLuminance, aa as getMediumFileLabel, bf as getNodeCluster, b8 as getNodeKey, bB as getNodeOpacityAtLevel, bA as getNodeSizeAtLevel, bc as getNodesInCluster, R as getParentDirectories, T as getPathDepth, bj as getPositionsAtDepth, bn as getRootScopes, bl as getScopeByDirectoryId, aG as getScopeDepthColor, a9 as getShortFileLabel, bT as getSymbolIcon, bU as getSymbolKindLabel, aL as getTextColorForBackground, ar as getTheme, at as getThemeIds, bz as getVisibleEdges, bx as getVisibleNodes, by as getVisibleScopes, a7 as getZoomLevel, b_ as getZoomLevelFromZoom, d1 as graphToScreen, av as hexToRgb, ay as hslToHex, ax as hslToRgb, ac as isCodeFile, Y as isPointInBoundingBox, a3 as lerp, ap as lightTheme, aA as lighten, U as matchesPattern, aN as mergeTheme, aD as mix, bN as nodeTypes, J as normalizePath, bh as normalizePositions, bp as positionAllNodes, bo as positionNodesInScope, as as registerTheme, bs as removeAllOverlaps, br as removeOverlapsInScope, aw as rgbToHex, az as rgbToHsl, aF as rgbaToCss, aC as saturate, a5 as scaleSize, d2 as screenToGraph, aK as shouldUseDarkText, a1 as shrinkBoundingBox, a8 as truncateLabel, a6 as uniformPadding, $ as unionBoundingBoxes, bH as useCurrentTheme, bI as useIsDarkTheme, cd as useLayout, ce as useOverlayPort, bG as useTheme, aE as withOpacity } from './useOverlayPort-dGxZQTue.mjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import Sigma from 'sigma';
+import * as Graph from 'graphology';
+import Graph__default from 'graphology';
+import { Attributes } from 'graphology-types';
+import Parser from 'tree-sitter';
+import 'react/jsx-runtime';
+import '@xyflow/react';
+import 'lucide-react';
+
+/**
+ * Directory scanner with gitignore support
+ * Recursively scans directories respecting .gitignore rules
+ */
+
+/**
+ * Scanner configuration
+ */
+interface ScannerConfig {
+    rootPath: string;
+    include?: string[];
+    exclude?: string[];
+    respectGitignore?: boolean;
+    maxDepth?: number;
+    maxFiles?: number;
+}
+/**
+ * Information about a skipped file
+ */
+interface SkippedFile {
+    path: string;
+    reason: 'gitignore' | 'excluded' | 'not-code' | 'max-depth' | 'max-files' | 'permission' | 'binary' | 'too-large';
+}
+/**
+ * Scan result containing discovered files and directories
+ */
+interface ScanResult {
+    directories: DirectoryNode[];
+    files: FileNode[];
+    skipped: SkippedFile[];
+    rootPath: string;
+}
+/**
+ * Convenience function to scan a directory
+ */
+declare function scanDirectory(config: ScannerConfig): Promise<ScanResult>;
+
+/**
+ * Symbol extraction module
+ * Coordinates extraction of symbols from source files using language-specific extractors
+ * Supports native high-quality extractors for TS/JS/Python and generic WASM-based extraction for other languages
+ */
+
+/**
+ * Result of symbol extraction
+ */
+interface SymbolExtractionResult {
+    symbols: SymbolNode[];
+    metrics: FileMetrics;
+    parseErrors?: string[];
+}
+/**
+ * Extract symbols from a file
+ * Uses native extractors for TS/JS/Python, falls back to generic WASM-based extraction for other languages
+ */
+declare function extractSymbols(filePath: string, content: string, fileId: string): Promise<SymbolExtractionResult>;
+/**
+ * Extract symbols from a file by reading it from disk
+ */
+declare function extractSymbolsFromFile(filePath: string, fileId: string): Promise<SymbolExtractionResult>;
+
+/**
+ * Import resolution module
+ * Handles resolution of import statements to actual file paths
+ */
+
+/**
+ * Import information extracted from source
+ */
+interface ImportInfo {
+    source: string;
+    importType: 'static' | 'dynamic' | 'type-only';
+    importedSymbols: string[];
+    location: SourceLocation;
+}
+/**
+ * Resolved import with edge information
+ */
+interface ResolvedImport {
+    edge: ImportEdge;
+    resolved: boolean;
+    resolvedPath?: string;
+}
+/**
+ * File index for resolving imports
+ */
+type FileIndex = Map<string, string>;
+/**
+ * Extract imports from a source file
+ */
+declare function extractImports(filePath: string, content: string): Promise<ImportInfo[]>;
+/**
+ * Resolve an import to a file path and create an edge
+ */
+declare function resolveImport(importInfo: ImportInfo, fromFileId: string, fromFilePath: string, rootPath: string, fileIndex: FileIndex): ResolvedImport;
+/**
+ * Build a file index from file paths
+ */
+declare function buildFileIndex(files: Array<{
+    id: string;
+    path: string;
+}>): FileIndex;
+
+/**
+ * Shared extraction utilities for all languages
+ * Contains common patterns and helper functions for AST traversal
+ */
+
+/**
+ * Raw call information extracted from source
+ */
+interface RawCall {
+    callerName: string;
+    calleeName: string;
+    callType: 'direct' | 'method' | 'constructor';
+    location: SourceLocation;
+}
+
+/**
+ * Call graph resolution module
+ * Handles extraction and resolution of function/method calls
+ */
+
+/**
+ * Resolved call with edge information
+ */
+interface ResolvedCall {
+    edge: CallEdge;
+    resolved: boolean;
+}
+/**
+ * Symbol index for resolving calls
+ */
+type SymbolIndex = Map<string, SymbolNode>;
+/**
+ * Extract calls from a source file
+ */
+declare function extractCalls(filePath: string, content: string, symbols: SymbolNode[]): Promise<RawCall[]>;
+/**
+ * Resolve all calls for a file
+ */
+declare function resolveFileCalls(filePath: string, content: string, fileSymbols: SymbolNode[], globalSymbolIndex: SymbolIndex): Promise<ResolvedCall[]>;
+/**
+ * Build a global symbol index from all files
+ */
+declare function buildGlobalSymbolIndex(allSymbols: SymbolNode[]): SymbolIndex;
+
+/**
+ * Language registry for tree-sitter grammars
+ * Handles lazy loading of language grammars
+ * Supports both native tree-sitter and WASM-based grammars
+ */
+/**
+ * Language configuration
+ */
+interface Language {
+    name: string;
+    extensions: string[];
+    grammar: unknown;
+}
+/**
+ * Lazy-loaded language definitions
+ */
+interface LanguageLoader {
+    name: string;
+    extensions: string[];
+    load: () => Promise<unknown>;
+}
+/**
+ * Language registry with lazy loading
+ */
+declare class LanguageRegistry {
+    private loaders;
+    private loaded;
+    private extensionMap;
+    constructor();
+    /**
+     * Register built-in language loaders
+     */
+    private registerBuiltinLanguages;
+    /**
+     * Register a language loader
+     */
+    registerLoader(loader: LanguageLoader): void;
+    /**
+     * Get language by name, loading if necessary
+     */
+    getLanguage(name: string): Promise<Language | null>;
+    /**
+     * Get language by file extension
+     */
+    getLanguageForExtension(extension: string): Promise<Language | null>;
+    /**
+     * Get language for a file path
+     */
+    getLanguageForFile(filePath: string): Promise<Language | null>;
+    /**
+     * Extract file extension from path
+     */
+    private getExtension;
+    /**
+     * Get list of supported languages
+     */
+    getSupportedLanguages(): string[];
+    /**
+     * Get list of supported extensions
+     */
+    getSupportedExtensions(): string[];
+    /**
+     * Check if a file extension is supported (native only)
+     */
+    isSupported(extension: string): boolean;
+    /**
+     * Check if a file extension is supported by WASM grammars
+     */
+    isWasmSupported(extension: string): boolean;
+    /**
+     * Check if a file is supported based on its path
+     * Considers both native tree-sitter and WASM-based grammars
+     */
+    isFileSupported(filePath: string): boolean;
+}
+declare function getLanguageRegistry(): LanguageRegistry;
+/**
+ * Reset the registry (useful for testing)
+ */
+declare function resetLanguageRegistry(): void;
+
+/**
+ * Tree-sitter parser initialization and caching
+ * Provides lazy loading of language parsers and parsed tree caching
+ * Supports both native tree-sitter and WASM-based web-tree-sitter
+ */
+
+/**
+ * Parsed tree with associated metadata
+ */
+interface ParsedTree {
+    tree: Parser.Tree;
+    language: string;
+    filePath: string;
+    parseTime: number;
+}
+/**
+ * Parse error information
+ */
+interface ParseError {
+    message: string;
+    filePath: string;
+    language?: string;
+}
+/**
+ * Parser manager that handles lazy loading and caching
+ */
+declare class ParserManager {
+    private parsers;
+    private treeCache;
+    private maxCacheSize;
+    constructor(maxCacheSize?: number);
+    /**
+     * Get or create a parser for the specified language
+     */
+    getParser(language: Language): Promise<Parser>;
+    /**
+     * Parse source code and return the syntax tree
+     */
+    parse(filePath: string, content: string, language: Language): Promise<ParsedTree>;
+    /**
+     * Parse with error handling - returns result or error
+     */
+    safeParse(filePath: string, content: string, language: Language): Promise<{
+        result: ParsedTree;
+    } | {
+        error: ParseError;
+    }>;
+    /**
+     * Add parsed tree to cache with LRU eviction
+     */
+    private addToCache;
+    /**
+     * Clear the cache for a specific file (e.g., when file changes)
+     */
+    invalidate(filePath: string): void;
+    /**
+     * Clear all cached trees
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+declare function getParserManager(): ParserManager;
+/**
+ * Reset the default parser manager (useful for testing)
+ */
+declare function resetParserManager(): void;
+
+/**
+ * CodeGraph Builder - Main orchestrator for codebase analysis
+ * Coordinates scanning, parsing, and graph building
+ */
+
+/**
+ * Analyzer configuration
+ */
+interface AnalyzerConfig {
+    rootPath: string;
+    include?: string[];
+    exclude?: string[];
+    respectGitignore?: boolean;
+    languages?: string[];
+    extractCalls?: boolean;
+    maxFiles?: number;
+    onProgress?: (progress: AnalysisProgress) => void;
+}
+/**
+ * Analysis progress information
+ */
+interface AnalysisProgress {
+    phase: 'scanning' | 'parsing' | 'resolving';
+    current: number;
+    total: number;
+    currentFile?: string;
+}
+/**
+ * Analysis result with additional metadata
+ */
+interface AnalysisResult {
+    graph: CodeGraph;
+    stats: AnalysisStats;
+    errors: AnalysisError[];
+}
+/**
+ * Analysis statistics
+ */
+interface AnalysisStats {
+    totalFiles: number;
+    totalDirectories: number;
+    totalSymbols: number;
+    totalImports: number;
+    totalCalls: number;
+    resolvedImports: number;
+    resolvedCalls: number;
+    parseTime: number;
+    totalTime: number;
+    skippedFiles: number;
+}
+/**
+ * Analysis error information
+ */
+interface AnalysisError {
+    file: string;
+    message: string;
+    phase: 'scan' | 'parse' | 'resolve';
+}
+/**
+ * Analyze a codebase and build a CodeGraph
+ */
+declare function analyzeCodebase(config: AnalyzerConfig): Promise<AnalysisResult>;
+/**
+ * Reset all caches (useful for testing or memory management)
+ */
+declare function resetAnalyzer(): void;
+
+/**
+ * Position options for the controls panel
+ */
+type ControlsPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+
+/**
+ * Props for SigmaRenderer component
+ */
+interface SigmaRendererProps {
+    /** Graphology graph to render */
+    graph: Graph__default | null;
+    /** View mode */
+    view: ViewMode;
+    /** CodeViz theme */
+    theme: Theme;
+    /** Current semantic zoom level (0-4) */
+    zoomLevel?: ZoomLevel;
+    /** Zoom level configuration for filtering */
+    zoomConfig?: ZoomLevelConfig | null;
+    /** Auto-run ForceAtlas2 layout on graph changes - default: false */
+    runLayout?: boolean;
+    onNodeClick?: (nodeId: string, data: MapNode) => void;
+    onNodeDoubleClick?: (nodeId: string) => void;
+    onNodeHover?: (nodeId: string | null) => void;
+    onEdgeClick?: (edgeId: string) => void;
+    onCanvasClick?: () => void;
+    selectedNodeId?: string | null;
+    onSelectedNodeChange?: (nodeId: string | null) => void;
+    highlightedNodeIds?: string[];
+    /** Overlay port for imperative overlay management */
+    overlayPort?: IOverlayPort;
+    /** Declarative overlays */
+    overlays?: Overlay[];
+    /** Throttle overlay position updates (ms) - default: 16 */
+    overlayUpdateThrottleMs?: number;
+    /** Overlay click handler */
+    onOverlayClick?: (id: string, overlay: Overlay) => void;
+    /** Overlay hover handler */
+    onOverlayHover?: (id: string, overlay: Overlay, isHovering: boolean) => void;
+    /** Show graph controls (zoom, reset, etc.) - default: true */
+    showControls?: boolean;
+    /** Position of graph controls */
+    controlsPosition?: ControlsPosition;
+    className?: string;
+    /** Disable the built-in error boundary - default: false */
+    disableErrorBoundary?: boolean;
+    /** Custom fallback UI for error boundary */
+    errorFallback?: ReactNode;
+    /** Callback when error occurs in the renderer */
+    onError?: (error: Error, errorInfo: React.ErrorInfo) => void;
+}
+/**
+ * Imperative handle for SigmaRenderer
+ */
+interface SigmaRendererHandle {
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetView: () => void;
+    focusNode: (nodeId: string) => void;
+    fitToNodes: (nodeIds: string[]) => void;
+    getSigma: () => Sigma | null;
+    isLayoutRunning: boolean;
+    startLayout: () => void;
+    stopLayout: () => void;
+}
+/**
+ * Sigma renderer component
+ *
+ * @example
+ * ```tsx
+ * <SigmaRenderer
+ *   graph={graphologyGraph}
+ *   view="nexus"
+ *   theme={darkTheme}
+ *   onNodeClick={(id) => console.log('clicked', id)}
+ * />
+ * ```
+ */
+declare const SigmaRenderer: react.ForwardRefExoticComponent<SigmaRendererProps & react.RefAttributes<SigmaRendererHandle>>;
+
+/**
+ * Core React hook for Sigma.js integration
+ *
+ * Manages Sigma instance lifecycle, event handling, and camera controls
+ */
+
+/**
+ * Options for useSigma hook
+ */
+interface UseSigmaOptions {
+    /** Graphology graph to render */
+    graph: Graph__default | null;
+    /** Container element for Sigma */
+    container: HTMLDivElement | null;
+    /** CodeViz theme */
+    theme: Theme;
+    /** Current semantic zoom level (0-4) */
+    zoomLevel?: ZoomLevel;
+    /** Zoom level configuration for filtering */
+    zoomConfig?: ZoomLevelConfig | null;
+    /** Run ForceAtlas2 layout on graph changes - default: false */
+    runLayout?: boolean;
+    /** Node IDs to highlight (from overlay system) */
+    highlightedNodes?: string[];
+    onNodeClick?: (nodeId: string, attrs: Record<string, unknown>) => void;
+    onNodeDoubleClick?: (nodeId: string) => void;
+    onNodeHover?: (nodeId: string | null) => void;
+    onEdgeClick?: (edgeId: string) => void;
+    onStageClick?: () => void;
+}
+/**
+ * Return value from useSigma hook
+ */
+interface UseSigmaReturn {
+    /** Sigma instance (null until initialized) */
+    sigma: Sigma | null;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    resetView: () => void;
+    focusNode: (nodeId: string) => void;
+    /** Fit camera to show all specified nodes */
+    fitToNodes: (nodeIds: string[]) => void;
+    /** Whether ForceAtlas2 layout is currently running */
+    isLayoutRunning: boolean;
+    /** Start ForceAtlas2 layout */
+    startLayout: () => void;
+    /** Stop ForceAtlas2 layout */
+    stopLayout: () => void;
+    isReady: boolean;
+}
+declare function useSigma(options: UseSigmaOptions): UseSigmaReturn;
+
+/**
+ * Sigma rendering constants and defaults
+ *
+ * Node colors, sizes, edge styles for Sigma visualization
+ */
+
+/**
+ * Default dark Sigma theme
+ */
+declare const DEFAULT_DARK_SIGMA_THEME: SigmaTheme;
+/**
+ * Default light Sigma theme
+ */
+declare const DEFAULT_LIGHT_SIGMA_THEME: SigmaTheme;
+/**
+ * Default Sigma theme (dark)
+ */
+declare const DEFAULT_SIGMA_THEME: SigmaTheme;
+/**
+ * Node sizes by type
+ */
+declare const NODE_SIZES: Record<string, number>;
+/**
+ * Edge sizes by relationship type
+ */
+declare const EDGE_SIZES: Record<string, number>;
+/**
+ * Get scaled node size based on graph size
+ *
+ * @param baseSize - Base node size
+ * @param nodeCount - Total nodes in graph
+ * @returns Scaled size
+ */
+declare function getScaledNodeSize(baseSize: number, nodeCount: number): number;
+/**
+ * Get Sigma theme from CodeViz theme, with fallback to defaults
+ *
+ * @param theme - CodeViz theme
+ * @returns Sigma theme configuration
+ */
+declare function getSigmaTheme(theme: Theme): SigmaTheme;
+
+/**
+ * Graph adapters for converting CodeViz data structures to Sigma-compatible Graphology graphs
+ */
+
+/**
+ * Convert CodeMap to Graphology graph for Structure view
+ * Preserves hierarchical layout with scopes as container regions
+ *
+ * @param codeMap - The CodeMap data from layout computation
+ * @param theme - Optional theme for colors
+ * @returns Graphology graph configured for Sigma rendering
+ */
+declare function structureToGraphology(codeMap: CodeMap, theme?: Theme): Graph__default;
+/**
+ * Options for nexusToGraphology conversion
+ */
+interface NexusToGraphologyOptions {
+    /** Include symbol nodes (functions, classes, etc.) - default: false */
+    includeSymbols?: boolean;
+    /** Theme for colors */
+    theme?: Theme;
+}
 /**
- * codeviz - Interactive 2D codebase visualization
+ * Convert CodeGraph to Graphology graph for Nexus view
+ * Creates flat relationship graph with code connections
+ *
+ * @param codeGraph - The CodeGraph from analysis
+ * @param options - Configuration options
+ * @returns Graphology graph configured for Sigma rendering
+ *
+ * @remarks
+ * Uses golden angle spiral positioning for directories, then positions
+ * children (files, optionally symbols) near their parents using BFS.
+ * This creates a good initial layout that ForceAtlas2 can refine quickly.
+ */
+declare function nexusToGraphology(codeGraph: CodeGraph, options?: NexusToGraphologyOptions): Graph__default;
+
+/**
+ * ForceAtlas2 configuration for Sigma graph layout
+ *
+ * Settings are dynamically scaled based on graph size for optimal performance
+ * Based on GitNexus implementation patterns
+ */
+
+/**
+ * ForceAtlas2 settings type
+ */
+interface FA2Settings {
+    gravity: number;
+    scalingRatio: number;
+    slowDown: number;
+    barnesHutOptimize: boolean;
+    barnesHutTheta: number;
+    strongGravityMode: boolean;
+    outboundAttractionDistribution: boolean;
+    linLogMode: boolean;
+    adjustSizes: boolean;
+    edgeWeightInfluence: number;
+}
+/**
+ * Get ForceAtlas2 settings dynamically scaled by node count
+ *
+ * @param nodeCount - Number of nodes in the graph
+ * @returns Optimized FA2 settings for the graph size
+ *
+ * @remarks
+ * This is a placeholder - full implementation in Phase 3
+ */
+declare function getFA2Settings(nodeCount: number): FA2Settings;
+/**
+ * Get layout duration based on graph size
+ *
+ * @param nodeCount - Number of nodes in the graph
+ * @returns Duration in milliseconds for ForceAtlas2 to run
+ */
+declare function getLayoutDuration(nodeCount: number): number;
+/**
+ * Get node mass based on type for ForceAtlas2
+ * Higher mass nodes spread apart and pull their children
+ *
+ * @param nodeType - Type of the node
+ * @param nodeCount - Total nodes in graph (affects scaling)
+ * @returns Mass value for the node
+ */
+declare function getNodeMass(nodeType: 'directory' | 'file' | 'symbol' | 'aggregate', nodeCount: number): number;
+
+/**
+ * Initial positioning algorithms for Sigma graph layout
+ *
+ * Uses golden angle spiral for structural nodes to provide
+ * a good starting point for ForceAtlas2
+ */
+
+/**
+ * Options for initial position assignment
+ */
+interface InitialPositionOptions {
+    /** Spread factor for structural nodes */
+    structuralSpread?: number;
+    /** Jitter factor for child nodes */
+    childJitter?: number;
+}
+/**
+ * Assign initial positions to graph nodes using golden angle spiral
+ *
+ * Structural nodes (directories) are spread in a spiral pattern,
+ * while child nodes are positioned near their parents with jitter.
+ *
+ * @param graph - Graphology graph to position
+ * @param options - Positioning options
+ *
+ * @remarks
+ * This is a placeholder - full implementation in Phase 3
+ */
+declare function assignInitialPositions(graph: Graph__default, options?: InitialPositionOptions): void;
+
+/**
+ * State used by reducers to compute appearance
+ */
+interface ReducerState {
+    /** Currently selected node ID */
+    selectedNode: string | null;
+    /** Set of highlighted node IDs (from search/AI) */
+    highlightedNodes: Set<string>;
+    /** Neighbor node IDs of selected node */
+    neighborNodes: Set<string>;
+}
+/**
+ * Extended state with zoom level for visibility filtering
+ */
+interface ZoomReducerState extends ReducerState {
+    /** Current semantic zoom level (0-4) */
+    zoomLevel: ZoomLevel;
+    /** Configuration for current zoom level (null to disable filtering) */
+    zoomConfig: ZoomLevelConfig | null;
+}
+/**
+ * Dim a hex color by mixing it toward a dark background
+ *
+ * @param hex - Hex color string
+ * @param amount - Amount to dim (0-1, lower = more dim)
+ * @returns Dimmed hex color
+ */
+declare function dimColor(hex: string, amount: number): string;
+/**
+ * Brighten a hex color
+ *
+ * @param hex - Hex color string
+ * @param factor - Brightening factor (>1 = brighter)
+ * @returns Brightened hex color
+ */
+declare function brightenColor(hex: string, factor: number): string;
+/**
+ * Create a node reducer for Sigma with zoom-based visibility
+ *
+ * @param state - Current reducer state (with optional zoom level)
+ * @param theme - Sigma theme configuration
+ * @returns Node reducer function
+ */
+declare function createNodeReducer(state: ReducerState | ZoomReducerState, theme: SigmaTheme): (node: string, data: Attributes) => Attributes;
+/**
+ * Create an edge reducer for Sigma with zoom-based visibility
+ *
+ * @param state - Current reducer state (with optional zoom level)
+ * @param theme - Sigma theme configuration
+ * @param graph - Optional graph to look up edge endpoints for selection highlighting
+ * @returns Edge reducer function
+ *
+ * @remarks
+ * The returned function signature matches Sigma's expected edge reducer format.
+ * For selection/highlight logic that needs source/target info, pass the graph parameter.
+ */
+declare function createEdgeReducer(state: ReducerState | ZoomReducerState, theme: SigmaTheme, graph?: Graph.default): (edge: string, data: Attributes) => Attributes;
+
+/**
+ * CodeViz - Interactive 2D codebase visualization with hierarchical semantic zoom
  *
  * @packageDocumentation
  */
 declare const VERSION = "0.1.0";
-interface CodeVizConfig {
-}
-declare function createCodeViz(_config?: CodeVizConfig): void;
 
-export { type CodeVizConfig, VERSION, createCodeViz };
+export { type AnalysisError, type AnalysisProgress, type AnalysisResult, type AnalysisStats, type AnalyzerConfig, CallEdge, CodeGraph, CodeMap, DEFAULT_DARK_SIGMA_THEME, DEFAULT_LIGHT_SIGMA_THEME, DEFAULT_SIGMA_THEME, DirectoryNode, EDGE_SIZES, type FA2Settings, FileMetrics, FileNode, IOverlayPort, ImportEdge, type InitialPositionOptions, MapNode, NODE_SIZES, Overlay, type ReducerState, type ScanResult, type ScannerConfig, SigmaRenderer, type SigmaRendererHandle, type SigmaRendererProps, SigmaTheme, SourceLocation, type SymbolExtractionResult, SymbolNode, Theme, type UseSigmaOptions, type UseSigmaReturn, VERSION, ViewMode, ZoomLevel, ZoomLevelConfig, analyzeCodebase, assignInitialPositions, brightenColor, buildFileIndex, buildGlobalSymbolIndex, createEdgeReducer, createNodeReducer, dimColor, extractCalls, extractImports, extractSymbols, extractSymbolsFromFile, getFA2Settings, getLanguageRegistry, getLayoutDuration, getNodeMass, getParserManager, getScaledNodeSize, getSigmaTheme, nexusToGraphology, resetAnalyzer, resetLanguageRegistry, resetParserManager, resolveFileCalls, resolveImport, scanDirectory, structureToGraphology, useSigma };