specmem-hardwicksoftware 3.5.99

package/dist/code-explanations/linkCodeToPrompt.js

@@ -0,0 +1,213 @@
+/**
+ * link_code_to_prompt - Associate code with conversation context
+ *
+ * Creates relationships between code files and memories/prompts
+ * to enable active recall of relevant code during conversations.
+ */
+import { v4 as uuidv4 } from 'uuid';
+import { logger } from '../utils/logger.js';
+import { LinkCodeToPromptInput } from './types.js';
+/**
+ * LinkCodeToPrompt - Create code-to-conversation links
+ *
+ * Features:
+ * - Multiple relationship types
+ * - Strength scoring
+ * - Context preservation
+ * - Duplicate prevention
+ */
+export class LinkCodeToPrompt {
+    db;
+    name = 'link_code_to_prompt';
+    description = `Create a link between code and a conversation memory. Relationship types:
+- referenced: Code was referenced in the conversation
+- explained: Code was explained to user
+- modified: User asked to modify this code
+- debugged: Code was debugged in conversation
+- created: Code was created in conversation
+- related: Code relates to conversation topic
+- imported: Code imports from this file
+- depends_on: Code depends on this file
+- tested: Code was tested or tests written`;
+    inputSchema = {
+        type: 'object',
+        properties: {
+            codeId: {
+                type: 'string',
+                format: 'uuid',
+                description: 'UUID of the code file (provide either this or filePath)'
+            },
+            filePath: {
+                type: 'string',
+                description: 'File path to link (provide either this or codeId)'
+            },
+            memoryId: {
+                type: 'string',
+                format: 'uuid',
+                description: 'UUID of the memory/prompt to link to'
+            },
+            relationshipType: {
+                type: 'string',
+                enum: ['referenced', 'explained', 'modified', 'debugged', 'created',
+                    'related', 'imported', 'depends_on', 'tested'],
+                default: 'referenced',
+                description: 'Type of relationship between code and prompt'
+            },
+            context: {
+                type: 'string',
+                description: 'Additional context about the relationship'
+            },
+            strength: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                default: 1,
+                description: 'Strength of the relationship (0-1)'
+            }
+        },
+        required: ['memoryId']
+    };
+    constructor(db) {
+        this.db = db;
+    }
+    async execute(params) {
+        const validatedParams = LinkCodeToPromptInput.parse(params);
+        logger.debug({
+            codeId: validatedParams.codeId,
+            filePath: validatedParams.filePath,
+            memoryId: validatedParams.memoryId
+        }, 'Creating code-prompt link');
+        try {
+            // Resolve codeId if only filePath provided
+            let codeId = validatedParams.codeId;
+            if (!codeId && validatedParams.filePath) {
+                const codeFile = await this.findCodeFileByPath(validatedParams.filePath);
+                if (codeFile) {
+                    codeId = codeFile.id;
+                }
+            }
+            // Verify memory exists
+            const memoryExists = await this.verifyMemoryExists(validatedParams.memoryId);
+            if (!memoryExists) {
+                return {
+                    success: false,
+                    message: `Memory ${validatedParams.memoryId} not found`
+                };
+            }
+            // Check for existing link
+            const existingLink = await this.findExistingLink(codeId, validatedParams.memoryId, validatedParams.relationshipType);
+            if (existingLink) {
+                // Update strength if existing link found
+                await this.updateLinkStrength(existingLink.id, validatedParams.strength, validatedParams.context);
+                logger.debug({ linkId: existingLink.id }, 'Updated existing link strength');
+                return {
+                    success: true,
+                    link: {
+                        ...existingLink,
+                        strength: validatedParams.strength,
+                        context: validatedParams.context ?? existingLink.context
+                    },
+                    message: `Updated existing ${validatedParams.relationshipType} link`
+                };
+            }
+            // Create new link
+            const id = uuidv4();
+            const now = new Date();
+            await this.db.query(`INSERT INTO code_prompt_links (
+          id, code_id, memory_id, relationship_type,
+          context, strength, created_at, metadata
+        ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`, [
+                id,
+                codeId ?? null,
+                validatedParams.memoryId,
+                validatedParams.relationshipType,
+                validatedParams.context ?? null,
+                validatedParams.strength,
+                now,
+                JSON.stringify({ filePath: validatedParams.filePath })
+            ]);
+            const link = {
+                id,
+                codeId: codeId ?? undefined,
+                memoryId: validatedParams.memoryId,
+                relationshipType: validatedParams.relationshipType,
+                context: validatedParams.context,
+                strength: validatedParams.strength,
+                createdAt: now,
+                metadata: { filePath: validatedParams.filePath }
+            };
+            logger.info({
+                linkId: id,
+                codeId,
+                memoryId: validatedParams.memoryId,
+                relationshipType: validatedParams.relationshipType
+            }, 'Code-prompt link created');
+            return {
+                success: true,
+                link,
+                message: `Created ${validatedParams.relationshipType} link between code and prompt`
+            };
+        }
+        catch (error) {
+            logger.error({
+                error,
+                codeId: validatedParams.codeId,
+                filePath: validatedParams.filePath
+            }, 'Failed to create code-prompt link');
+            return {
+                success: false,
+                message: error instanceof Error ? error.message : 'Failed to create link'
+            };
+        }
+    }
+    /**
+     * Find code file by path
+     */
+    async findCodeFileByPath(filePath) {
+        const result = await this.db.query(`SELECT id FROM codebase_files
+       WHERE file_path = $1 OR file_path LIKE $2
+       LIMIT 1`, [filePath, `%${filePath}`]);
+        return result.rows[0] ?? null;
+    }
+    /**
+     * Verify memory exists
+     */
+    async verifyMemoryExists(memoryId) {
+        const result = await this.db.query(`SELECT EXISTS(SELECT 1 FROM memories WHERE id = $1) as exists`, [memoryId]);
+        return result.rows[0]?.exists ?? false;
+    }
+    /**
+     * Find existing link
+     */
+    async findExistingLink(codeId, memoryId, relationshipType) {
+        const result = await this.db.query(`SELECT * FROM code_prompt_links
+       WHERE ($1::uuid IS NULL OR code_id = $1)
+       AND memory_id = $2
+       AND relationship_type = $3
+       LIMIT 1`, [codeId ?? null, memoryId, relationshipType]);
+        if (result.rows.length === 0)
+            return null;
+        const row = result.rows[0];
+        return {
+            id: row.id,
+            codeId: row.code_id ?? undefined,
+            memoryId: row.memory_id,
+            explanationId: row.explanation_id ?? undefined,
+            relationshipType: row.relationship_type,
+            context: row.context ?? undefined,
+            strength: row.strength,
+            createdAt: row.created_at,
+            metadata: row.metadata
+        };
+    }
+    /**
+     * Update existing link strength
+     */
+    async updateLinkStrength(linkId, strength, context) {
+        await this.db.query(`UPDATE code_prompt_links
+       SET strength = $2,
+           context = COALESCE($3, context)
+       WHERE id = $1`, [linkId, strength, context ?? null]);
+    }
+}
+//# sourceMappingURL=linkCodeToPrompt.js.map

