@fermindi/pwn-cli 0.1.1 → 0.3.0

package/src/knowledge/references.js

@@ -1,342 +1,342 @@
-import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
-import { join, relative } from 'path';
-import {
-  getKnowledgeRegistry,
-  saveKnowledgeRegistry,
-  updateKnowledgeItem
-} from './lifecycle.js';
-
-/**
- * Scan a file for knowledge references (DEC-XXX, DE-XXX)
- * @param {string} filePath - Path to file
- * @returns {string[]} Array of referenced IDs
- */
-export function scanFileForReferences(filePath) {
-  if (!existsSync(filePath)) {
-    return [];
-  }
-
-  try {
-    const content = readFileSync(filePath, 'utf8');
-    const references = new Set();
-
-    // Match DEC-XXX and DE-XXX patterns
-    const decisionRegex = /DEC-\d+/g;
-    const deadendRegex = /DE-\d+/g;
-
-    let match;
-    while ((match = decisionRegex.exec(content)) !== null) {
-      references.add(match[0]);
-    }
-    while ((match = deadendRegex.exec(content)) !== null) {
-      references.add(match[0]);
-    }
-
-    return Array.from(references);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Recursively scan directory for knowledge references
- * @param {string} dir - Directory to scan
- * @param {Object} options - Options
- * @param {string[]} options.exclude - Patterns to exclude
- * @returns {Map<string, string[]>} Map of file path to referenced IDs
- */
-export function scanDirectoryForReferences(dir, options = {}) {
-  const exclude = options.exclude || [
-    'node_modules', '.git', '.ai', 'dist', 'build', 'coverage',
-    '.next', '.nuxt', '.output', 'vendor', '__pycache__'
-  ];
-
-  const results = new Map();
-
-  function walk(currentDir) {
-    try {
-      const entries = readdirSync(currentDir);
-
-      for (const entry of entries) {
-        const fullPath = join(currentDir, entry);
-
-        // Skip excluded directories
-        if (exclude.some(pattern => entry === pattern || fullPath.includes(pattern))) {
-          continue;
-        }
-
-        try {
-          const stat = statSync(fullPath);
-
-          if (stat.isDirectory()) {
-            walk(fullPath);
-          } else if (stat.isFile()) {
-            // Skip binary and non-text files
-            if (isScannable(entry)) {
-              const refs = scanFileForReferences(fullPath);
-              if (refs.length > 0) {
-                results.set(fullPath, refs);
-              }
-            }
-          }
-        } catch {
-          // Skip files we can't access
-        }
-      }
-    } catch {
-      // Skip directories we can't access
-    }
-  }
-
-  walk(dir);
-  return results;
-}
-
-/**
- * Check if a file should be scanned for references
- * @param {string} filename - File name
- * @returns {boolean}
- */
-function isScannable(filename) {
-  const scannableExtensions = [
-    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
-    '.py', '.rb', '.go', '.rs', '.java', '.kt', '.scala',
-    '.c', '.cpp', '.h', '.hpp', '.cs',
-    '.php', '.swift', '.m',
-    '.md', '.mdx', '.txt', '.rst',
-    '.yml', '.yaml', '.json', '.toml',
-    '.html', '.css', '.scss', '.less',
-    '.sql', '.graphql', '.prisma',
-    '.sh', '.bash', '.zsh', '.fish',
-    '.vue', '.svelte', '.astro'
-  ];
-
-  const extension = filename.substring(filename.lastIndexOf('.'));
-  return scannableExtensions.includes(extension);
-}
-
-/**
- * Build a reference map: which files reference which knowledge items
- * @param {string} cwd - Working directory
- * @returns {Object} Reference map
- */
-export function buildReferenceMap(cwd = process.cwd()) {
-  const fileRefs = scanDirectoryForReferences(cwd);
-
-  // Build inverse map: knowledge ID -> files
-  const knowledgeToFiles = new Map();
-
-  for (const [file, refs] of fileRefs) {
-    const relativePath = relative(cwd, file);
-    for (const ref of refs) {
-      if (!knowledgeToFiles.has(ref)) {
-        knowledgeToFiles.set(ref, []);
-      }
-      knowledgeToFiles.get(ref).push(relativePath);
-    }
-  }
-
-  return {
-    fileToKnowledge: Object.fromEntries(
-      Array.from(fileRefs.entries()).map(([file, refs]) => [
-        relative(cwd, file),
-        refs
-      ])
-    ),
-    knowledgeToFiles: Object.fromEntries(knowledgeToFiles)
-  };
-}
-
-/**
- * Update knowledge registry with current file references
- * @param {string} cwd - Working directory
- * @returns {Object} Update result
- */
-export function updateReferences(cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) {
-    return { error: 'No knowledge registry found. Run sync first.' };
-  }
-
-  const refMap = buildReferenceMap(cwd);
-  const result = { updated: [], orphaned: [], newRefs: [] };
-
-  // Update each knowledge item with its references
-  for (const [id, item] of Object.entries(registry.items)) {
-    const currentFiles = refMap.knowledgeToFiles[id] || [];
-    const previousFiles = item.relatedFiles || [];
-
-    // Find changes
-    const added = currentFiles.filter(f => !previousFiles.includes(f));
-    const removed = previousFiles.filter(f => !currentFiles.includes(f));
-
-    if (added.length > 0 || removed.length > 0) {
-      registry.items[id].relatedFiles = currentFiles;
-      result.updated.push({ id, added, removed });
-    }
-
-    // Check for orphaned items (no references)
-    if (currentFiles.length === 0 && item.status === 'active') {
-      result.orphaned.push(id);
-    }
-
-    // Track new references for metrics
-    if (added.length > 0) {
-      result.newRefs.push({ id, files: added });
-    }
-  }
-
-  saveKnowledgeRegistry(registry, cwd);
-  return result;
-}
-
-/**
- * Add a manual reference link
- * @param {string} knowledgeId - Knowledge item ID
- * @param {string} target - Target (file path, decision ID, task ID)
- * @param {string} targetType - Type: 'file', 'decision', 'task'
- * @param {string} cwd - Working directory
- * @returns {Object|null}
- */
-export function addReference(knowledgeId, target, targetType, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry || !registry.items[knowledgeId]) {
-    return null;
-  }
-
-  const item = registry.items[knowledgeId];
-
-  switch (targetType) {
-    case 'file':
-      item.relatedFiles = item.relatedFiles || [];
-      if (!item.relatedFiles.includes(target)) {
-        item.relatedFiles.push(target);
-      }
-      break;
-    case 'decision':
-      item.relatedDecisions = item.relatedDecisions || [];
-      if (!item.relatedDecisions.includes(target)) {
-        item.relatedDecisions.push(target);
-      }
-      break;
-    case 'task':
-      item.relatedTasks = item.relatedTasks || [];
-      if (!item.relatedTasks.includes(target)) {
-        item.relatedTasks.push(target);
-      }
-      break;
-    default:
-      return null;
-  }
-
-  saveKnowledgeRegistry(registry, cwd);
-  return item;
-}
-
-/**
- * Remove a reference link
- * @param {string} knowledgeId - Knowledge item ID
- * @param {string} target - Target to remove
- * @param {string} targetType - Type: 'file', 'decision', 'task'
- * @param {string} cwd - Working directory
- * @returns {Object|null}
- */
-export function removeReference(knowledgeId, target, targetType, cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry || !registry.items[knowledgeId]) {
-    return null;
-  }
-
-  const item = registry.items[knowledgeId];
-
-  switch (targetType) {
-    case 'file':
-      item.relatedFiles = (item.relatedFiles || []).filter(f => f !== target);
-      break;
-    case 'decision':
-      item.relatedDecisions = (item.relatedDecisions || []).filter(d => d !== target);
-      break;
-    case 'task':
-      item.relatedTasks = (item.relatedTasks || []).filter(t => t !== target);
-      break;
-    default:
-      return null;
-  }
-
-  saveKnowledgeRegistry(registry, cwd);
-  return item;
-}
-
-/**
- * Find broken references (references to non-existent files)
- * @param {string} cwd - Working directory
- * @returns {Object[]} Broken references
- */
-export function findBrokenReferences(cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) {
-    return [];
-  }
-
-  const broken = [];
-
-  for (const [id, item] of Object.entries(registry.items)) {
-    const brokenFiles = (item.relatedFiles || []).filter(file => {
-      const fullPath = join(cwd, file);
-      return !existsSync(fullPath);
-    });
-
-    const brokenDecisions = (item.relatedDecisions || []).filter(decId => {
-      return !registry.items[decId];
-    });
-
-    if (brokenFiles.length > 0 || brokenDecisions.length > 0) {
-      broken.push({
-        id,
-        brokenFiles,
-        brokenDecisions
-      });
-    }
-  }
-
-  return broken;
-}
-
-/**
- * Get reference statistics
- * @param {string} cwd - Working directory
- * @returns {Object}
- */
-export function getReferenceStats(cwd = process.cwd()) {
-  const registry = getKnowledgeRegistry(cwd);
-  if (!registry) {
-    return { totalRefs: 0, avgRefsPerItem: 0, orphaned: 0, mostReferenced: [] };
-  }
-
-  const items = Object.values(registry.items);
-  let totalRefs = 0;
-  let orphaned = 0;
-  const refCounts = [];
-
-  for (const item of items) {
-    const refCount = (item.relatedFiles || []).length +
-                     (item.relatedDecisions || []).length +
-                     (item.relatedTasks || []).length;
-    totalRefs += refCount;
-    refCounts.push({ id: item.id, title: item.title, count: refCount });
-
-    if (refCount === 0 && item.status === 'active') {
-      orphaned++;
-    }
-  }
-
-  // Sort by ref count descending
-  refCounts.sort((a, b) => b.count - a.count);
-
-  return {
-    totalRefs,
-    avgRefsPerItem: items.length > 0 ? (totalRefs / items.length).toFixed(1) : 0,
-    orphaned,
-    mostReferenced: refCounts.slice(0, 5)
-  };
-}
+import { readFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join, relative } from 'path';
+import {
+  getKnowledgeRegistry,
+  saveKnowledgeRegistry,
+  updateKnowledgeItem
+} from './lifecycle.js';
+
+/**
+ * Scan a file for knowledge references (DEC-XXX, DE-XXX)
+ * @param {string} filePath - Path to file
+ * @returns {string[]} Array of referenced IDs
+ */
+export function scanFileForReferences(filePath) {
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const references = new Set();
+
+    // Match DEC-XXX and DE-XXX patterns
+    const decisionRegex = /DEC-\d+/g;
+    const deadendRegex = /DE-\d+/g;
+
+    let match;
+    while ((match = decisionRegex.exec(content)) !== null) {
+      references.add(match[0]);
+    }
+    while ((match = deadendRegex.exec(content)) !== null) {
+      references.add(match[0]);
+    }
+
+    return Array.from(references);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Recursively scan directory for knowledge references
+ * @param {string} dir - Directory to scan
+ * @param {Object} options - Options
+ * @param {string[]} options.exclude - Patterns to exclude
+ * @returns {Map<string, string[]>} Map of file path to referenced IDs
+ */
+export function scanDirectoryForReferences(dir, options = {}) {
+  const exclude = options.exclude || [
+    'node_modules', '.git', '.ai', 'dist', 'build', 'coverage',
+    '.next', '.nuxt', '.output', 'vendor', '__pycache__'
+  ];
+
+  const results = new Map();
+
+  function walk(currentDir) {
+    try {
+      const entries = readdirSync(currentDir);
+
+      for (const entry of entries) {
+        const fullPath = join(currentDir, entry);
+
+        // Skip excluded directories
+        if (exclude.some(pattern => entry === pattern || fullPath.includes(pattern))) {
+          continue;
+        }
+
+        try {
+          const stat = statSync(fullPath);
+
+          if (stat.isDirectory()) {
+            walk(fullPath);
+          } else if (stat.isFile()) {
+            // Skip binary and non-text files
+            if (isScannable(entry)) {
+              const refs = scanFileForReferences(fullPath);
+              if (refs.length > 0) {
+                results.set(fullPath, refs);
+              }
+            }
+          }
+        } catch {
+          // Skip files we can't access
+        }
+      }
+    } catch {
+      // Skip directories we can't access
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/**
+ * Check if a file should be scanned for references
+ * @param {string} filename - File name
+ * @returns {boolean}
+ */
+function isScannable(filename) {
+  const scannableExtensions = [
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+    '.py', '.rb', '.go', '.rs', '.java', '.kt', '.scala',
+    '.c', '.cpp', '.h', '.hpp', '.cs',
+    '.php', '.swift', '.m',
+    '.md', '.mdx', '.txt', '.rst',
+    '.yml', '.yaml', '.json', '.toml',
+    '.html', '.css', '.scss', '.less',
+    '.sql', '.graphql', '.prisma',
+    '.sh', '.bash', '.zsh', '.fish',
+    '.vue', '.svelte', '.astro'
+  ];
+
+  const extension = filename.substring(filename.lastIndexOf('.'));
+  return scannableExtensions.includes(extension);
+}
+
+/**
+ * Build a reference map: which files reference which knowledge items
+ * @param {string} cwd - Working directory
+ * @returns {Object} Reference map
+ */
+export function buildReferenceMap(cwd = process.cwd()) {
+  const fileRefs = scanDirectoryForReferences(cwd);
+
+  // Build inverse map: knowledge ID -> files
+  const knowledgeToFiles = new Map();
+
+  for (const [file, refs] of fileRefs) {
+    const relativePath = relative(cwd, file);
+    for (const ref of refs) {
+      if (!knowledgeToFiles.has(ref)) {
+        knowledgeToFiles.set(ref, []);
+      }
+      knowledgeToFiles.get(ref).push(relativePath);
+    }
+  }
+
+  return {
+    fileToKnowledge: Object.fromEntries(
+      Array.from(fileRefs.entries()).map(([file, refs]) => [
+        relative(cwd, file),
+        refs
+      ])
+    ),
+    knowledgeToFiles: Object.fromEntries(knowledgeToFiles)
+  };
+}
+
+/**
+ * Update knowledge registry with current file references
+ * @param {string} cwd - Working directory
+ * @returns {Object} Update result
+ */
+export function updateReferences(cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) {
+    return { error: 'No knowledge registry found. Run sync first.' };
+  }
+
+  const refMap = buildReferenceMap(cwd);
+  const result = { updated: [], orphaned: [], newRefs: [] };
+
+  // Update each knowledge item with its references
+  for (const [id, item] of Object.entries(registry.items)) {
+    const currentFiles = refMap.knowledgeToFiles[id] || [];
+    const previousFiles = item.relatedFiles || [];
+
+    // Find changes
+    const added = currentFiles.filter(f => !previousFiles.includes(f));
+    const removed = previousFiles.filter(f => !currentFiles.includes(f));
+
+    if (added.length > 0 || removed.length > 0) {
+      registry.items[id].relatedFiles = currentFiles;
+      result.updated.push({ id, added, removed });
+    }
+
+    // Check for orphaned items (no references)
+    if (currentFiles.length === 0 && item.status === 'active') {
+      result.orphaned.push(id);
+    }
+
+    // Track new references for metrics
+    if (added.length > 0) {
+      result.newRefs.push({ id, files: added });
+    }
+  }
+
+  saveKnowledgeRegistry(registry, cwd);
+  return result;
+}
+
+/**
+ * Add a manual reference link
+ * @param {string} knowledgeId - Knowledge item ID
+ * @param {string} target - Target (file path, decision ID, task ID)
+ * @param {string} targetType - Type: 'file', 'decision', 'task'
+ * @param {string} cwd - Working directory
+ * @returns {Object|null}
+ */
+export function addReference(knowledgeId, target, targetType, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry || !registry.items[knowledgeId]) {
+    return null;
+  }
+
+  const item = registry.items[knowledgeId];
+
+  switch (targetType) {
+    case 'file':
+      item.relatedFiles = item.relatedFiles || [];
+      if (!item.relatedFiles.includes(target)) {
+        item.relatedFiles.push(target);
+      }
+      break;
+    case 'decision':
+      item.relatedDecisions = item.relatedDecisions || [];
+      if (!item.relatedDecisions.includes(target)) {
+        item.relatedDecisions.push(target);
+      }
+      break;
+    case 'task':
+      item.relatedTasks = item.relatedTasks || [];
+      if (!item.relatedTasks.includes(target)) {
+        item.relatedTasks.push(target);
+      }
+      break;
+    default:
+      return null;
+  }
+
+  saveKnowledgeRegistry(registry, cwd);
+  return item;
+}
+
+/**
+ * Remove a reference link
+ * @param {string} knowledgeId - Knowledge item ID
+ * @param {string} target - Target to remove
+ * @param {string} targetType - Type: 'file', 'decision', 'task'
+ * @param {string} cwd - Working directory
+ * @returns {Object|null}
+ */
+export function removeReference(knowledgeId, target, targetType, cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry || !registry.items[knowledgeId]) {
+    return null;
+  }
+
+  const item = registry.items[knowledgeId];
+
+  switch (targetType) {
+    case 'file':
+      item.relatedFiles = (item.relatedFiles || []).filter(f => f !== target);
+      break;
+    case 'decision':
+      item.relatedDecisions = (item.relatedDecisions || []).filter(d => d !== target);
+      break;
+    case 'task':
+      item.relatedTasks = (item.relatedTasks || []).filter(t => t !== target);
+      break;
+    default:
+      return null;
+  }
+
+  saveKnowledgeRegistry(registry, cwd);
+  return item;
+}
+
+/**
+ * Find broken references (references to non-existent files)
+ * @param {string} cwd - Working directory
+ * @returns {Object[]} Broken references
+ */
+export function findBrokenReferences(cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) {
+    return [];
+  }
+
+  const broken = [];
+
+  for (const [id, item] of Object.entries(registry.items)) {
+    const brokenFiles = (item.relatedFiles || []).filter(file => {
+      const fullPath = join(cwd, file);
+      return !existsSync(fullPath);
+    });
+
+    const brokenDecisions = (item.relatedDecisions || []).filter(decId => {
+      return !registry.items[decId];
+    });
+
+    if (brokenFiles.length > 0 || brokenDecisions.length > 0) {
+      broken.push({
+        id,
+        brokenFiles,
+        brokenDecisions
+      });
+    }
+  }
+
+  return broken;
+}
+
+/**
+ * Get reference statistics
+ * @param {string} cwd - Working directory
+ * @returns {Object}
+ */
+export function getReferenceStats(cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) {
+    return { totalRefs: 0, avgRefsPerItem: 0, orphaned: 0, mostReferenced: [] };
+  }
+
+  const items = Object.values(registry.items);
+  let totalRefs = 0;
+  let orphaned = 0;
+  const refCounts = [];
+
+  for (const item of items) {
+    const refCount = (item.relatedFiles || []).length +
+                     (item.relatedDecisions || []).length +
+                     (item.relatedTasks || []).length;
+    totalRefs += refCount;
+    refCounts.push({ id: item.id, title: item.title, count: refCount });
+
+    if (refCount === 0 && item.status === 'active') {
+      orphaned++;
+    }
+  }
+
+  // Sort by ref count descending
+  refCounts.sort((a, b) => b.count - a.count);
+
+  return {
+    totalRefs,
+    avgRefsPerItem: items.length > 0 ? (totalRefs / items.length).toFixed(1) : 0,
+    orphaned,
+    mostReferenced: refCounts.slice(0, 5)
+  };
+}