claude-context 1.2.4

package/lib/sync.js

@@ -0,0 +1,263 @@
+/**
+ * Synchronization module for Claude Context Engineering
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+const chalk = require('chalk');
+
+/**
+ * Synchronize documentation with code
+ */
+async function sync(projectRoot, options = {}) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const results = {
+    success: true,
+    driftDetected: false,
+    filesChecked: 0,
+    issuesFound: 0,
+    issuesFixed: 0
+  };
+
+  console.log(chalk.blue('\n🔄 Checking documentation synchronization...\n'));
+
+  // Check for drift
+  if (options.check || options.fix || (!options.rebuildMap)) {
+    const driftResult = await checkDrift(claudeDir, projectRoot, options);
+    results.driftDetected = driftResult.hasDrift;
+    results.filesChecked = driftResult.filesChecked;
+    results.issuesFound = driftResult.issues.length;
+
+    if (options.fix && driftResult.issues.length > 0) {
+      const fixResult = await fixDrift(claudeDir, projectRoot, driftResult.issues);
+      results.issuesFixed = fixResult.fixed;
+    }
+
+    if (options.strict && results.driftDetected) {
+      results.success = false;
+    }
+  }
+
+  // Rebuild CODE_TO_WORKFLOW_MAP
+  if (options.rebuildMap) {
+    await rebuildCodeMap(claudeDir, projectRoot);
+    console.log(chalk.green('✓ CODE_TO_WORKFLOW_MAP.md regenerated'));
+  }
+
+  // Print summary
+  printSyncSummary(results, options);
+
+  return results;
+}
+
+/**
+ * Check for documentation drift
+ */
+async function checkDrift(claudeDir, projectRoot, options) {
+  const result = {
+    hasDrift: false,
+    filesChecked: 0,
+    issues: []
+  };
+
+  // Load staleness tracking
+  const stalenessPath = path.join(claudeDir, 'sync', 'staleness.json');
+  let staleness = {};
+  if (fs.existsSync(stalenessPath)) {
+    try {
+      staleness = JSON.parse(fs.readFileSync(stalenessPath, 'utf8'));
+    } catch {
+      // Start fresh
+    }
+  }
+
+  // Check workflow files against code
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+  if (fs.existsSync(workflowDir)) {
+    const workflowFiles = await glob('*.md', { cwd: workflowDir });
+
+    for (const file of workflowFiles) {
+      result.filesChecked++;
+      const content = fs.readFileSync(path.join(workflowDir, file), 'utf8');
+
+      // Find file:line references
+      const lineRefPattern = /`([^`]+):(\d+)`/g;
+      let match;
+
+      while ((match = lineRefPattern.exec(content)) !== null) {
+        const filePath = match[1];
+        const lineNum = parseInt(match[2], 10);
+        const targetPath = path.join(projectRoot, filePath);
+
+        if (fs.existsSync(targetPath)) {
+          const lines = fs.readFileSync(targetPath, 'utf8').split('\n');
+
+          if (lineNum > lines.length) {
+            result.hasDrift = true;
+            result.issues.push({
+              docFile: file,
+              codeFile: filePath,
+              oldLine: lineNum,
+              newLine: null,
+              type: 'line_exceeded'
+            });
+          }
+        } else {
+          result.hasDrift = true;
+          result.issues.push({
+            docFile: file,
+            codeFile: filePath,
+            oldLine: lineNum,
+            newLine: null,
+            type: 'file_missing'
+          });
+        }
+      }
+    }
+  }
+
+  if (result.issues.length > 0) {
+    console.log(chalk.yellow(`⚠ Found ${result.issues.length} drift issues:`));
+    for (const issue of result.issues.slice(0, 5)) {
+      if (issue.type === 'file_missing') {
+        console.log(chalk.yellow(`  - ${issue.docFile}: File ${issue.codeFile} no longer exists`));
+      } else {
+        console.log(chalk.yellow(`  - ${issue.docFile}: Line ${issue.oldLine} in ${issue.codeFile} is out of range`));
+      }
+    }
+    if (result.issues.length > 5) {
+      console.log(chalk.yellow(`  ... and ${result.issues.length - 5} more`));
+    }
+  } else {
+    console.log(chalk.green('✓ No drift detected'));
+  }
+
+  return result;
+}
+
+/**
+ * Fix drift issues
+ */
+async function fixDrift(claudeDir, projectRoot, issues) {
+  const result = { fixed: 0, failed: 0 };
+
+  // Group issues by doc file
+  const byDocFile = {};
+  for (const issue of issues) {
+    if (!byDocFile[issue.docFile]) {
+      byDocFile[issue.docFile] = [];
+    }
+    byDocFile[issue.docFile].push(issue);
+  }
+
+  for (const [docFile, fileIssues] of Object.entries(byDocFile)) {
+    const docPath = path.join(claudeDir, 'context', 'workflows', docFile);
+    if (!fs.existsSync(docPath)) continue;
+
+    let content = fs.readFileSync(docPath, 'utf8');
+    let modified = false;
+
+    for (const issue of fileIssues) {
+      if (issue.type === 'file_missing') {
+        // Comment out the reference
+        const pattern = new RegExp(`\`${issue.codeFile}:${issue.oldLine}\``, 'g');
+        const newContent = content.replace(pattern, `<!-- REMOVED: ${issue.codeFile}:${issue.oldLine} -->`);
+        if (newContent !== content) {
+          content = newContent;
+          modified = true;
+          result.fixed++;
+        }
+      }
+    }
+
+    if (modified) {
+      fs.writeFileSync(docPath, content);
+    }
+  }
+
+  console.log(chalk.green(`✓ Fixed ${result.fixed} issues`));
+
+  return result;
+}
+
+/**
+ * Rebuild CODE_TO_WORKFLOW_MAP.md
+ */
+async function rebuildCodeMap(claudeDir, projectRoot) {
+  const mapPath = path.join(claudeDir, 'context', 'CODE_TO_WORKFLOW_MAP.md');
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+
+  const codeToWorkflow = {};
+
+  if (fs.existsSync(workflowDir)) {
+    const workflowFiles = await glob('*.md', { cwd: workflowDir });
+
+    for (const file of workflowFiles) {
+      const content = fs.readFileSync(path.join(workflowDir, file), 'utf8');
+
+      // Extract workflow name from first heading
+      const nameMatch = content.match(/^#\s+(.+)$/m);
+      const workflowName = nameMatch ? nameMatch[1] : file.replace('.md', '');
+
+      // Find file references
+      const fileRefPattern = /`([^`]+\.[a-z]+)(?::\d+)?`/g;
+      let match;
+
+      while ((match = fileRefPattern.exec(content)) !== null) {
+        const filePath = match[1];
+        if (!codeToWorkflow[filePath]) {
+          codeToWorkflow[filePath] = [];
+        }
+        if (!codeToWorkflow[filePath].includes(workflowName)) {
+          codeToWorkflow[filePath].push(workflowName);
+        }
+      }
+    }
+  }
+
+  // Generate markdown
+  let output = `# Code to Workflow Map
+
+> Auto-generated by \`npx claude-context generate --code-map\`
+> Last updated: ${new Date().toISOString().split('T')[0]}
+
+This maps source files to their documenting workflows.
+
+| File | Workflows |
+|------|-----------|
+`;
+
+  const sortedFiles = Object.keys(codeToWorkflow).sort();
+  for (const file of sortedFiles) {
+    const workflows = codeToWorkflow[file].join(', ');
+    output += `| \`${file}\` | ${workflows} |\n`;
+  }
+
+  if (sortedFiles.length === 0) {
+    output += `| *No mappings yet* | - |\n`;
+  }
+
+  fs.writeFileSync(mapPath, output);
+}
+
+/**
+ * Print sync summary
+ */
+function printSyncSummary(results, options) {
+  console.log('\n' + chalk.bold('Sync Summary:'));
+  console.log(`  Files checked: ${results.filesChecked}`);
+  console.log(`  Issues found: ${results.issuesFound}`);
+
+  if (options.fix) {
+    console.log(`  Issues fixed: ${results.issuesFixed}`);
+  }
+
+  if (results.success) {
+    console.log(chalk.green('\n✓ Sync check complete!\n'));
+  } else {
+    console.log(chalk.red('\n✗ Drift detected (strict mode).\n'));
+  }
+}
+
+module.exports = { sync };

package/lib/validate.js

@@ -0,0 +1,292 @@
+/**
+ * Validation module for Claude Context Engineering
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+const chalk = require('chalk');
+
+/**
+ * Validate context engineering setup
+ */
+async function validate(projectRoot, options = {}) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const results = {
+    success: true,
+    checks: [],
+    errors: [],
+    warnings: []
+  };
+
+  console.log(chalk.blue('\n🔍 Validating context engineering setup...\n'));
+
+  // Determine which checks to run
+  const runAll = options.all || (!options.schema && !options.links && !options.placeholders && !options.structure && !options.lines);
+
+  // Schema validation
+  if (runAll || options.schema) {
+    const schemaResult = await validateSchemas(claudeDir, options);
+    results.checks.push(schemaResult);
+    if (!schemaResult.passed) {
+      results.errors.push(...schemaResult.errors);
+      results.success = false;
+    }
+  }
+
+  // Link validation
+  if (runAll || options.links) {
+    const linkResult = await validateLinks(claudeDir, projectRoot, options);
+    results.checks.push(linkResult);
+    if (!linkResult.passed) {
+      results.errors.push(...linkResult.errors);
+      results.success = false;
+    }
+  }
+
+  // Placeholder validation
+  if (runAll || options.placeholders) {
+    const placeholderResult = await validatePlaceholders(claudeDir, options);
+    results.checks.push(placeholderResult);
+    if (!placeholderResult.passed) {
+      results.warnings.push(...placeholderResult.errors);
+      // Placeholders are warnings, not failures
+    }
+  }
+
+  // Structure validation
+  if (runAll || options.structure) {
+    const structureResult = await validateStructure(claudeDir, options);
+    results.checks.push(structureResult);
+    if (!structureResult.passed) {
+      results.errors.push(...structureResult.errors);
+      results.success = false;
+    }
+  }
+
+  // Line number validation
+  if (runAll || options.lines) {
+    const lineResult = await validateLineNumbers(claudeDir, projectRoot, options);
+    results.checks.push(lineResult);
+    if (!lineResult.passed) {
+      results.warnings.push(...lineResult.errors);
+    }
+  }
+
+  // Print summary
+  printSummary(results);
+
+  return results;
+}
+
+/**
+ * Validate JSON schemas
+ */
+async function validateSchemas(claudeDir, options) {
+  const result = { name: 'Schema Validation', passed: true, errors: [], count: 0 };
+
+  const schemaDir = path.join(claudeDir, 'schemas');
+  if (!fs.existsSync(schemaDir)) {
+    result.errors.push('No schemas directory found');
+    result.passed = false;
+    return result;
+  }
+
+  const jsonFiles = await glob('**/*.json', { cwd: claudeDir, nodir: true });
+
+  for (const file of jsonFiles) {
+    try {
+      const content = fs.readFileSync(path.join(claudeDir, file), 'utf8');
+      JSON.parse(content);
+      result.count++;
+    } catch (e) {
+      result.errors.push(`Invalid JSON in ${file}: ${e.message}`);
+      result.passed = false;
+    }
+  }
+
+  console.log(result.passed
+    ? chalk.green(`✓ Schema validation: ${result.count} JSON files valid`)
+    : chalk.red(`✗ Schema validation: ${result.errors.length} errors`));
+
+  return result;
+}
+
+/**
+ * Validate internal links
+ */
+async function validateLinks(claudeDir, projectRoot, options) {
+  const result = { name: 'Link Validation', passed: true, errors: [], count: 0 };
+
+  const mdFiles = await glob('**/*.md', { cwd: claudeDir, nodir: true });
+  const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+  for (const file of mdFiles) {
+    const content = fs.readFileSync(path.join(claudeDir, file), 'utf8');
+    let match;
+
+    while ((match = linkPattern.exec(content)) !== null) {
+      const linkPath = match[2];
+
+      // Skip external links and anchors
+      if (linkPath.startsWith('http') || linkPath.startsWith('#') || linkPath.startsWith('mailto:')) {
+        continue;
+      }
+
+      result.count++;
+
+      // Resolve relative path
+      const targetPath = path.resolve(path.dirname(path.join(claudeDir, file)), linkPath.split('#')[0]);
+
+      if (!fs.existsSync(targetPath)) {
+        result.errors.push(`Broken link in ${file}: ${linkPath}`);
+        result.passed = false;
+      }
+    }
+  }
+
+  console.log(result.passed
+    ? chalk.green(`✓ Link validation: ${result.count} links checked`)
+    : chalk.red(`✗ Link validation: ${result.errors.length} broken links`));
+
+  if (options.verbose && result.errors.length > 0) {
+    result.errors.forEach(e => console.log(chalk.yellow(`  - ${e}`)));
+  }
+
+  return result;
+}
+
+/**
+ * Validate placeholders are replaced
+ */
+async function validatePlaceholders(claudeDir, options) {
+  const result = { name: 'Placeholder Validation', passed: true, errors: [], count: 0 };
+
+  const mdFiles = await glob('**/*.md', { cwd: claudeDir, nodir: true });
+  const placeholderPattern = /\{\{([A-Z_]+)\}\}/g;
+
+  for (const file of mdFiles) {
+    const content = fs.readFileSync(path.join(claudeDir, file), 'utf8');
+    let match;
+
+    while ((match = placeholderPattern.exec(content)) !== null) {
+      result.errors.push(`Unreplaced placeholder in ${file}: ${match[0]}`);
+      result.count++;
+      result.passed = false;
+    }
+  }
+
+  console.log(result.passed
+    ? chalk.green(`✓ Placeholder validation: No unreplaced placeholders`)
+    : chalk.yellow(`⚠ Placeholder validation: ${result.count} unreplaced placeholders`));
+
+  return result;
+}
+
+/**
+ * Validate directory structure
+ */
+async function validateStructure(claudeDir, options) {
+  const result = { name: 'Structure Validation', passed: true, errors: [], count: 0 };
+
+  const requiredDirs = [
+    'agents',
+    'commands',
+    'context',
+    'indexes'
+  ];
+
+  for (const dir of requiredDirs) {
+    const dirPath = path.join(claudeDir, dir);
+    if (fs.existsSync(dirPath)) {
+      result.count++;
+    } else {
+      result.errors.push(`Missing required directory: ${dir}`);
+      result.passed = false;
+    }
+  }
+
+  // Check for CLAUDE.md at project root
+  const claudeMdPath = path.join(path.dirname(claudeDir), 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    result.count++;
+  } else {
+    result.errors.push('Missing CLAUDE.md at project root');
+    result.passed = false;
+  }
+
+  console.log(result.passed
+    ? chalk.green(`✓ Structure validation: ${result.count} required items present`)
+    : chalk.red(`✗ Structure validation: ${result.errors.length} missing items`));
+
+  return result;
+}
+
+/**
+ * Validate line number references
+ */
+async function validateLineNumbers(claudeDir, projectRoot, options) {
+  const result = { name: 'Line Number Validation', passed: true, errors: [], count: 0, accurate: 0 };
+  const threshold = parseInt(options.threshold || '60', 10);
+
+  const mdFiles = await glob('**/*.md', { cwd: claudeDir, nodir: true });
+  const lineRefPattern = /`([^`]+):(\d+)`|([a-zA-Z0-9_\-/.]+):(\d+)/g;
+
+  for (const file of mdFiles) {
+    const content = fs.readFileSync(path.join(claudeDir, file), 'utf8');
+    let match;
+
+    while ((match = lineRefPattern.exec(content)) !== null) {
+      const filePath = match[1] || match[3];
+      const lineNum = parseInt(match[2] || match[4], 10);
+
+      // Skip if file path doesn't look like a source file
+      if (!filePath || filePath.includes(' ') || !filePath.includes('.')) {
+        continue;
+      }
+
+      result.count++;
+
+      const targetPath = path.join(projectRoot, filePath);
+      if (fs.existsSync(targetPath)) {
+        try {
+          const lines = fs.readFileSync(targetPath, 'utf8').split('\n');
+          if (lineNum <= lines.length) {
+            result.accurate++;
+          } else {
+            result.errors.push(`Line ${lineNum} exceeds file length in ${filePath} (${lines.length} lines)`);
+          }
+        } catch {
+          // Skip unreadable files
+        }
+      }
+    }
+  }
+
+  const accuracy = result.count > 0 ? Math.round((result.accurate / result.count) * 100) : 100;
+  result.passed = accuracy >= threshold;
+
+  console.log(result.passed
+    ? chalk.green(`✓ Line number validation: ${accuracy}% accurate (threshold: ${threshold}%)`)
+    : chalk.yellow(`⚠ Line number validation: ${accuracy}% accurate (below ${threshold}% threshold)`));
+
+  return result;
+}
+
+/**
+ * Print validation summary
+ */
+function printSummary(results) {
+  console.log('\n' + chalk.bold('Summary:'));
+  console.log(`  Checks run: ${results.checks.length}`);
+  console.log(`  Errors: ${results.errors.length}`);
+  console.log(`  Warnings: ${results.warnings.length}`);
+
+  if (results.success) {
+    console.log(chalk.green('\n✓ All validations passed!\n'));
+  } else {
+    console.log(chalk.red('\n✗ Some validations failed.\n'));
+  }
+}
+
+module.exports = { validate };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "claude-context",
+  "version": "1.2.4",
+  "description": "CLI tools for Claude Context Engineering - validate, sync, diagnose, and manage your context system",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "context-engineering",
+    "documentation",
+    "validation",
+    "cli"
+  ],
+  "author": "SireJeff",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SireJeff/claude-context-engineering-template.git",
+    "directory": "packages/claude-context"
+  },
+  "homepage": "https://github.com/SireJeff/claude-context-engineering-template#readme",
+  "bugs": {
+    "url": "https://github.com/SireJeff/claude-context-engineering-template/issues"
+  },
+  "bin": {
+    "claude-context": "./bin/claude-context.js"
+  },
+  "main": "lib/index.js",
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "commander": "^11.0.0",
+    "chalk": "^4.1.2",
+    "glob": "^10.3.0",
+    "minimatch": "^9.0.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "test:coverage": "jest --coverage"
+  }
+}