package/dist/code-explanations/linkCodeToPrompt.js.map

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

package/dist/code-explanations/recallExplanation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * recall_code_explanation - Retrieve stored code explanations
+ *
+ * Supports multiple retrieval methods:
+ * - By code ID
+ * - By file path
+ * - By semantic search query
+ * - By explanation type
+ */
+import { MCPTool } from '../mcp/toolRegistry.js';
+import { DatabaseManager } from '../database.js';
+import { EmbeddingProvider } from '../types/index.js';
+import { RecallExplanationParams, RecallExplanationResult } from './types.js';
+/**
+ * RecallCodeExplanation - Retrieve stored explanations
+ *
+ * Features:
+ * - Multiple retrieval methods
+ * - Semantic search support
+ * - Quality filtering
+ * - Type filtering
+ */
+export declare class RecallCodeExplanation implements MCPTool<RecallExplanationParams, RecallExplanationResult> {
+    private db;
+    private embeddingProvider;
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            codeId: {
+                type: string;
+                format: string;
+                description: string;
+            };
+            filePath: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            explanationType: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            minQuality: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+            limit: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+                description: string;
+            };
+        };
+    };
+    constructor(db: DatabaseManager, embeddingProvider: EmbeddingProvider);
+    execute(params: RecallExplanationParams): Promise<RecallExplanationResult>;
+    /**
+     * Semantic search for explanations
+     */
+    private semanticSearch;
+    /**
+     * Text-based search fallback
+     */
+    private textSearch;
+    /**
+     * Direct lookup by codeId or filePath
+     */
+    private directLookup;
+    /**
+     * Convert database row to CodeExplanation
+     */
+    private rowToExplanation;
+    /**
+     * Update use counts for retrieved explanations
+     */
+    private updateUseCounts;
+}
+//# sourceMappingURL=recallExplanation.d.ts.map

package/dist/code-explanations/recallExplanation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recallExplanation.d.ts","sourceRoot":"","sources":["../../src/code-explanations/recallExplanation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,EAEL,uBAAuB,EACvB,uBAAuB,EAGxB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,OAAO,CAAC,uBAAuB,EAAE,uBAAuB,CAAC;IAiDnG,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,iBAAiB;IAjD3B,IAAI,SAA6B;IACjC,WAAW,SAKwC;IAEnD,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAqCT;gBAGQ,EAAE,EAAE,eAAe,EACnB,iBAAiB,EAAE,iBAAiB;IAGxC,OAAO,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAiDhF;;OAEG;YACW,cAAc;IAoD5B;;OAEG;YACW,UAAU;IA4CxB;;OAEG;YACW,YAAY;IAqD1B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAyCxB;;OAEG;YACW,eAAe;CAU9B"}

