clearctx 3.0.0

package/src/pattern-registry.js

@@ -0,0 +1,221 @@
+/**
+ * Pattern Registry — Layer 0: Session Continuity Engine
+ *
+ * Stores and retrieves coding patterns learned during sessions.
+ * Patterns are project-scoped and persist across sessions.
+ *
+ * Example pattern:
+ * {
+ *   id: 'p_1707856123456_a1b2c3d4',
+ *   rule: 'Always normalize phone numbers to 10 digits',
+ *   context: 'auth module',
+ *   example: 'phone.replace(/\D/g, "").slice(-10)',
+ *   tags: ['validation', 'auth'],
+ *   createdAt: '2024-02-13T12:34:56.789Z'
+ * }
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// These are helper modules already in the codebase
+const { atomicWriteJson, readJsonSafe } = require('./atomic-io');
+const { acquireLock, releaseLock } = require('./file-lock');
+
+/**
+ * PatternRegistry class for managing coding patterns.
+ *
+ * This class stores patterns (rules, examples, context) that help maintain
+ * consistency across sessions. Each pattern has a unique ID and metadata.
+ */
+class PatternRegistry {
+  /**
+   * Creates a new PatternRegistry instance.
+   *
+   * @param {string} projectPath - Absolute path to the project directory
+   *
+   * The registry creates a project-specific storage directory using a hash
+   * of the project path, so different projects have separate pattern stores.
+   */
+  constructor(projectPath) {
+    // Create a short hash of the project path to identify this project
+    const projectHash = crypto
+      .createHash('sha256')
+      .update(projectPath)
+      .digest('hex')
+      .slice(0, 16);
+
+    // Storage directory for this project's patterns
+    this.storageDir = path.join(
+      os.homedir(),
+      '.clearctx',
+      'continuity',
+      projectHash
+    );
+
+    // File that holds all patterns as JSON
+    this.patternsPath = path.join(this.storageDir, 'patterns.json');
+
+    // Directory for lock files (prevents race conditions)
+    this.locksDir = path.join(this.storageDir, 'locks');
+
+    // Create directories if they don't exist yet
+    fs.mkdirSync(this.storageDir, { recursive: true });
+    fs.mkdirSync(this.locksDir, { recursive: true });
+  }
+
+  /**
+   * Adds a new pattern to the registry.
+   *
+   * @param {Object} options - Pattern details
+   * @param {string} options.rule - The pattern rule (required)
+   * @param {string} [options.context] - Where this pattern applies
+   * @param {string} [options.example] - Code example or explanation
+   * @param {string[]} [options.tags] - Tags for categorization
+   * @returns {Object} The created pattern entry
+   *
+   * Example:
+   *   registry.add({
+   *     rule: 'Always validate email format',
+   *     context: 'user registration',
+   *     example: '/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)',
+   *     tags: ['validation', 'user']
+   *   });
+   */
+  add({ rule, context, example, tags }) {
+    // Generate a unique ID for this pattern
+    // Format: 'p_' + timestamp + '_' + random hex
+    const id = 'p_' + Date.now() + '_' + crypto.randomBytes(4).toString('hex');
+
+    try {
+      // Lock the patterns file to prevent conflicts from other sessions
+      acquireLock(this.locksDir, 'patterns');
+
+      // Read existing patterns (returns {} if file doesn't exist)
+      const patterns = readJsonSafe(this.patternsPath, {});
+
+      // Build the new pattern entry
+      const entry = {
+        id,
+        rule,
+        context: context || '',
+        example: example || '',
+        tags: tags || [],
+        createdAt: new Date().toISOString()
+      };
+
+      // Add the pattern to the collection
+      patterns[id] = entry;
+
+      // Write back to disk atomically (safe even if interrupted)
+      atomicWriteJson(this.patternsPath, patterns);
+
+      return entry;
+    } finally {
+      // Always release the lock, even if an error occurred
+      releaseLock(this.locksDir, 'patterns');
+    }
+  }
+
+  /**
+   * Lists all patterns, optionally filtered by tag or context.
+   *
+   * @param {Object} [options] - Filter options
+   * @param {string} [options.tag] - Filter by tag (exact match)
+   * @param {string} [options.context] - Filter by context (substring match, case-insensitive)
+   * @returns {Array} Array of pattern entries, sorted by creation time (newest first)
+   *
+   * Example:
+   *   registry.list({ tag: 'validation' })
+   *   registry.list({ context: 'auth' })
+   *   registry.list() // all patterns
+   */
+  list({ tag, context } = {}) {
+    // Read all patterns from disk
+    const patterns = readJsonSafe(this.patternsPath, {});
+
+    // Convert from object to array
+    let entries = Object.values(patterns);
+
+    // Apply tag filter if provided
+    if (tag) {
+      entries = entries.filter(entry => entry.tags.includes(tag));
+    }
+
+    // Apply context filter if provided (case-insensitive substring match)
+    if (context) {
+      const contextLower = context.toLowerCase();
+      entries = entries.filter(entry =>
+        entry.context.toLowerCase().includes(contextLower)
+      );
+    }
+
+    // Sort by creation time, newest first
+    entries.sort((a, b) => {
+      return new Date(b.createdAt) - new Date(a.createdAt);
+    });
+
+    return entries;
+  }
+
+  /**
+   * Removes a pattern from the registry.
+   *
+   * @param {string} patternId - The ID of the pattern to remove
+   * @returns {Object} Confirmation object with removed ID
+   * @throws {Error} If pattern ID doesn't exist
+   *
+   * Example:
+   *   registry.remove('p_1707856123456_a1b2c3d4')
+   */
+  remove(patternId) {
+    try {
+      // Lock the patterns file
+      acquireLock(this.locksDir, 'patterns');
+
+      // Read current patterns
+      const patterns = readJsonSafe(this.patternsPath, {});
+
+      // Check if the pattern exists
+      if (!patterns[patternId]) {
+        throw new Error(`Pattern not found: ${patternId}`);
+      }
+
+      // Delete the pattern
+      delete patterns[patternId];
+
+      // Write back to disk
+      atomicWriteJson(this.patternsPath, patterns);
+
+      return { removed: patternId };
+    } finally {
+      // Always release the lock
+      releaseLock(this.locksDir, 'patterns');
+    }
+  }
+
+  /**
+   * Gets a specific pattern by ID.
+   *
+   * @param {string} patternId - The ID of the pattern to retrieve
+   * @returns {Object|null} The pattern entry, or null if not found
+   *
+   * Example:
+   *   const pattern = registry.get('p_1707856123456_a1b2c3d4');
+   *   if (pattern) {
+   *     console.log(pattern.rule);
+   *   }
+   */
+  get(patternId) {
+    // Read patterns (no lock needed for simple reads)
+    const patterns = readJsonSafe(this.patternsPath, {});
+
+    // Return the pattern or null if not found
+    return patterns[patternId] || null;
+  }
+}
+
+// Export the class so other modules can use it
+module.exports = PatternRegistry;