@egentica/codemap 0.1.5

package/dist/core/ExperienceTracker.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * ExperienceTracker - Records all CodeMap operations for self-improving discovery.
+ *
+ * Subscribes to FileSystemIO events and records:
+ * - Operation outcomes (success/failure)
+ * - Search journeys (query → read → write paths)
+ * - Anti-results (dead ends, abandoned paths)
+ *
+ * This data powers AssistMap's experience-weighted scoring.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ExperienceTracker(store, eventBus);
+ *
+ * // Tracker automatically subscribes to events:
+ * // - file:write:before/after → Records writes
+ * // - file:read → Tracks reads in current journey
+ * // - search:executed → Records search steps
+ *
+ * // Manual journey tracking
+ * tracker.startJourney('find TaskCard component');
+ * tracker.recordSearch('assist', 'TaskCard', ['TaskCard.vue', 'TaskList.vue']);
+ * tracker.recordRead('TaskCard.vue');
+ * await tracker.recordSuccessfulWrite('TaskCard.vue', 'edit');
+ * // → Completes journey, records anti-results, updates patterns
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExperienceTracker = void 0;
+class ExperienceTracker {
+    store;
+    eventBus;
+    currentJourney = null;
+    operationContexts;
+    lastAssistQuery = null;
+    constructor(store, eventBus, enabled = true) {
+        this.store = store;
+        this.eventBus = eventBus;
+        this.operationContexts = new Map();
+        if (enabled) {
+            this.wireEventHandlers();
+        }
+    }
+    /**
+     * Wire up event handlers to track all operations.
+     */
+    wireEventHandlers() {
+        // Track file writes
+        this.eventBus.on('file:write:before', async (payload) => {
+            this.recordOperationStart('codemap_write', payload.operation || 'write', payload.path);
+        });
+        this.eventBus.on('file:write:after', async (payload) => {
+            await this.recordOperationComplete('codemap_write', payload.operation || 'write', payload.path, 'success');
+            // If journey is active, this might be the completion
+            if (this.currentJourney && payload.path) {
+                await this.recordSuccessfulWrite(payload.path, payload.operation || 'write');
+            }
+        });
+        // Track file reads (for journey tracking)
+        this.eventBus.on('file:read', async (payload) => {
+            if (this.currentJourney && payload.path) {
+                this.recordRead(payload.path);
+            }
+        });
+        // Track searches
+        this.eventBus.on('search:executed', async (payload) => {
+            if (payload.query && payload.results) {
+                this.recordSearch(payload.operation || 'search', payload.query, payload.results);
+            }
+        });
+    }
+    // ── Operation Tracking ─────────────────────────────────────────────────────
+    /**
+     * Record operation start.
+     *
+     * @param tool - Tool name (e.g., 'codemap_read')
+     * @param operation - Operation name (e.g., 'content')
+     * @param target - Target file/directory
+     */
+    recordOperationStart(tool, operation, target) {
+        const contextId = `${tool}:${operation}:${target || 'none'}:${Date.now()}`;
+        this.operationContexts.set(contextId, {
+            tool,
+            operation,
+            target,
+            startTime: Date.now()
+        });
+    }
+    /**
+     * Record operation completion.
+     *
+     * @param tool - Tool name
+     * @param operation - Operation name
+     * @param target - Target file/directory
+     * @param outcome - Operation outcome
+     */
+    async recordOperationComplete(tool, operation, target, outcome) {
+        // Find matching context (most recent)
+        let matchingContext;
+        let matchingId;
+        for (const [id, ctx] of this.operationContexts.entries()) {
+            if (ctx.tool === tool && ctx.operation === operation && ctx.target === target) {
+                matchingContext = ctx;
+                matchingId = id;
+            }
+        }
+        const durationMs = matchingContext
+            ? Date.now() - matchingContext.startTime
+            : undefined;
+        // Clean up context
+        if (matchingId) {
+            this.operationContexts.delete(matchingId);
+        }
+        // Create experience event
+        const event = {
+            id: this.generateEventId(),
+            timestamp: new Date().toISOString(),
+            tool,
+            operation,
+            target,
+            outcome,
+            durationMs,
+            sessionId: this.store.getSessionId(),
+            assistQuery: this.lastAssistQuery || undefined
+        };
+        // Append to store
+        await this.store.appendEvent(event);
+    }
+    // ── Search Journey Tracking ────────────────────────────────────────────────
+    /**
+     * Start a new search journey.
+     * Called when user initiates a search or assist operation.
+     *
+     * @param initialQuery - The query that started the journey
+     */
+    startJourney(initialQuery) {
+        this.currentJourney = {
+            sessionId: this.store.getSessionId(),
+            journeyId: this.generateJourneyId(),
+            startedAt: new Date().toISOString(),
+            searchPath: []
+        };
+        this.lastAssistQuery = initialQuery;
+    }
+    /**
+     * Record a search step in the current journey.
+     *
+     * @param operation - Search operation type
+     * @param query - Search query
+     * @param results - Results returned
+     */
+    recordSearch(operation, query, results) {
+        if (!this.currentJourney) {
+            // Auto-start journey if not already started
+            this.startJourney(query);
+        }
+        const step = {
+            operation,
+            query,
+            results,
+            selected: [],
+            rejected: [],
+            timestamp: new Date().toISOString()
+        };
+        this.currentJourney.searchPath.push(step);
+    }
+    /**
+     * Record that user read a file (from search results).
+     *
+     * @param filePath - File path that was read
+     */
+    recordRead(filePath) {
+        if (!this.currentJourney)
+            return;
+        // Find the most recent search step that included this file
+        for (let i = this.currentJourney.searchPath.length - 1; i >= 0; i--) {
+            const step = this.currentJourney.searchPath[i];
+            if (step.results.includes(filePath)) {
+                // Mark as selected
+                if (!step.selected.includes(filePath)) {
+                    step.selected.push(filePath);
+                }
+                // Mark other results as rejected (user saw them, didn't choose them)
+                step.rejected = step.results.filter(r => r !== filePath && !step.selected.includes(r));
+                break;
+            }
+        }
+    }
+    /**
+     * Record successful write - completes the journey.
+     *
+     * @param filePath - File that was successfully written
+     * @param operation - Write operation type
+     */
+    async recordSuccessfulWrite(filePath, operation) {
+        if (!this.currentJourney)
+            return;
+        // Complete the journey
+        this.currentJourney.completedAt = new Date().toISOString();
+        this.currentJourney.finalTarget = {
+            path: filePath,
+            operation: operation,
+            success: true,
+            timestamp: new Date().toISOString()
+        };
+        // Extract anti-results
+        const antiResults = this.extractAntiResults();
+        // Store journey
+        await this.store.recordJourney(this.currentJourney);
+        // Store anti-results
+        for (const antiResult of antiResults) {
+            await this.store.recordAntiResult(antiResult);
+        }
+        // Reset journey
+        this.currentJourney = null;
+        this.lastAssistQuery = null;
+    }
+    /**
+     * Extract anti-results from the current journey.
+     *
+     * @returns Array of anti-result entries
+     */
+    extractAntiResults() {
+        if (!this.currentJourney || !this.currentJourney.finalTarget) {
+            return [];
+        }
+        const antiResults = [];
+        const correctFile = this.currentJourney.finalTarget.path;
+        const sessionId = this.store.getSessionId();
+        const timestamp = new Date().toISOString();
+        for (const step of this.currentJourney.searchPath) {
+            // Files that were rejected (appeared in results but not selected)
+            for (const rejected of step.rejected) {
+                antiResults.push({
+                    correctFile,
+                    incorrectFile: rejected,
+                    query: step.query,
+                    reason: 'appeared_in_results_but_rejected',
+                    timestamp,
+                    sessionId
+                });
+            }
+            // Files that were selected but eventually abandoned
+            for (const selected of step.selected) {
+                if (selected !== correctFile) {
+                    antiResults.push({
+                        correctFile,
+                        incorrectFile: selected,
+                        query: step.query,
+                        reason: 'read_but_abandoned',
+                        timestamp,
+                        sessionId
+                    });
+                }
+            }
+        }
+        return antiResults;
+    }
+    // ── Utilities ──────────────────────────────────────────────────────────────
+    /**
+     * Generate a unique event ID.
+     */
+    generateEventId() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 9);
+        return `evt_${timestamp}_${random}`;
+    }
+    /**
+     * Generate a unique journey ID.
+     */
+    generateJourneyId() {
+        const timestamp = Date.now();
+        const random = Math.random().toString(36).substring(2, 9);
+        return `jrn_${timestamp}_${random}`;
+    }
+    /**
+     * Get the experience store.
+     */
+    getStore() {
+        return this.store;
+    }
+    /**
+     * Set the last assist query (used for attribution).
+     */
+    setLastAssistQuery(query) {
+        this.lastAssistQuery = query;
+    }
+}
+exports.ExperienceTracker = ExperienceTracker;
+//# sourceMappingURL=ExperienceTracker.js.map