package/dist/code-explanations/recallExplanation.js

@@ -0,0 +1,218 @@
+/**
+ * recall_code_explanation - Retrieve stored code explanations
+ *
+ * Supports multiple retrieval methods:
+ * - By code ID
+ * - By file path
+ * - By semantic search query
+ * - By explanation type
+ */
+import { logger } from '../utils/logger.js';
+import { RecallExplanationInput } from './types.js';
+/**
+ * RecallCodeExplanation - Retrieve stored explanations
+ *
+ * Features:
+ * - Multiple retrieval methods
+ * - Semantic search support
+ * - Quality filtering
+ * - Type filtering
+ */
+export class RecallCodeExplanation {
+    db;
+    embeddingProvider;
+    name = 'recall_code_explanation';
+    description = `Retrieve stored code explanations. Search by:
+- codeId: Get explanations for a specific code file
+- filePath: Get explanations by file path pattern
+- query: Semantic search for related explanations
+- explanationType: Filter by type (general, architectural, etc.)
+- minQuality: Filter by minimum quality score (0-1)`;
+    inputSchema = {
+        type: 'object',
+        properties: {
+            codeId: {
+                type: 'string',
+                format: 'uuid',
+                description: 'UUID of the code file'
+            },
+            filePath: {
+                type: 'string',
+                description: 'File path pattern to search (supports % wildcard)'
+            },
+            query: {
+                type: 'string',
+                description: 'Semantic search query'
+            },
+            explanationType: {
+                type: 'string',
+                enum: ['general', 'architectural', 'algorithmic', 'usage', 'gotchas',
+                    'performance', 'security', 'debugging', 'history', 'todo'],
+                description: 'Filter by explanation type'
+            },
+            minQuality: {
+                type: 'number',
+                minimum: 0,
+                maximum: 1,
+                default: 0,
+                description: 'Minimum quality score (0-1)'
+            },
+            limit: {
+                type: 'number',
+                minimum: 1,
+                maximum: 100,
+                default: 10,
+                description: 'Maximum results to return'
+            }
+        }
+    };
+    constructor(db, embeddingProvider) {
+        this.db = db;
+        this.embeddingProvider = embeddingProvider;
+    }
+    async execute(params) {
+        const validatedParams = RecallExplanationInput.parse(params);
+        logger.debug({ params: validatedParams }, 'Recalling code explanations');
+        try {
+            let explanations;
+            if (validatedParams.query) {
+                // Semantic search mode
+                explanations = await this.semanticSearch(validatedParams.query, validatedParams.explanationType, validatedParams.minQuality, validatedParams.limit);
+            }
+            else {
+                // Direct lookup mode
+                explanations = await this.directLookup(validatedParams);
+            }
+            // Update use counts for retrieved explanations
+            if (explanations.length > 0) {
+                await this.updateUseCounts(explanations.map(e => e.id));
+            }
+            logger.info({
+                resultCount: explanations.length,
+                method: validatedParams.query ? 'semantic' : 'direct'
+            }, 'Recalled code explanations');
+            return {
+                success: true,
+                explanations,
+                total: explanations.length,
+                message: `Found ${explanations.length} explanation(s)`
+            };
+        }
+        catch (error) {
+            logger.error({ error, params: validatedParams }, 'Failed to recall explanations');
+            return {
+                success: false,
+                explanations: [],
+                total: 0,
+                message: error instanceof Error ? error.message : 'Failed to recall explanations'
+            };
+        }
+    }
+    /**
+     * Semantic search for explanations
+     */
+    async semanticSearch(query, explanationType, minQuality = 0, limit = 10) {
+        // Generate embedding for query
+        const queryEmbedding = await this.embeddingProvider.generateEmbedding(query);
+        if (!queryEmbedding || queryEmbedding.length === 0) {
+            logger.warn('Failed to generate query embedding, falling back to text search');
+            return this.textSearch(query, explanationType, minQuality, limit);
+        }
+        const embeddingStr = `[${queryEmbedding.join(',')}]`;
+        // Vector similarity search
+        const result = await this.db.query(`SELECT *,
+        1 - (embedding <=> $1::vector) as similarity
+       FROM code_explanations
+       WHERE embedding IS NOT NULL
+       AND quality_score >= $2
+       ${explanationType ? 'AND explanation_type = $5' : ''}
+       ORDER BY embedding <=> $1::vector
+       LIMIT $3`, explanationType
+            ? [embeddingStr, minQuality, limit, undefined, explanationType]
+            : [embeddingStr, minQuality, limit]);
+        return result.rows.map((row) => this.rowToExplanation(row));
+    }
+    /**
+     * Text-based search fallback
+     */
+    async textSearch(query, explanationType, minQuality = 0, limit = 10) {
+        const result = await this.db.query(`SELECT *,
+        ts_rank(to_tsvector('english', explanation_text), plainto_tsquery('english', $1)) as rank
+       FROM code_explanations
+       WHERE to_tsvector('english', explanation_text) @@ plainto_tsquery('english', $1)
+       AND quality_score >= $2
+       ${explanationType ? 'AND explanation_type = $4' : ''}
+       ORDER BY rank DESC
+       LIMIT $3`, explanationType
+            ? [query, minQuality, limit, explanationType]
+            : [query, minQuality, limit]);
+        return result.rows.map((row) => ({
+            ...this.rowToExplanation(row),
+            similarity: row.rank
+        }));
+    }
+    /**
+     * Direct lookup by codeId or filePath
+     */
+    async directLookup(params) {
+        let query = `SELECT * FROM code_explanations WHERE 1=1`;
+        const values = [];
+        let paramIndex = 1;
+        if (params.codeId) {
+            query += ` AND code_id = $${paramIndex++}`;
+            values.push(params.codeId);
+        }
+        if (params.filePath) {
+            query += ` AND file_path LIKE $${paramIndex++}`;
+            values.push(`%${params.filePath}%`);
+        }
+        if (params.explanationType) {
+            query += ` AND explanation_type = $${paramIndex++}`;
+            values.push(params.explanationType);
+        }
+        if (params.minQuality !== undefined) {
+            query += ` AND quality_score >= $${paramIndex++}`;
+            values.push(params.minQuality);
+        }
+        query += ` ORDER BY quality_score DESC, use_count DESC`;
+        query += ` LIMIT $${paramIndex++}`;
+        values.push(params.limit);
+        const result = await this.db.query(query, values);
+        return result.rows.map((row) => this.rowToExplanation(row));
+    }
+    /**
+     * Convert database row to CodeExplanation
+     */
+    rowToExplanation(row) {
+        return {
+            id: row.id,
+            codeId: row.code_id ?? undefined,
+            filePath: row.file_path,
+            lineStart: row.line_start ?? undefined,
+            lineEnd: row.line_end ?? undefined,
+            codeSnippet: row.code_snippet ?? undefined,
+            explanationText: row.explanation_text,
+            explanationType: row.explanation_type,
+            qualityScore: row.quality_score,
+            useCount: row.use_count,
+            feedbackPositive: row.feedback_positive,
+            feedbackNegative: row.feedback_negative,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            createdBy: row.created_by,
+            metadata: row.metadata,
+            similarity: row.similarity ?? row.rank
+        };
+    }
+    /**
+     * Update use counts for retrieved explanations
+     */
+    async updateUseCounts(explanationIds) {
+        if (explanationIds.length === 0)
+            return;
+        await this.db.query(`UPDATE code_explanations
+       SET use_count = use_count + 1
+       WHERE id = ANY($1)`, [explanationIds]);
+    }
+}
+//# sourceMappingURL=recallExplanation.js.map

