@fermindi/pwn-cli 0.1.0

package/src/knowledge/promote.js

@@ -0,0 +1,364 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import {
+  getKnowledgeRegistry,
+  saveKnowledgeRegistry,
+  getKnowledgeItem,
+  changeStatus,
+  getAllKnowledge
+} from './lifecycle.js';
+
+/**
+ * Promotion criteria configuration
+ */
+export const PROMOTION_CRITERIA = {
+  // Minimum times the decision was applied in code
+  minAppliedCount: 3,
+  // Minimum different contexts where it was applied
+  minAppliedContexts: 2,
+  // Minimum access count
+  minAccessCount: 5
+};
+
+/**
+ * Check if a decision is eligible for promotion to pattern
+ * @param {string} id - Decision ID
+ * @param {string} cwd - Working directory
+ * @returns {Object} Eligibility result
+ */
+export function checkPromotionEligibility(id, cwd = process.cwd()) {
+  const item = getKnowledgeItem(id, cwd);
+
+  if (!item) {
+    return { eligible: false, reason: 'Item not found' };
+  }
+
+  if (item.type !== 'decision') {
+    return { eligible: false, reason: 'Only decisions can be promoted to patterns' };
+  }
+
+  if (item.status === 'archived' || item.status === 'garbage') {
+    return { eligible: false, reason: `Item is ${item.status}` };
+  }
+
+  const criteria = {
+    appliedCount: {
+      current: item.appliedCount || 0,
+      required: PROMOTION_CRITERIA.minAppliedCount,
+      met: (item.appliedCount || 0) >= PROMOTION_CRITERIA.minAppliedCount
+    },
+    appliedContexts: {
+      current: (item.appliedContexts || []).length,
+      required: PROMOTION_CRITERIA.minAppliedContexts,
+      met: (item.appliedContexts || []).length >= PROMOTION_CRITERIA.minAppliedContexts
+    },
+    accessCount: {
+      current: item.accessCount || 0,
+      required: PROMOTION_CRITERIA.minAccessCount,
+      met: (item.accessCount || 0) >= PROMOTION_CRITERIA.minAccessCount
+    }
+  };
+
+  const allMet = criteria.appliedCount.met &&
+                 criteria.appliedContexts.met &&
+                 criteria.accessCount.met;
+
+  return {
+    eligible: allMet,
+    criteria,
+    item: {
+      id: item.id,
+      title: item.title,
+      status: item.status,
+      appliedContexts: item.appliedContexts || []
+    }
+  };
+}
+
+/**
+ * Get all decisions that are candidates for promotion
+ * @param {string} cwd - Working directory
+ * @returns {Object[]}
+ */
+export function getPromotionCandidates(cwd = process.cwd()) {
+  const decisions = getAllKnowledge({ type: 'decision' }, cwd);
+  const candidates = [];
+
+  for (const decision of decisions) {
+    if (decision.status === 'archived' || decision.status === 'garbage') {
+      continue;
+    }
+
+    const eligibility = checkPromotionEligibility(decision.id, cwd);
+
+    if (eligibility.eligible || decision.status === 'candidate_pattern') {
+      candidates.push({
+        id: decision.id,
+        title: decision.title,
+        status: decision.status,
+        eligibility: eligibility.criteria,
+        isEligible: eligibility.eligible
+      });
+    }
+  }
+
+  // Sort by applied count descending
+  return candidates.sort((a, b) =>
+    (b.eligibility?.appliedCount?.current || 0) -
+    (a.eligibility?.appliedCount?.current || 0)
+  );
+}
+
+/**
+ * Promote a decision to a pattern
+ * Creates a new pattern file and updates the decision status
+ * @param {string} id - Decision ID
+ * @param {Object} options - Options
+ * @param {string} options.category - Pattern category (frontend, backend, universal)
+ * @param {string} options.name - Pattern name (for filename)
+ * @param {string} cwd - Working directory
+ * @returns {Object}
+ */
+export function promoteToPattern(id, options = {}, cwd = process.cwd()) {
+  const eligibility = checkPromotionEligibility(id, cwd);
+
+  if (!eligibility.eligible && !options.force) {
+    return {
+      success: false,
+      error: 'Decision does not meet promotion criteria',
+      eligibility
+    };
+  }
+
+  const item = getKnowledgeItem(id, cwd);
+  if (!item) {
+    return { success: false, error: 'Item not found' };
+  }
+
+  // Determine category
+  const category = options.category || inferCategory(item);
+  const patternName = options.name || slugify(item.title);
+
+  // Create pattern file
+  const patternDir = join(cwd, '.ai', 'patterns', category);
+  if (!existsSync(patternDir)) {
+    mkdirSync(patternDir, { recursive: true });
+  }
+
+  const patternFile = join(patternDir, `${patternName}.md`);
+  const patternContent = generatePatternContent(item);
+
+  writeFileSync(patternFile, patternContent);
+
+  // Update decision status
+  const registry = getKnowledgeRegistry(cwd);
+  registry.items[id].status = 'promoted';
+  registry.items[id].promotedTo = `patterns/${category}/${patternName}.md`;
+  registry.items[id].promotedAt = new Date().toISOString();
+  saveKnowledgeRegistry(registry, cwd);
+
+  // Add to patterns index
+  updatePatternsIndex(item, category, patternName, cwd);
+
+  return {
+    success: true,
+    patternFile: `patterns/${category}/${patternName}.md`,
+    decision: id,
+    category
+  };
+}
+
+/**
+ * Infer the category for a pattern based on its contexts
+ * @param {Object} item - Knowledge item
+ * @returns {string}
+ */
+function inferCategory(item) {
+  const contexts = item.appliedContexts || [];
+  const contextStr = contexts.join(' ').toLowerCase();
+
+  // Check for frontend patterns
+  const frontendKeywords = ['component', 'react', 'vue', 'svelte', 'ui', 'css', 'style', 'hook'];
+  if (frontendKeywords.some(kw => contextStr.includes(kw))) {
+    return 'frontend';
+  }
+
+  // Check for backend patterns
+  const backendKeywords = ['api', 'server', 'database', 'auth', 'middleware', 'route', 'controller'];
+  if (backendKeywords.some(kw => contextStr.includes(kw))) {
+    return 'backend';
+  }
+
+  return 'universal';
+}
+
+/**
+ * Generate pattern content from a decision
+ * @param {Object} item - Knowledge item
+ * @returns {string}
+ */
+function generatePatternContent(item) {
+  const content = `# ${item.title}
+
+> Promoted from ${item.id} on ${new Date().toISOString().split('T')[0]}
+
+## Context
+
+This pattern was identified after being applied ${item.appliedCount || 0} times across ${(item.appliedContexts || []).length} different contexts.
+
+## Pattern
+
+<!-- Describe the pattern here -->
+
+## When to Use
+
+Applied contexts:
+${(item.appliedContexts || []).map(ctx => `- ${ctx}`).join('\n')}
+
+## Example
+
+\`\`\`
+// Add example code here
+\`\`\`
+
+## Related
+
+- Source: ${item.id}
+${(item.relatedDecisions || []).map(d => `- ${d}`).join('\n')}
+
+## Statistics
+
+- Applied: ${item.appliedCount || 0} times
+- Accessed: ${item.accessCount || 0} times
+- First created: ${item.createdAt || 'Unknown'}
+`;
+
+  return content;
+}
+
+/**
+ * Convert a string to a slug
+ * @param {string} str - Input string
+ * @returns {string}
+ */
+function slugify(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .substring(0, 50);
+}
+
+/**
+ * Update patterns/index.md with new pattern
+ * @param {Object} item - Knowledge item
+ * @param {string} category - Pattern category
+ * @param {string} patternName - Pattern filename (without .md)
+ * @param {string} cwd - Working directory
+ */
+function updatePatternsIndex(item, category, patternName, cwd = process.cwd()) {
+  const indexPath = join(cwd, '.ai', 'patterns', 'index.md');
+
+  if (!existsSync(indexPath)) {
+    return;
+  }
+
+  const entry = `\n## ${category}/${patternName}\n` +
+    `- **Promoted from:** ${item.id}\n` +
+    `- **Applied:** ${item.appliedCount || 0} times\n` +
+    `- **Description:** ${item.title}\n`;
+
+  appendFileSync(indexPath, entry);
+}
+
+/**
+ * Get promotion statistics
+ * @param {string} cwd - Working directory
+ * @returns {Object}
+ */
+export function getPromotionStats(cwd = process.cwd()) {
+  const registry = getKnowledgeRegistry(cwd);
+  if (!registry) {
+    return {
+      totalDecisions: 0,
+      promotedCount: 0,
+      candidateCount: 0,
+      eligibleCount: 0,
+      candidates: []
+    };
+  }
+
+  const items = Object.values(registry.items);
+  const decisions = items.filter(i => i.type === 'decision');
+
+  const promoted = decisions.filter(d => d.status === 'promoted');
+  const candidates = decisions.filter(d => d.status === 'candidate_pattern');
+
+  // Check eligibility for active decisions
+  let eligibleCount = 0;
+  for (const d of decisions) {
+    if (d.status === 'active') {
+      const elig = checkPromotionEligibility(d.id, cwd);
+      if (elig.eligible) eligibleCount++;
+    }
+  }
+
+  return {
+    totalDecisions: decisions.length,
+    promotedCount: promoted.length,
+    candidateCount: candidates.length,
+    eligibleCount,
+    promoted: promoted.map(p => ({
+      id: p.id,
+      title: p.title,
+      promotedTo: p.promotedTo,
+      promotedAt: p.promotedAt
+    })),
+    candidates: getPromotionCandidates(cwd).slice(0, 5)
+  };
+}
+
+/**
+ * Suggest next best candidate for promotion
+ * @param {string} cwd - Working directory
+ * @returns {Object|null}
+ */
+export function suggestPromotion(cwd = process.cwd()) {
+  const candidates = getPromotionCandidates(cwd);
+
+  // Find the first eligible candidate
+  const eligible = candidates.find(c => c.isEligible);
+  if (eligible) {
+    return {
+      type: 'ready',
+      ...eligible,
+      message: `${eligible.id} is ready for promotion to pattern`
+    };
+  }
+
+  // Find the closest to eligible
+  if (candidates.length > 0) {
+    const closest = candidates[0];
+    const criteria = closest.eligibility;
+
+    const missing = [];
+    if (!criteria.appliedCount.met) {
+      missing.push(`${criteria.appliedCount.required - criteria.appliedCount.current} more applications needed`);
+    }
+    if (!criteria.appliedContexts.met) {
+      missing.push(`${criteria.appliedContexts.required - criteria.appliedContexts.current} more contexts needed`);
+    }
+    if (!criteria.accessCount.met) {
+      missing.push(`${criteria.accessCount.required - criteria.accessCount.current} more accesses needed`);
+    }
+
+    return {
+      type: 'close',
+      ...closest,
+      missing,
+      message: `${closest.id} is close to promotion: ${missing.join(', ')}`
+    };
+  }
+
+  return null;
+}

package/src/knowledge/references.js

@@ -0,0 +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)
+  };
+}