@saluzi/codegraph 0.1.0 → 0.2.0

package/dist/sync/watcher.js

@@ -1,192 +0,0 @@
-"use strict";
-/**
- * File Watcher
- *
- * Watches the project directory for file changes and triggers
- * debounced sync operations to keep the code graph up-to-date.
- *
- * Uses Node.js native fs.watch with recursive mode (macOS FSEvents,
- * Windows ReadDirectoryChangesW, Linux inotify on Node 19+).
- */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.FileWatcher = void 0;
-const fs = __importStar(require("fs"));
-const extraction_1 = require("../extraction");
-const errors_1 = require("../errors");
-const utils_1 = require("../utils");
-const watch_policy_1 = require("./watch-policy");
-/**
- * FileWatcher monitors a project directory for changes and triggers
- * debounced sync operations via a provided callback.
- *
- * Design goals:
- * - Minimal resource usage (native OS file events, no polling)
- * - Debounced to avoid thrashing on rapid saves
- * - Filters to supported source files by extension
- * - Ignores .codegraph/ directory changes
- */
-class FileWatcher {
-    watcher = null;
-    debounceTimer = null;
-    hasChanges = false;
-    syncing = false;
-    stopped = false;
-    projectRoot;
-    debounceMs;
-    syncFn;
-    onSyncComplete;
-    onSyncError;
-    constructor(projectRoot, syncFn, options = {}) {
-        this.projectRoot = projectRoot;
-        this.syncFn = syncFn;
-        this.debounceMs = options.debounceMs ?? 2000;
-        this.onSyncComplete = options.onSyncComplete;
-        this.onSyncError = options.onSyncError;
-    }
-    /**
-     * Start watching for file changes.
-     * Returns true if watching started successfully, false otherwise.
-     */
-    start() {
-        if (this.watcher)
-            return true; // Already watching
-        this.stopped = false;
-        // Some environments make recursive fs.watch unusable — most notably WSL2
-        // /mnt/ drives, where setup blocks long enough to break MCP startup
-        // handshakes (issue #199). Skip watching there; callers fall back to
-        // manual `codegraph sync` or the git sync hooks.
-        const disabledReason = (0, watch_policy_1.watchDisabledReason)(this.projectRoot);
-        if (disabledReason) {
-            (0, errors_1.logDebug)('File watcher disabled', { reason: disabledReason, projectRoot: this.projectRoot });
-            return false;
-        }
-        try {
-            this.watcher = fs.watch(this.projectRoot, { recursive: true }, (_eventType, filename) => {
-                if (!filename || this.stopped)
-                    return;
-                // Normalize path separators
-                const normalized = (0, utils_1.normalizePath)(filename);
-                // Ignore .codegraph/ directory changes (our own DB writes)
-                if (normalized === '.codegraph' ||
-                    normalized.startsWith('.codegraph/') ||
-                    normalized.startsWith('.codegraph\\')) {
-                    return;
-                }
-                // Only sync changes to files we can actually parse.
-                if (!(0, extraction_1.isSourceFile)(normalized)) {
-                    return;
-                }
-                (0, errors_1.logDebug)('File change detected', { file: normalized });
-                this.hasChanges = true;
-                this.scheduleSync();
-            });
-            // Handle watcher errors gracefully
-            this.watcher.on('error', (err) => {
-                (0, errors_1.logWarn)('File watcher error', { error: String(err) });
-                // Don't crash — watcher may recover or user can restart
-            });
-            (0, errors_1.logDebug)('File watcher started', { projectRoot: this.projectRoot, debounceMs: this.debounceMs });
-            return true;
-        }
-        catch (err) {
-            // Recursive watch not supported (e.g., Linux < Node 19)
-            (0, errors_1.logWarn)('Could not start file watcher — recursive fs.watch not supported on this platform', { error: String(err) });
-            return false;
-        }
-    }
-    /**
-     * Stop watching for file changes.
-     */
-    stop() {
-        this.stopped = true;
-        if (this.debounceTimer) {
-            clearTimeout(this.debounceTimer);
-            this.debounceTimer = null;
-        }
-        if (this.watcher) {
-            this.watcher.close();
-            this.watcher = null;
-        }
-        this.hasChanges = false;
-        (0, errors_1.logDebug)('File watcher stopped');
-    }
-    /**
-     * Whether the watcher is currently active.
-     */
-    isActive() {
-        return this.watcher !== null && !this.stopped;
-    }
-    /**
-     * Schedule a debounced sync.
-     */
-    scheduleSync() {
-        if (this.debounceTimer) {
-            clearTimeout(this.debounceTimer);
-        }
-        this.debounceTimer = setTimeout(() => {
-            this.debounceTimer = null;
-            this.flush();
-        }, this.debounceMs);
-    }
-    /**
-     * Flush pending changes by running sync.
-     */
-    async flush() {
-        // If already syncing, the post-sync check will re-trigger
-        if (this.syncing || this.stopped)
-            return;
-        this.hasChanges = false;
-        this.syncing = true;
-        try {
-            const result = await this.syncFn();
-            this.onSyncComplete?.(result);
-        }
-        catch (err) {
-            const error = err instanceof Error ? err : new Error(String(err));
-            (0, errors_1.logWarn)('Watch sync failed', { error: error.message });
-            this.onSyncError?.(error);
-        }
-        finally {
-            this.syncing = false;
-            // If new changes arrived during sync, schedule another
-            if (this.hasChanges && !this.stopped) {
-                this.scheduleSync();
-            }
-        }
-    }
-}
-exports.FileWatcher = FileWatcher;
-//# sourceMappingURL=watcher.js.map