package/dist/code-explanations/recallExplanation.js.map

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

package/dist/code-explanations/schema.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Code Explanation System - Database Schema
+ *
+ * Tables:
+ * - code_explanations: Store explanations for code locations
+ * - code_prompt_links: Link code to conversation prompts/memories
+ * - code_access_patterns: Track access patterns for learning
+ *
+ * EMBEDDING DIMENSION NOTE:
+ * DEPRECATED: SPECMEM_EMBEDDING_DIMENSIONS is no longer used.
+ * Embedding dimensions are AUTO-DETECTED from the database pgvector column.
+ * The system auto-migrates when dimension mismatch is detected at startup.
+ */
+import { DatabaseManager } from '../database.js';
+/**
+ * Initialize the code explanation schema
+ * This creates all necessary tables for the active recall system
+ */
+export declare function initializeCodeExplanationSchema(db: DatabaseManager): Promise<void>;
+/**
+ * Check if code explanation schema exists
+ */
+export declare function schemaExists(db: DatabaseManager): Promise<boolean>;
+/**
+ * Get schema statistics
+ */
+export declare function getSchemaStats(db: DatabaseManager): Promise<{
+    explanations: number;
+    links: number;
+    patterns: number;
+}>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/code-explanations/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/code-explanations/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD;;;GAGG;AACH,wBAAsB,+BAA+B,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAkMxF;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAYxE;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAYD"}