@egentica/codemap 0.1.5

package/dist/core/FileSystemGraph.js

@@ -0,0 +1,316 @@
+"use strict";
+/**
+ * FileSystemGraph — The Foundation Layer
+ *
+ * Passive knowledge base for files, directories, symbols, and import dependencies.
+ * Pure in-memory graph operations — no I/O, no side effects.
+ *
+ * @codemap.domain.name Dependency Graph
+ * @codemap.usage Add new query methods for graph traversal (find related files, traverse dependencies)
+ * @codemap.usage Modify symbol or dependency storage structures
+ * @codemap.usage Implement new graph algorithms (shortest path, connected components, etc)
+ * @codemap.usage Add caching or indexing optimizations for queries
+ * @codemap.usage Fix bugs in dependency tracking or symbol lookups
+ * @codemap.policy This is a pure data structure. No file operations, no event emission.
+ * @codemap.policy All I/O happens in FileSystemIO (the gateway). Graph is read-only to plugins.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileSystemGraph = void 0;
+/**
+ * FileSystemGraph stores the complete project knowledge graph.
+ *
+ * Data structures:
+ * - files: Map<relativePath, FileEntry>
+ * - directories: Map<relativePath, DirEntry>
+ * - dependencies: Set<DependencyEdge> (import edges)
+ *
+ * Query methods:
+ * - getFile, getDirectory, getSymbol
+ * - findImporters, findImports (dependency traversal)
+ * - traverse (BFS/DFS graph traversal)
+ */
+class FileSystemGraph {
+    files;
+    directories;
+    dependencies; // Stored as "from->to" strings for deduplication
+    /**
+     * Root path of the project this graph represents.
+     */
+    rootPath;
+    /**
+     * Timestamp of last full scan.
+     */
+    lastFullScan;
+    constructor(rootPath) {
+        this.rootPath = rootPath;
+        this.files = new Map();
+        this.directories = new Map();
+        this.dependencies = new Set();
+        this.lastFullScan = 0;
+    }
+    // ── File Operations ────────────────────────────────────────────────────────
+    /**
+     * Add or update a file in the graph.
+     */
+    addFile(file) {
+        this.files.set(file.relativePath, file);
+    }
+    /**
+     * Get a file by relative path.
+     */
+    getFile(relativePath) {
+        return this.files.get(relativePath);
+    }
+    /**
+     * Remove a file from the graph.
+     */
+    removeFile(relativePath) {
+        return this.files.delete(relativePath);
+    }
+    /**
+     * Get all files in the graph.
+     */
+    getAllFiles() {
+        return Array.from(this.files.values());
+    }
+    /**
+     * Get file count.
+     */
+    getFileCount() {
+        return this.files.size;
+    }
+    // ── Directory Operations ───────────────────────────────────────────────────
+    /**
+     * Add or update a directory in the graph.
+     */
+    addDirectory(dir) {
+        this.directories.set(dir.relativePath, dir);
+    }
+    /**
+     * Get a directory by relative path.
+     */
+    getDirectory(relativePath) {
+        return this.directories.get(relativePath);
+    }
+    /**
+     * Remove a directory from the graph.
+     */
+    removeDirectory(relativePath) {
+        return this.directories.delete(relativePath);
+    }
+    /**
+     * Get all directories in the graph.
+     */
+    getAllDirectories() {
+        return Array.from(this.directories.values());
+    }
+    /**
+     * Get directory count.
+     */
+    getDirectoryCount() {
+        return this.directories.size;
+    }
+    /**
+     * Get dependency count.
+     */
+    getDependencyCount() {
+        return this.dependencies.size;
+    }
+    // ── Symbol Operations ──────────────────────────────────────────────────────
+    /**
+     * Get a symbol by searching all files.
+     * Returns first match (symbols should be unique per file, not globally).
+     *
+     * @param symbolName - Name of the symbol to find
+     * @param kind - Optional: filter by symbol kind
+     */
+    getSymbol(symbolName, kind) {
+        for (const file of this.files.values()) {
+            if (!file.symbols)
+                continue;
+            for (const symbol of file.symbols) {
+                if (symbol.name === symbolName && (!kind || symbol.kind === kind)) {
+                    return { file, symbol };
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Find all symbols matching a predicate.
+     */
+    findSymbols(predicate) {
+        const results = [];
+        for (const file of this.files.values()) {
+            if (!file.symbols)
+                continue;
+            for (const symbol of file.symbols) {
+                if (predicate(symbol, file)) {
+                    results.push({ file, symbol });
+                }
+            }
+        }
+        return results;
+    }
+    // ── Dependency Operations ──────────────────────────────────────────────────
+    /**
+     * Add a dependency edge (import relationship).
+     *
+     * @param from - Source file relativePath
+     * @param to - Imported file relativePath
+     */
+    addDependency(from, to) {
+        this.dependencies.add(`${from}->${to}`);
+        // Also update FileEntry.references and FileEntry.referencedBy
+        const fromFile = this.files.get(from);
+        const toFile = this.files.get(to);
+        if (fromFile && !fromFile.references.includes(to)) {
+            fromFile.references.push(to);
+        }
+        if (toFile && !toFile.referencedBy.includes(from)) {
+            toFile.referencedBy.push(from);
+        }
+    }
+    /**
+     * Remove a dependency edge.
+     */
+    removeDependency(from, to) {
+        const key = `${from}->${to}`;
+        const deleted = this.dependencies.delete(key);
+        if (deleted) {
+            // Also update FileEntry arrays
+            const fromFile = this.files.get(from);
+            const toFile = this.files.get(to);
+            if (fromFile) {
+                fromFile.references = fromFile.references.filter(r => r !== to);
+            }
+            if (toFile) {
+                toFile.referencedBy = toFile.referencedBy.filter(r => r !== from);
+            }
+        }
+        return deleted;
+    }
+    /**
+     * Find all files that import the given file.
+     *
+     * @param relativePath - File to find importers for
+     * @returns Array of files that import this file
+     */
+    findImporters(relativePath) {
+        const file = this.files.get(relativePath);
+        if (!file)
+            return [];
+        return file.referencedBy
+            .map(path => this.files.get(path))
+            .filter((f) => f !== undefined);
+    }
+    /**
+     * Find all files imported by the given file.
+     *
+     * @param relativePath - File to find imports for
+     * @returns Array of files imported by this file
+     */
+    findImports(relativePath) {
+        const file = this.files.get(relativePath);
+        if (!file)
+            return [];
+        return file.references
+            .map(path => this.files.get(path))
+            .filter((f) => f !== undefined);
+    }
+    /**
+     * Get related files (both importers and imports).
+     */
+    getRelated(relativePath) {
+        return {
+            references: this.findImports(relativePath),
+            referencedBy: this.findImporters(relativePath),
+        };
+    }
+    // ── Traversal ──────────────────────────────────────────────────────────────
+    /**
+     * Traverse the dependency graph starting from a file.
+     *
+     * @param startPath - Starting file relativePath
+     * @param direction - 'imports' (follow references) or 'importers' (follow referencedBy)
+     * @param maxDepth - Maximum depth to traverse (default: 3)
+     * @returns Array of files visited during traversal (BFS order)
+     */
+    traverse(startPath, direction, maxDepth = 3) {
+        const visited = new Set();
+        const result = [];
+        const queue = [{ path: startPath, depth: 0 }];
+        while (queue.length > 0) {
+            const { path, depth } = queue.shift();
+            if (visited.has(path) || depth > maxDepth)
+                continue;
+            const file = this.files.get(path);
+            if (!file)
+                continue;
+            visited.add(path);
+            result.push(file);
+            // Get next level based on direction
+            const nextPaths = direction === 'imports' ? file.references : file.referencedBy;
+            for (const nextPath of nextPaths) {
+                if (!visited.has(nextPath)) {
+                    queue.push({ path: nextPath, depth: depth + 1 });
+                }
+            }
+        }
+        return result;
+    }
+    // ── Export / Import ────────────────────────────────────────────────────────
+    /**
+     * Export the entire graph as ProjectMapData (for persistence).
+     */
+    toJSON() {
+        const filesObj = {};
+        const dirsObj = {};
+        for (const [path, file] of this.files) {
+            filesObj[path] = file;
+        }
+        for (const [path, dir] of this.directories) {
+            dirsObj[path] = dir;
+        }
+        return {
+            rootPath: this.rootPath,
+            lastFullScan: this.lastFullScan,
+            files: filesObj,
+            directories: dirsObj,
+        };
+    }
+    /**
+     * Import graph data from ProjectMapData (load from persistence).
+     */
+    fromJSON(data) {
+        this.files.clear();
+        this.directories.clear();
+        this.dependencies.clear();
+        this.lastFullScan = data.lastFullScan;
+        // Load files
+        for (const [path, file] of Object.entries(data.files)) {
+            this.files.set(path, file);
+        }
+        // Load directories
+        for (const [path, dir] of Object.entries(data.directories)) {
+            this.directories.set(path, dir);
+        }
+        // Rebuild dependencies from FileEntry.references
+        for (const file of this.files.values()) {
+            for (const ref of file.references) {
+                this.dependencies.add(`${file.relativePath}->${ref}`);
+            }
+        }
+    }
+    /**
+     * Clear all data from the graph.
+     */
+    clear() {
+        this.files.clear();
+        this.directories.clear();
+        this.dependencies.clear();
+        this.lastFullScan = 0;
+    }
+}
+exports.FileSystemGraph = FileSystemGraph;
+//# sourceMappingURL=FileSystemGraph.js.map

package/dist/core/FileSystemGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemGraph.js","sourceRoot":"","sources":["../../src/core/FileSystemGraph.ts"],"names":[],"mappings":"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"}

package/dist/core/FileSystemIO.d.ts

@@ -0,0 +1,222 @@
+/**
+ * FileSystemIO — The Controlled Gateway
+ *
+ * All file operations in CodeMap flow through this gateway.
+ * Wraps FileSystemProvider and emits lifecycle events for plugins.
+ *
+ * NEW FEATURES:
+ * - Line range writes via LineRangeWriter
+ * - Target parsing with wildcards and line ranges
+ * - Annotation metadata via AnnotationStore
+ *
+ * This is where TimeWarp hooks into file:write:before to capture snapshots.
+ * Plugins CANNOT bypass this gateway — no direct FS access allowed.
+ *
+ * @codemap.domain.name File System Gateway
+ * @codemap.usage Add new file operation types (copy, move, chmod, etc)
+ * @codemap.usage Modify event emission logic for lifecycle hooks (file:write:before, file:write:after)
+ * @codemap.usage Integrate new features (line range operations, wildcards, safety guards)
+ * @codemap.usage Fix file operation bugs or add validation/safety checks
+ * @codemap.usage Change how FileSystemProvider is wrapped or called
+ * @codemap.policy This is the ONLY place in CodeMap that touches FileSystemProvider.
+ * @codemap.policy All plugins must use codemap.fs — no bypass, no history gaps.
+ * @codemap.warning Event handlers are async. await emit() before continuing.
+ */
+import type { FileSystemProvider } from '../types/contracts/FileSystemProvider';
+import type { EventHandler } from '../types/contracts/Plugin';
+import type { CodeMapEvent } from '../types/events';
+import type { ParsedTarget, LineRangeWriteResult } from '../types';
+import { AnnotationStore } from './AnnotationStore';
+import { WriteSafetyGuard } from './WriteSafetyGuard';
+import type { SafeWriteResult } from './WriteSafetyGuard';
+/**
+ * Write operation parameters.
+ */
+interface WriteOptions {
+    /** If true, interpret content as line range replacement */
+    lineRange?: {
+        start: number;
+        end: number;
+    };
+    /** Emit events (default: true) */
+    emitEvents?: boolean;
+    /** Skip syntax validation (default: false) */
+    skipValidation?: boolean;
+}
+/**
+ * FileSystemIO wraps a storage provider and emits lifecycle events.
+ *
+ * Lifecycle flow:
+ * 1. Plugin registers handler via codemap.on('file:write:before', handler)
+ * 2. User calls codemap.fs.write(path, content)
+ * 3. FileSystemIO emits 'file:write:before' → handlers run (TimeWarp captures)
+ * 4. FileSystemIO calls provider.write(path, content)
+ * 5. FileSystemIO emits 'file:write:after' → handlers run (graph updates)
+ *
+ * Result: No writes can bypass history tracking.
+ */
+export declare class FileSystemIO {
+    private provider;
+    private eventHandlers;
+    private targetParser;
+    private lineRangeWriter;
+    private annotationStore;
+    private safetyGuard;
+    private codemap;
+    constructor(provider: FileSystemProvider, codemapRoot?: string);
+    /**
+     * Set CodeMap reference for parser access.
+     * Called during CodeMap initialization.
+     *
+     * @param codemap - CodeMap instance
+     */
+    setCodeMap(codemap: any): void;
+    /**
+     * Register an event handler.
+     * Used internally by CodeMap to wire up plugin hooks.
+     */
+    on(event: CodeMapEvent, handler: EventHandler): void;
+    /**
+     * Emit an event to all registered handlers.
+     * Handlers run sequentially (await each before next).
+     */
+    private emit;
+    /**
+     * Parse a target string (supports wildcards and line ranges).
+     *
+     * @param target - Target string (e.g., "file.ts:10-20" or "src/*.vue")
+     * @returns Parsed target structure
+     */
+    parseTarget(target: string): ParsedTarget;
+    /**
+     * Resolve wildcards to concrete file paths.
+     *
+     * @param _pattern - Wildcard pattern (e.g., "src/components/*.vue")
+     * @returns Array of matching file paths
+     */
+    resolveWildcard(_pattern: string): Promise<string[]>;
+    /**
+     * Read file content.
+     * Supports line range extraction via target parsing.
+     *
+     * @param target - File path or "file.ts:10-20" for line range
+     * @returns File content (full or line range)
+     */
+    read(target: string): Promise<string>;
+    /**
+     * Check if file/directory exists.
+     * No lifecycle events — read is passive.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Read directory contents.
+     * No lifecycle events — read is passive.
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Get file/directory stats.
+     * No lifecycle events — read is passive.
+     */
+    stat(path: string): Promise<{
+        isDirectory: boolean;
+        size: number;
+        mtime: number;
+    }>;
+    /**
+     * Write file content.
+     * Supports line range replacement via target parsing.
+     *
+     * @param target - File path or "file.ts:10-20" for line range replacement
+     * @param content - Content to write
+     * @param options - Write options
+     * @returns Line range result if applicable, otherwise void
+     *
+     * @example
+     * // Full file write
+     * await fs.write("file.ts", "content")
+     *
+     * // Line range replacement
+     * await fs.write("file.ts:10-15", "new content")
+     * // → Replaces lines 10-15 with new content
+     */
+    write(target: string, content: string, options?: WriteOptions): Promise<void | LineRangeWriteResult>;
+    /**
+     * Append content to file.
+     *
+     * @param path - File path
+     * @param content - Content to append
+     * @param options - Write options (including skipValidation)
+     */
+    append(path: string, content: string, options?: WriteOptions): Promise<void>;
+    /**
+     * Remove file.
+     * Emits: file:delete
+     *
+     * TimeWarp can hook into this for deletion tracking.
+     */
+    remove(path: string): Promise<void>;
+    /**
+     * Create directory.
+     * No lifecycle events — directory creation is structural.
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Remove directory.
+     * No lifecycle events for now — can add if needed.
+     */
+    rmdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Rename/move file.
+     * Emits: file:rename
+     *
+     * TimeWarp can hook into this for history continuity across renames.
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Get annotation store for direct access.
+     * Used by higher-level operations that manage annotations.
+     */
+    getAnnotationStore(): AnnotationStore;
+    /**
+     * Attach annotations to a file (convenience method).
+     *
+     * @param target - File path
+     * @param annotations - Array of annotation strings
+     * @returns Attachment result
+     */
+    attachAnnotations(target: string, annotations: string[]): Promise<import("../types").AttachAnnotationsResult>;
+    /**
+     * Get annotations for a file (convenience method).
+     *
+     * @param target - File path
+     * @returns Annotation set (inline + meta)
+     */
+    getAnnotations(target: string): Promise<import("../types").AnnotationSet>;
+    /**
+     * Verify a replace operation before executing.
+     * Returns context around matches for user confirmation.
+     *
+     * @param path - File path
+     * @param oldString - String to find
+     * @returns Verification result
+     */
+    verifyReplace(path: string, oldString: string): Promise<import("./WriteSafetyGuard").ReplaceVerification>;
+    /**
+     * Safely replace text in file.
+     * Uses all write safety guarantees.
+     *
+     * @param path - File path
+     * @param oldString - Text to find (must be unique)
+     * @param newString - Replacement text
+     * @returns Write result
+     */
+    safeReplace(path: string, oldString: string, newString: string): Promise<SafeWriteResult>;
+    /**
+     * Get the safety guard instance for advanced operations.
+     */
+    getSafetyGuard(): WriteSafetyGuard;
+}
+export {};
+//# sourceMappingURL=FileSystemIO.d.ts.map

package/dist/core/FileSystemIO.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemIO.d.ts","sourceRoot":"","sources":["../../src/core/FileSystemIO.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGnE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAc1D;;GAEG;AACH,UAAU,YAAY;IACpB,2DAA2D;IAC3D,SAAS,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAE3C,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,aAAa,CAAoC;IACzD,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,OAAO,CAAoB;gBAGjC,QAAQ,EAAE,kBAAkB,EAC5B,WAAW,GAAE,MAAmB;IAUlC;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI;IAI9B;;;OAGG;IACH,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAOpD;;;OAGG;YACW,IAAI;IASlB;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY;IAIzC;;;;;OAKG;IACG,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAQ1D;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAwB3C;;;OAGG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5C;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAI9C;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAMxF;;;;;;;;;;;;;;;;OAgBG;IACG,KAAK,CACT,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,GAAG,oBAAoB,CAAC;IA+FvC;;;;;;OAMG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlF;;;;;OAKG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAezC;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC;;;OAGG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3E;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB7D;;;OAGG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;;;;;OAMG;IACG,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE;IAI7D;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,MAAM;IAMnC;;;;;;;OAOG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAInD;;;;;;;;OAQG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;IAIpE;;OAEG;IACH,cAAc;CAGf"}