package/dist/types.d.ts

@@ -1,433 +0,0 @@
-/**
- * CodeGraph Type Definitions
- *
- * Core types for the semantic knowledge graph system.
- */
-/**
- * Types of nodes in the knowledge graph.
- *
- * Defined as a runtime-iterable `as const` array so the same source
- * of truth backs both the TS type and any runtime validation
- * (e.g. the search query parser).
- */
-export declare const NODE_KINDS: readonly [
-  'file',
-  'module',
-  'class',
-  'struct',
-  'interface',
-  'trait',
-  'protocol',
-  'function',
-  'method',
-  'property',
-  'field',
-  'variable',
-  'constant',
-  'enum',
-  'enum_member',
-  'type_alias',
-  'namespace',
-  'parameter',
-  'import',
-  'export',
-  'route',
-  'component',
-]
-export type NodeKind = (typeof NODE_KINDS)[number]
-/**
- * Types of edges (relationships) between nodes
- */
-export type EdgeKind =
-  | 'contains'
-  | 'calls'
-  | 'imports'
-  | 'exports'
-  | 'extends'
-  | 'implements'
-  | 'references'
-  | 'type_of'
-  | 'returns'
-  | 'instantiates'
-  | 'overrides'
-  | 'decorates'
-/**
- * Supported programming languages. See NODE_KINDS for why this is a
- * runtime-iterable const array.
- */
-export declare const LANGUAGES: readonly [
-  'typescript',
-  'javascript',
-  'tsx',
-  'jsx',
-  'python',
-  'go',
-  'rust',
-  'java',
-  'c',
-  'cpp',
-  'csharp',
-  'php',
-  'ruby',
-  'swift',
-  'kotlin',
-  'dart',
-  'svelte',
-  'vue',
-  'liquid',
-  'pascal',
-  'scala',
-  'lua',
-  'luau',
-  'yaml',
-  'twig',
-  'unknown',
-]
-export type Language = (typeof LANGUAGES)[number]
-/**
- * A node in the knowledge graph representing a code symbol
- */
-export interface Node {
-  /** Unique identifier (hash of file path + qualified name) */
-  id: string
-  /** Type of code element */
-  kind: NodeKind
-  /** Simple name (e.g., "calculateTotal") */
-  name: string
-  /** Fully qualified name (e.g., "src/utils.ts::MathHelper.calculateTotal") */
-  qualifiedName: string
-  /** File path relative to project root */
-  filePath: string
-  /** Programming language */
-  language: Language
-  /** Starting line number (1-indexed) */
-  startLine: number
-  /** Ending line number (1-indexed) */
-  endLine: number
-  /** Starting column (0-indexed) */
-  startColumn: number
-  /** Ending column (0-indexed) */
-  endColumn: number
-  /** Documentation string if present */
-  docstring?: string
-  /** Function/method signature */
-  signature?: string
-  /** Visibility modifier */
-  visibility?: 'public' | 'private' | 'protected' | 'internal'
-  /** Whether symbol is exported */
-  isExported?: boolean
-  /** Whether symbol is async */
-  isAsync?: boolean
-  /** Whether symbol is static */
-  isStatic?: boolean
-  /** Whether symbol is abstract */
-  isAbstract?: boolean
-  /** Decorators/annotations applied */
-  decorators?: string[]
-  /** Generic type parameters */
-  typeParameters?: string[]
-  /** When the node was last updated */
-  updatedAt: number
-}
-/**
- * An edge representing a relationship between two nodes
- */
-export interface Edge {
-  /** Source node ID */
-  source: string
-  /** Target node ID */
-  target: string
-  /** Type of relationship */
-  kind: EdgeKind
-  /** Additional context about the relationship */
-  metadata?: Record<string, unknown>
-  /** Line number where relationship occurs (e.g., call site) */
-  line?: number
-  /** Column number where relationship occurs */
-  column?: number
-  /** How this edge was created */
-  provenance?: 'tree-sitter' | 'scip' | 'heuristic'
-}
-/**
- * Metadata about a tracked file
- */
-export interface FileRecord {
-  /** File path relative to project root */
-  path: string
-  /** Content hash for change detection */
-  contentHash: string
-  /** Detected language */
-  language: Language
-  /** File size in bytes */
-  size: number
-  /** Last modification timestamp */
-  modifiedAt: number
-  /** When last indexed */
-  indexedAt: number
-  /** Number of nodes extracted */
-  nodeCount: number
-  /** Any extraction errors */
-  errors?: ExtractionError[]
-}
-/**
- * Result from parsing a source file
- */
-export interface ExtractionResult {
-  /** Extracted nodes */
-  nodes: Node[]
-  /** Extracted edges */
-  edges: Edge[]
-  /** References that couldn't be resolved yet */
-  unresolvedReferences: UnresolvedReference[]
-  /** Any errors during extraction */
-  errors: ExtractionError[]
-  /** Extraction duration in milliseconds */
-  durationMs: number
-}
-/**
- * Error during code extraction
- */
-export interface ExtractionError {
-  /** Error message */
-  message: string
-  /** File path where the error occurred */
-  filePath?: string
-  /** Line number if available */
-  line?: number
-  /** Column number if available */
-  column?: number
-  /** Error severity */
-  severity: 'error' | 'warning'
-  /** Error code for categorization */
-  code?: string
-}
-/**
- * A reference that couldn't be resolved during extraction
- */
-export interface UnresolvedReference {
-  /** ID of the node containing the reference */
-  fromNodeId: string
-  /** Name being referenced */
-  referenceName: string
-  /** Type of reference (call, type, import, etc.) */
-  referenceKind: EdgeKind
-  /** Location of the reference */
-  line: number
-  column: number
-  /** File path where reference occurs (denormalized for performance) */
-  filePath?: string
-  /** Language of the source file (denormalized for performance) */
-  language?: Language
-  /** Possible qualified names it might resolve to */
-  candidates?: string[]
-}
-/**
- * A subgraph containing a subset of the knowledge graph
- */
-export interface Subgraph {
-  /** Nodes in this subgraph */
-  nodes: Map<string, Node>
-  /** Edges in this subgraph */
-  edges: Edge[]
-  /** Root node IDs (entry points) */
-  roots: string[]
-}
-/**
- * Options for graph traversal
- */
-export interface TraversalOptions {
-  /** Maximum depth to traverse (default: Infinity) */
-  maxDepth?: number
-  /** Edge types to follow (default: all) */
-  edgeKinds?: EdgeKind[]
-  /** Node types to include (default: all) */
-  nodeKinds?: NodeKind[]
-  /** Direction of traversal */
-  direction?: 'outgoing' | 'incoming' | 'both'
-  /** Maximum nodes to return */
-  limit?: number
-  /** Whether to include the starting node */
-  includeStart?: boolean
-}
-/**
- * Options for searching the graph
- */
-export interface SearchOptions {
-  /** Node types to search */
-  kinds?: NodeKind[]
-  /** Languages to include */
-  languages?: Language[]
-  /** File path patterns to include */
-  includePatterns?: string[]
-  /** File path patterns to exclude */
-  excludePatterns?: string[]
-  /** Maximum results to return */
-  limit?: number
-  /** Offset for pagination */
-  offset?: number
-  /** Whether search is case-sensitive */
-  caseSensitive?: boolean
-}
-/**
- * A search result with relevance scoring
- */
-export interface SearchResult {
-  /** Matching node */
-  node: Node
-  /** Relevance score (0-1) */
-  score: number
-  /** Matched text snippets for highlighting */
-  highlights?: string[]
-}
-/**
- * Context information for code understanding
- */
-export interface Context {
-  /** Primary node being examined */
-  focal: Node
-  /** Nodes containing the focal node (file, class, etc.) */
-  ancestors: Node[]
-  /** Nodes directly contained by focal node */
-  children: Node[]
-  /** Incoming references (who calls/uses this) */
-  incomingRefs: Array<{
-    node: Node
-    edge: Edge
-  }>
-  /** Outgoing references (what this calls/uses) */
-  outgoingRefs: Array<{
-    node: Node
-    edge: Edge
-  }>
-  /** Related type information */
-  types: Node[]
-  /** Relevant imports */
-  imports: Node[]
-}
-/**
- * A block of code with context
- */
-export interface CodeBlock {
-  /** The code content */
-  content: string
-  /** File path */
-  filePath: string
-  /** Starting line */
-  startLine: number
-  /** Ending line */
-  endLine: number
-  /** Language for syntax highlighting */
-  language: Language
-  /** Associated node if extracted */
-  node?: Node
-}
-/**
- * Database schema version info
- */
-export interface SchemaVersion {
-  /** Current schema version */
-  version: number
-  /** When schema was created/updated */
-  appliedAt: number
-  /** Description of this version */
-  description?: string
-}
-/**
- * Statistics about the knowledge graph
- */
-export interface GraphStats {
-  /** Total number of nodes */
-  nodeCount: number
-  /** Total number of edges */
-  edgeCount: number
-  /** Number of tracked files */
-  fileCount: number
-  /** Node counts by kind */
-  nodesByKind: Record<NodeKind, number>
-  /** Edge counts by kind */
-  edgesByKind: Record<EdgeKind, number>
-  /** File counts by language */
-  filesByLanguage: Record<Language, number>
-  /** Database size in bytes */
-  dbSizeBytes: number
-  /** Last update timestamp */
-  lastUpdated: number
-}
-/**
- * Input for building task context
- */
-export type TaskInput =
-  | string
-  | {
-      title: string
-      description?: string
-    }
-/**
- * Options for building task context
- */
-export interface BuildContextOptions {
-  /** Maximum number of nodes to include (default: 50) */
-  maxNodes?: number
-  /** Maximum number of code blocks to include (default: 10) */
-  maxCodeBlocks?: number
-  /** Maximum characters per code block (default: 2000) */
-  maxCodeBlockSize?: number
-  /** Whether to include code blocks (default: true) */
-  includeCode?: boolean
-  /** Output format (default: 'markdown') */
-  format?: 'markdown' | 'json'
-  /** Number of semantic search results (default: 5) */
-  searchLimit?: number
-  /** Graph traversal depth from entry points (default: 2) */
-  traversalDepth?: number
-  /** Minimum semantic similarity score (default: 0.3) */
-  minScore?: number
-}
-/**
- * Full context for a task, ready for Claude
- */
-export interface TaskContext {
-  /** The original query/task */
-  query: string
-  /** Subgraph of relevant nodes and edges */
-  subgraph: Subgraph
-  /** Entry point nodes (from semantic search) */
-  entryPoints: Node[]
-  /** Code blocks extracted from key nodes */
-  codeBlocks: CodeBlock[]
-  /** Files involved in this context */
-  relatedFiles: string[]
-  /** Brief summary of the context */
-  summary: string
-  /** Statistics about the context */
-  stats: {
-    /** Number of nodes included */
-    nodeCount: number
-    /** Number of edges included */
-    edgeCount: number
-    /** Number of files touched */
-    fileCount: number
-    /** Number of code blocks included */
-    codeBlockCount: number
-    /** Total characters in code blocks */
-    totalCodeSize: number
-  }
-}
-/**
- * Options for finding relevant context
- */
-export interface FindRelevantContextOptions {
-  /** Number of semantic search results (default: 5) */
-  searchLimit?: number
-  /** Graph traversal depth (default: 2) */
-  traversalDepth?: number
-  /** Maximum nodes in result (default: 50) */
-  maxNodes?: number
-  /** Minimum semantic similarity score (default: 0.3) */
-  minScore?: number
-  /** Edge types to follow in traversal */
-  edgeKinds?: EdgeKind[]
-  /** Node types to include */
-  nodeKinds?: NodeKind[]
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,75 +0,0 @@
-"use strict";
-/**
- * CodeGraph Type Definitions
- *
- * Core types for the semantic knowledge graph system.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LANGUAGES = exports.NODE_KINDS = void 0;
-// =============================================================================
-// Union Types
-// =============================================================================
-/**
- * Types of nodes in the knowledge graph.
- *
- * Defined as a runtime-iterable `as const` array so the same source
- * of truth backs both the TS type and any runtime validation
- * (e.g. the search query parser).
- */
-exports.NODE_KINDS = [
-    'file',
-    'module',
-    'class',
-    'struct',
-    'interface',
-    'trait',
-    'protocol',
-    'function',
-    'method',
-    'property',
-    'field',
-    'variable',
-    'constant',
-    'enum',
-    'enum_member',
-    'type_alias',
-    'namespace',
-    'parameter',
-    'import',
-    'export',
-    'route',
-    'component',
-];
-/**
- * Supported programming languages. See NODE_KINDS for why this is a
- * runtime-iterable const array.
- */
-exports.LANGUAGES = [
-    'typescript',
-    'javascript',
-    'tsx',
-    'jsx',
-    'python',
-    'go',
-    'rust',
-    'java',
-    'c',
-    'cpp',
-    'csharp',
-    'php',
-    'ruby',
-    'swift',
-    'kotlin',
-    'dart',
-    'svelte',
-    'vue',
-    'liquid',
-    'pascal',
-    'scala',
-    'lua',
-    'luau',
-    'yaml',
-    'twig',
-    'unknown',
-];
-//# sourceMappingURL=types.js.map