package/dist/core/ExperienceTracker.js.map

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

package/dist/core/FileSystemGraph.d.ts

@@ -0,0 +1,157 @@
+/**
+ * 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.
+ */
+import type { FileEntry, DirEntry, SymbolEntry } from '../types/core';
+import type { ProjectMapData, RelatedResult } from '../types/graph';
+/**
+ * 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)
+ */
+export declare class FileSystemGraph {
+    private files;
+    private directories;
+    private dependencies;
+    /**
+     * Root path of the project this graph represents.
+     */
+    readonly rootPath: string;
+    /**
+     * Timestamp of last full scan.
+     */
+    lastFullScan: number;
+    constructor(rootPath: string);
+    /**
+     * Add or update a file in the graph.
+     */
+    addFile(file: FileEntry): void;
+    /**
+     * Get a file by relative path.
+     */
+    getFile(relativePath: string): FileEntry | undefined;
+    /**
+     * Remove a file from the graph.
+     */
+    removeFile(relativePath: string): boolean;
+    /**
+     * Get all files in the graph.
+     */
+    getAllFiles(): FileEntry[];
+    /**
+     * Get file count.
+     */
+    getFileCount(): number;
+    /**
+     * Add or update a directory in the graph.
+     */
+    addDirectory(dir: DirEntry): void;
+    /**
+     * Get a directory by relative path.
+     */
+    getDirectory(relativePath: string): DirEntry | undefined;
+    /**
+     * Remove a directory from the graph.
+     */
+    removeDirectory(relativePath: string): boolean;
+    /**
+     * Get all directories in the graph.
+     */
+    getAllDirectories(): DirEntry[];
+    /**
+     * Get directory count.
+     */
+    getDirectoryCount(): number;
+    /**
+     * Get dependency count.
+     */
+    getDependencyCount(): number;
+    /**
+     * 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: string, kind?: string): {
+        file: FileEntry;
+        symbol: SymbolEntry;
+    } | undefined;
+    /**
+     * Find all symbols matching a predicate.
+     */
+    findSymbols(predicate: (symbol: SymbolEntry, file: FileEntry) => boolean): Array<{
+        file: FileEntry;
+        symbol: SymbolEntry;
+    }>;
+    /**
+     * Add a dependency edge (import relationship).
+     *
+     * @param from - Source file relativePath
+     * @param to - Imported file relativePath
+     */
+    addDependency(from: string, to: string): void;
+    /**
+     * Remove a dependency edge.
+     */
+    removeDependency(from: string, to: string): boolean;
+    /**
+     * 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: string): FileEntry[];
+    /**
+     * 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: string): FileEntry[];
+    /**
+     * Get related files (both importers and imports).
+     */
+    getRelated(relativePath: string): RelatedResult;
+    /**
+     * 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: string, direction: 'imports' | 'importers', maxDepth?: number): FileEntry[];
+    /**
+     * Export the entire graph as ProjectMapData (for persistence).
+     */
+    toJSON(): ProjectMapData;
+    /**
+     * Import graph data from ProjectMapData (load from persistence).
+     */
+    fromJSON(data: ProjectMapData): void;
+    /**
+     * Clear all data from the graph.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=FileSystemGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FileSystemGraph.d.ts","sourceRoot":"","sources":["../../src/core/FileSystemGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAAc;IAElC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;gBAET,QAAQ,EAAE,MAAM;IAU5B;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI;IAI9B;;OAEG;IACH,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIpD;;OAEG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIzC;;OAEG;IACH,WAAW,IAAI,SAAS,EAAE;IAI1B;;OAEG;IACH,YAAY,IAAI,MAAM;IAMtB;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI;IAIjC;;OAEG;IACH,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIxD;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAI9C;;OAEG;IACH,iBAAiB,IAAI,QAAQ,EAAE;IAI/B;;OAEG;IACH,iBAAiB,IAAI,MAAM;IAI3B;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAM5B;;;;;;OAMG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,GAAG,SAAS;IAalG;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,GAAG,KAAK,CAAC;QAAE,IAAI,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC;IAkB1H;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IAgB7C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO;IAqBnD;;;;;OAKG;IACH,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE;IAShD;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE;IAS9C;;OAEG;IACH,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,aAAa;IAS/C;;;;;;;OAOG;IACH,QAAQ,CACN,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,GAAG,WAAW,EAClC,QAAQ,GAAE,MAAU,GACnB,SAAS,EAAE;IA+Bd;;OAEG;IACH,MAAM,IAAI,cAAc;IAoBxB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAyBpC;;OAEG;IACH,KAAK,IAAI,IAAI;CAMd"}