k0ntext 3.0.0

package/templates/base/tools/lib/diagnose.js

@@ -0,0 +1,206 @@
+/**
+ * Claude Context Engineering - Diagnostics Module
+ *
+ * System health diagnostics and issue detection with optional auto-fix.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const { findClaudeDir, loadJsonFile } = require('./config-loader');
+const { logger } = require('./logger');
+const { validate } = require('./validate');
+
+/**
+ * Diagnostic procedures for common issues
+ */
+const DIAGNOSTIC_PROCEDURES = {
+  'corrupted-settings': {
+    name: 'Corrupted Settings',
+    detect: async (claudeDir) => {
+      const settingsPath = path.join(claudeDir, 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+
+      try {
+        JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        return false;
+      } catch {
+        return true;
+      }
+    },
+    fix: async (claudeDir) => {
+      const settingsPath = path.join(claudeDir, 'settings.json');
+      const backupPath = settingsPath + '.corrupted';
+
+      // Backup corrupted file
+      fs.renameSync(settingsPath, backupPath);
+
+      // Create default settings
+      const defaults = require('./config-loader').configLoader.getDefaults();
+      defaults.$schema = './schemas/settings.schema.json';
+      defaults.version = '1.1.0';
+
+      fs.writeFileSync(settingsPath, JSON.stringify(defaults, null, 2));
+
+      return `Settings restored from defaults. Backup saved to ${backupPath}`;
+    },
+  },
+
+  'incomplete-init': {
+    name: 'Incomplete Initialization',
+    detect: async (claudeDir) => {
+      const progressPath = path.join(claudeDir, 'INIT_PROGRESS.json');
+      if (!fs.existsSync(progressPath)) return false;
+
+      const progress = loadJsonFile(progressPath);
+      return progress.status !== 'COMPLETED';
+    },
+    fix: async (claudeDir) => {
+      console.log(chalk.yellow('  To resume initialization, run:'));
+      console.log(chalk.cyan('    npx claude-context init --resume'));
+      return 'Manual action required';
+    },
+  },
+
+  'missing-schemas': {
+    name: 'Missing Schema Directory',
+    detect: async (claudeDir) => {
+      return !fs.existsSync(path.join(claudeDir, 'schemas'));
+    },
+    fix: async (claudeDir) => {
+      const schemaDir = path.join(claudeDir, 'schemas');
+      fs.mkdirSync(schemaDir, { recursive: true });
+      return 'Created schemas directory';
+    },
+  },
+
+  'missing-logs-dir': {
+    name: 'Missing Logs Directory',
+    detect: async (claudeDir) => {
+      return !fs.existsSync(path.join(claudeDir, 'logs'));
+    },
+    fix: async (claudeDir) => {
+      fs.mkdirSync(path.join(claudeDir, 'logs'), { recursive: true });
+      return 'Created logs directory';
+    },
+  },
+
+  'orphaned-workflows': {
+    name: 'Orphaned Workflow Files',
+    detect: async (claudeDir) => {
+      const indexPath = path.join(claudeDir, 'context', 'WORKFLOW_INDEX.md');
+      const workflowDir = path.join(claudeDir, 'context', 'workflows');
+
+      if (!fs.existsSync(indexPath) || !fs.existsSync(workflowDir)) {
+        return false;
+      }
+
+      const indexContent = fs.readFileSync(indexPath, 'utf8');
+      const workflowFiles = fs.readdirSync(workflowDir).filter(f => f.endsWith('.md'));
+
+      for (const wf of workflowFiles) {
+        const baseName = wf.replace('.md', '');
+        if (!indexContent.includes(baseName)) {
+          return true;
+        }
+      }
+
+      return false;
+    },
+    fix: async (claudeDir) => {
+      return 'Orphaned workflows detected. Update WORKFLOW_INDEX.md to include all workflows.';
+    },
+  },
+};
+
+/**
+ * Run diagnostics
+ */
+async function diagnose(options = {}) {
+  const { fix = false, verbose = false } = options;
+  const op = logger.startOperation('diagnose');
+
+  const claudeDir = findClaudeDir();
+
+  console.log(chalk.cyan('\n🔬 Running Diagnostics...\n'));
+
+  const results = {
+    timestamp: new Date().toISOString(),
+    issues: [],
+    fixed: [],
+    suggestions: [],
+  };
+
+  // Run all diagnostic procedures
+  for (const [key, procedure] of Object.entries(DIAGNOSTIC_PROCEDURES)) {
+    if (verbose) {
+      console.log(chalk.gray(`  Checking: ${procedure.name}...`));
+    }
+
+    try {
+      const detected = await procedure.detect(claudeDir);
+
+      if (detected) {
+        console.log(chalk.yellow(`  ⚠️  Issue detected: ${procedure.name}`));
+
+        results.issues.push({
+          key,
+          name: procedure.name,
+          fixable: !!procedure.fix,
+        });
+
+        if (fix && procedure.fix) {
+          console.log(chalk.cyan(`     Attempting fix...`));
+          const fixResult = await procedure.fix(claudeDir);
+          console.log(chalk.green(`     ✓ ${fixResult}`));
+          results.fixed.push({ key, result: fixResult });
+        } else if (procedure.fix) {
+          console.log(chalk.gray(`     Run with --fix to attempt auto-repair`));
+        }
+      } else if (verbose) {
+        console.log(chalk.green(`  ✓ ${procedure.name}: OK`));
+      }
+    } catch (error) {
+      console.log(chalk.red(`  ✗ Error checking ${procedure.name}: ${error.message}`));
+      results.issues.push({
+        key,
+        name: procedure.name,
+        error: error.message,
+      });
+    }
+  }
+
+  // Run validation as part of diagnostics
+  console.log(chalk.white('\nRunning validation checks...'));
+  const validation = await validate({ all: true, claudeDir });
+
+  if (validation.summary.failed > 0) {
+    results.suggestions.push('Run validation to see detailed issues: npx claude-context validate');
+  }
+
+  // Summary
+  console.log(chalk.white('\n📋 Diagnostic Summary'));
+  console.log(chalk.gray('─'.repeat(50)));
+
+  if (results.issues.length === 0) {
+    console.log(chalk.green('  ✓ No issues detected'));
+  } else {
+    console.log(chalk.yellow(`  Issues found: ${results.issues.length}`));
+    if (results.fixed.length > 0) {
+      console.log(chalk.green(`  Issues fixed: ${results.fixed.length}`));
+    }
+  }
+
+  if (results.suggestions.length > 0) {
+    console.log(chalk.white('\n💡 Suggestions:'));
+    results.suggestions.forEach(s => console.log(chalk.gray(`  - ${s}`)));
+  }
+
+  op.success();
+  return results;
+}
+
+module.exports = {
+  diagnose,
+  DIAGNOSTIC_PROCEDURES,
+};

package/templates/base/tools/lib/drift-detector.js

@@ -0,0 +1,373 @@
+/**
+ * Drift Detector - Detects documentation drift from code
+ *
+ * Compares documentation references against current code state
+ * to identify outdated line numbers, renamed functions, etc.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { resolveAnchor, buildFileAnchors, loadAnchors } = require('./anchor-resolver');
+
+const SYNC_DIR = path.join(__dirname, '..', '..', 'sync');
+const HASHES_PATH = path.join(SYNC_DIR, 'hashes.json');
+const STALENESS_PATH = path.join(SYNC_DIR, 'staleness.json');
+
+/**
+ * Drift severity levels
+ */
+const DRIFT_LEVEL = {
+  NONE: 'none',
+  LOW: 'low',         // Line number shifted slightly
+  MEDIUM: 'medium',   // Function renamed or moved
+  HIGH: 'high',       // Logic changed significantly
+  CRITICAL: 'critical' // File deleted or major restructure
+};
+
+/**
+ * Calculate file hash
+ */
+function hashFile(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return crypto.createHash('md5').update(content).digest('hex');
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Load stored hashes
+ */
+function loadHashes() {
+  try {
+    if (fs.existsSync(HASHES_PATH)) {
+      const content = fs.readFileSync(HASHES_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error('Failed to load hashes:', error.message);
+  }
+  return { version: '1.0.0', files: {} };
+}
+
+/**
+ * Save hashes
+ */
+function saveHashes(data) {
+  try {
+    if (!fs.existsSync(SYNC_DIR)) {
+      fs.mkdirSync(SYNC_DIR, { recursive: true });
+    }
+    data.generatedAt = new Date().toISOString();
+    fs.writeFileSync(HASHES_PATH, JSON.stringify(data, null, 2));
+    return true;
+  } catch (error) {
+    console.error('Failed to save hashes:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Load staleness tracking
+ */
+function loadStaleness() {
+  try {
+    if (fs.existsSync(STALENESS_PATH)) {
+      const content = fs.readFileSync(STALENESS_PATH, 'utf-8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    console.error('Failed to load staleness:', error.message);
+  }
+  return { version: '1.0.0', workflows: {}, thresholds: { warningDays: 30, staleDays: 90 } };
+}
+
+/**
+ * Save staleness tracking
+ */
+function saveStaleness(data) {
+  try {
+    if (!fs.existsSync(SYNC_DIR)) {
+      fs.mkdirSync(SYNC_DIR, { recursive: true });
+    }
+    fs.writeFileSync(STALENESS_PATH, JSON.stringify(data, null, 2));
+    return true;
+  } catch (error) {
+    console.error('Failed to save staleness:', error.message);
+    return false;
+  }
+}
+
+/**
+ * Check if a file has changed since last recorded
+ */
+function checkFileChange(filePath, projectRoot = process.cwd()) {
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+  const stored = loadHashes();
+
+  if (!fs.existsSync(fullPath)) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.CRITICAL,
+      reason: 'File not found'
+    };
+  }
+
+  const currentHash = hashFile(fullPath);
+  const storedData = stored.files[filePath];
+
+  if (!storedData) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.LOW,
+      reason: 'File not previously tracked'
+    };
+  }
+
+  if (storedData.hash !== currentHash) {
+    return {
+      changed: true,
+      level: DRIFT_LEVEL.MEDIUM,
+      reason: 'File content changed',
+      previousHash: storedData.hash,
+      currentHash
+    };
+  }
+
+  return {
+    changed: false,
+    level: DRIFT_LEVEL.NONE
+  };
+}
+
+/**
+ * Extract line references from markdown content
+ */
+function extractLineReferences(content) {
+  const references = [];
+
+  // file:123 format
+  const linePattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+):(\d+)/g;
+  let match;
+  while ((match = linePattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      line: parseInt(match[2]),
+      type: 'line',
+      original: match[0]
+    });
+  }
+
+  // file::function() format
+  const anchorPattern = /([a-zA-Z0-9_\-./]+\.[a-zA-Z0-9]+)::(\w+)\(\)/g;
+  while ((match = anchorPattern.exec(content)) !== null) {
+    references.push({
+      file: match[1],
+      anchor: match[2],
+      type: 'anchor',
+      original: match[0]
+    });
+  }
+
+  return references;
+}
+
+/**
+ * Check drift for a workflow file
+ */
+function checkWorkflowDrift(workflowPath, projectRoot = process.cwd()) {
+  const fullPath = path.isAbsolute(workflowPath)
+    ? workflowPath
+    : path.join(projectRoot, '.claude', workflowPath);
+
+  if (!fs.existsSync(fullPath)) {
+    return {
+      workflow: workflowPath,
+      status: 'error',
+      error: 'Workflow file not found'
+    };
+  }
+
+  const content = fs.readFileSync(fullPath, 'utf-8');
+  const references = extractLineReferences(content);
+  const issues = [];
+
+  for (const ref of references) {
+    if (ref.type === 'line') {
+      // Check if file exists and line is valid
+      const filePath = path.join(projectRoot, ref.file);
+
+      if (!fs.existsSync(filePath)) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.CRITICAL,
+          issue: 'Referenced file not found'
+        });
+        continue;
+      }
+
+      const fileContent = fs.readFileSync(filePath, 'utf-8');
+      const lines = fileContent.split('\n');
+
+      if (ref.line > lines.length) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.HIGH,
+          issue: `Line ${ref.line} exceeds file length (${lines.length} lines)`
+        });
+      }
+
+      // Check if file has changed
+      const changeResult = checkFileChange(ref.file, projectRoot);
+      if (changeResult.changed && changeResult.level !== DRIFT_LEVEL.NONE) {
+        issues.push({
+          ...ref,
+          level: changeResult.level,
+          issue: changeResult.reason
+        });
+      }
+    } else if (ref.type === 'anchor') {
+      // Resolve semantic anchor
+      const result = resolveAnchor(`${ref.file}::${ref.anchor}()`, projectRoot);
+      if (!result.success) {
+        issues.push({
+          ...ref,
+          level: DRIFT_LEVEL.HIGH,
+          issue: result.error,
+          availableSymbols: result.availableSymbols
+        });
+      }
+    }
+  }
+
+  // Determine overall status
+  let status = 'healthy';
+  let maxLevel = DRIFT_LEVEL.NONE;
+
+  for (const issue of issues) {
+    if (issue.level === DRIFT_LEVEL.CRITICAL) {
+      status = 'critical';
+      maxLevel = DRIFT_LEVEL.CRITICAL;
+    } else if (issue.level === DRIFT_LEVEL.HIGH && maxLevel !== DRIFT_LEVEL.CRITICAL) {
+      status = 'stale';
+      maxLevel = DRIFT_LEVEL.HIGH;
+    } else if (issue.level === DRIFT_LEVEL.MEDIUM && maxLevel === DRIFT_LEVEL.NONE) {
+      status = 'needs_update';
+      maxLevel = DRIFT_LEVEL.MEDIUM;
+    }
+  }
+
+  return {
+    workflow: workflowPath,
+    status,
+    level: maxLevel,
+    totalReferences: references.length,
+    issues,
+    checkedAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Update file hashes for tracking
+ */
+function updateFileHashes(filePaths, projectRoot = process.cwd()) {
+  const stored = loadHashes();
+
+  for (const filePath of filePaths) {
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+    const hash = hashFile(fullPath);
+
+    if (hash) {
+      stored.files[filePath] = {
+        hash,
+        updatedAt: new Date().toISOString()
+      };
+    }
+  }
+
+  saveHashes(stored);
+  return stored;
+}
+
+/**
+ * Mark workflow as verified
+ */
+function markWorkflowVerified(workflowPath) {
+  const staleness = loadStaleness();
+
+  staleness.workflows[workflowPath] = {
+    lastVerified: new Date().toISOString(),
+    status: 'verified'
+  };
+
+  saveStaleness(staleness);
+}
+
+/**
+ * Check staleness of all workflows
+ */
+function checkStaleness() {
+  const staleness = loadStaleness();
+  const now = Date.now();
+  const results = [];
+
+  for (const [workflow, data] of Object.entries(staleness.workflows)) {
+    const lastVerified = new Date(data.lastVerified).getTime();
+    const daysSince = (now - lastVerified) / (1000 * 60 * 60 * 24);
+
+    let status = 'fresh';
+    if (daysSince > staleness.thresholds.staleDays) {
+      status = 'stale';
+    } else if (daysSince > staleness.thresholds.warningDays) {
+      status = 'warning';
+    }
+
+    results.push({
+      workflow,
+      lastVerified: data.lastVerified,
+      daysSince: Math.round(daysSince),
+      status
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Generate drift report
+ */
+function generateReport(workflowPaths, projectRoot = process.cwd()) {
+  const results = [];
+
+  for (const workflow of workflowPaths) {
+    const result = checkWorkflowDrift(workflow, projectRoot);
+    results.push(result);
+  }
+
+  // Summary
+  const summary = {
+    total: results.length,
+    healthy: results.filter(r => r.status === 'healthy').length,
+    needsUpdate: results.filter(r => r.status === 'needs_update').length,
+    stale: results.filter(r => r.status === 'stale').length,
+    critical: results.filter(r => r.status === 'critical').length,
+    generatedAt: new Date().toISOString()
+  };
+
+  return { summary, results };
+}
+
+module.exports = {
+  checkFileChange,
+  checkWorkflowDrift,
+  updateFileHashes,
+  markWorkflowVerified,
+  checkStaleness,
+  generateReport,
+  extractLineReferences,
+  loadHashes,
+  saveHashes,
+  DRIFT_LEVEL
+};