claude-context 1.2.4

package/lib/generate.js

@@ -0,0 +1,302 @@
+/**
+ * Generation module for Claude Context Engineering
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+const chalk = require('chalk');
+
+/**
+ * Generate or regenerate documentation
+ */
+async function generate(projectRoot, options = {}) {
+  const claudeDir = path.join(projectRoot, '.claude');
+  const results = {
+    success: true,
+    generated: []
+  };
+
+  console.log(chalk.blue('\n📝 Generating documentation...\n'));
+
+  // Generate CODE_TO_WORKFLOW_MAP
+  if (options.codeMap) {
+    await generateCodeMap(claudeDir, projectRoot);
+    results.generated.push('CODE_TO_WORKFLOW_MAP.md');
+    console.log(chalk.green('✓ Generated CODE_TO_WORKFLOW_MAP.md'));
+  }
+
+  // Rebuild indexes
+  if (options.indexes) {
+    await generateIndexes(claudeDir);
+    results.generated.push('indexes');
+    console.log(chalk.green('✓ Rebuilt indexes'));
+  }
+
+  // Regenerate semantic anchors
+  if (options.anchors) {
+    await generateAnchors(claudeDir, projectRoot);
+    results.generated.push('anchors.json');
+    console.log(chalk.green('✓ Generated semantic anchors'));
+  }
+
+  // If no specific option, show help
+  if (!options.codeMap && !options.indexes && !options.anchors) {
+    console.log(chalk.yellow('No generation option specified. Available options:'));
+    console.log('  --code-map   Regenerate CODE_TO_WORKFLOW_MAP.md');
+    console.log('  --indexes    Rebuild all indexes');
+    console.log('  --anchors    Regenerate semantic anchors');
+    results.success = false;
+  }
+
+  if (results.generated.length > 0) {
+    console.log(chalk.green(`\n✓ Generated ${results.generated.length} item(s)\n`));
+  }
+
+  return results;
+}
+
+/**
+ * Generate CODE_TO_WORKFLOW_MAP.md
+ */
+async function generateCodeMap(claudeDir, projectRoot) {
+  const mapPath = path.join(claudeDir, 'context', 'CODE_TO_WORKFLOW_MAP.md');
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+
+  // Ensure context directory exists
+  const contextDir = path.join(claudeDir, 'context');
+  if (!fs.existsSync(contextDir)) {
+    fs.mkdirSync(contextDir, { recursive: true });
+  }
+
+  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
+      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.
+
+## Quick Reference
+
+| 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* | Run @context-engineer to document workflows |\n`;
+  }
+
+  output += `
+
+---
+
+## Usage
+
+When modifying a file listed above, check its workflow documentation:
+
+1. Find the file in the table above
+2. Open the linked workflow in \`.claude/context/workflows/\`
+3. Update any affected sections after your changes
+
+## Maintenance
+
+Regenerate this file after adding new workflows:
+
+\`\`\`bash
+npx claude-context generate --code-map
+\`\`\`
+`;
+
+  fs.writeFileSync(mapPath, output);
+}
+
+/**
+ * Generate/rebuild indexes
+ */
+async function generateIndexes(claudeDir) {
+  const indexDir = path.join(claudeDir, 'indexes');
+
+  if (!fs.existsSync(indexDir)) {
+    fs.mkdirSync(indexDir, { recursive: true });
+  }
+
+  // Generate workflow index
+  const workflowDir = path.join(claudeDir, 'context', 'workflows');
+  if (fs.existsSync(workflowDir)) {
+    const workflowFiles = await glob('*.md', { cwd: workflowDir });
+
+    let workflowIndex = `# Workflow Index
+
+> Auto-generated by \`npx claude-context generate --indexes\`
+
+| Workflow | Description |
+|----------|-------------|
+`;
+
+    for (const file of workflowFiles.sort()) {
+      const content = fs.readFileSync(path.join(workflowDir, file), 'utf8');
+      const nameMatch = content.match(/^#\s+(.+)$/m);
+      const descMatch = content.match(/^>\s*(.+)$/m) || content.match(/\n\n([^#\n]+)/);
+
+      const name = nameMatch ? nameMatch[1] : file.replace('.md', '');
+      const desc = descMatch ? descMatch[1].substring(0, 60) + '...' : 'No description';
+
+      workflowIndex += `| [${name}](../context/workflows/${file}) | ${desc} |\n`;
+    }
+
+    fs.writeFileSync(path.join(indexDir, 'WORKFLOW_INDEX.md'), workflowIndex);
+  }
+
+  // Generate agent index
+  const agentDir = path.join(claudeDir, 'agents');
+  if (fs.existsSync(agentDir)) {
+    const agentFiles = await glob('*.md', { cwd: agentDir });
+
+    let agentIndex = `# Agent Index
+
+> Auto-generated by \`npx claude-context generate --indexes\`
+
+| Agent | Specialty |
+|-------|-----------|
+`;
+
+    for (const file of agentFiles.sort()) {
+      const content = fs.readFileSync(path.join(agentDir, file), 'utf8');
+      const nameMatch = content.match(/^#\s+(.+)$/m);
+      const roleMatch = content.match(/##\s+Role\s*\n+([^\n#]+)/i);
+
+      const name = nameMatch ? nameMatch[1] : file.replace('.md', '');
+      const role = roleMatch ? roleMatch[1].substring(0, 50) : 'Specialized agent';
+
+      agentIndex += `| @${file.replace('.md', '')} | ${role} |\n`;
+    }
+
+    fs.writeFileSync(path.join(indexDir, 'AGENT_INDEX.md'), agentIndex);
+  }
+
+  // Generate command index
+  const commandDir = path.join(claudeDir, 'commands');
+  if (fs.existsSync(commandDir)) {
+    const commandFiles = await glob('*.md', { cwd: commandDir });
+
+    let commandIndex = `# Command Index
+
+> Auto-generated by \`npx claude-context generate --indexes\`
+
+| Command | Description |
+|---------|-------------|
+`;
+
+    for (const file of commandFiles.sort()) {
+      const content = fs.readFileSync(path.join(commandDir, file), 'utf8');
+      const nameMatch = content.match(/^#\s+(.+)$/m);
+      const descMatch = content.match(/^>\s*(.+)$/m);
+
+      const name = nameMatch ? nameMatch[1] : '/' + file.replace('.md', '');
+      const desc = descMatch ? descMatch[1].substring(0, 60) : 'No description';
+
+      commandIndex += `| /${file.replace('.md', '')} | ${desc} |\n`;
+    }
+
+    fs.writeFileSync(path.join(indexDir, 'COMMAND_INDEX.md'), commandIndex);
+  }
+}
+
+/**
+ * Generate semantic anchors
+ */
+async function generateAnchors(claudeDir, projectRoot) {
+  const anchorsPath = path.join(claudeDir, 'sync', 'anchors.json');
+  const syncDir = path.join(claudeDir, 'sync');
+
+  if (!fs.existsSync(syncDir)) {
+    fs.mkdirSync(syncDir, { recursive: true });
+  }
+
+  const anchors = {};
+
+  // Find function definitions in source files
+  const sourcePatterns = ['**/*.js', '**/*.ts', '**/*.py', '**/*.go', '**/*.rb'];
+  const ignorePatterns = ['node_modules/**', '.git/**', 'dist/**', 'build/**', 'vendor/**'];
+
+  for (const pattern of sourcePatterns) {
+    const files = await glob(pattern, {
+      cwd: projectRoot,
+      ignore: ignorePatterns,
+      nodir: true
+    });
+
+    for (const file of files.slice(0, 100)) { // Limit for performance
+      try {
+        const content = fs.readFileSync(path.join(projectRoot, file), 'utf8');
+        const lines = content.split('\n');
+
+        // Find function/method definitions
+        const funcPatterns = [
+          /(?:function|async function)\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g,           // JS function
+          /(?:const|let|var)\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*=\s*(?:async\s*)?\(/g,    // JS arrow
+          /def\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g,                                    // Python
+          /func\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/g,                                   // Go
+          /def\s+([a-zA-Z_][a-zA-Z0-9_?!]*)/g                                        // Ruby
+        ];
+
+        for (const pattern of funcPatterns) {
+          let match;
+          while ((match = pattern.exec(content)) !== null) {
+            const funcName = match[1];
+            const lineNum = content.substring(0, match.index).split('\n').length;
+
+            const anchor = `${file}::${funcName}()`;
+            anchors[anchor] = {
+              file,
+              function: funcName,
+              line: lineNum,
+              updated: new Date().toISOString()
+            };
+          }
+        }
+      } catch {
+        // Skip unreadable files
+      }
+    }
+  }
+
+  fs.writeFileSync(anchorsPath, JSON.stringify(anchors, null, 2));
+}
+
+module.exports = { generate };

package/lib/hooks.js

@@ -0,0 +1,150 @@
+/**
+ * Git hooks management for Claude Context Engineering
+ */
+
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+
+const PRE_COMMIT_HOOK = `#!/bin/sh
+# Claude Context Engineering - Pre-commit hook
+# Validates documentation before commits
+
+echo "🔍 Running context validation..."
+
+# Check for unreplaced placeholders in staged files
+STAGED_MD=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\\.md$' || true)
+
+if [ -n "$STAGED_MD" ]; then
+  for file in $STAGED_MD; do
+    if grep -q '{{[A-Z_]*}}' "$file" 2>/dev/null; then
+      echo "⚠️  Warning: Unreplaced placeholder found in $file"
+    fi
+  done
+fi
+
+# Optional: Run full validation (uncomment to enable)
+# npx claude-context validate --all --strict
+
+exit 0
+`;
+
+const POST_COMMIT_HOOK = `#!/bin/sh
+# Claude Context Engineering - Post-commit hook
+# Updates indexes after commits
+
+echo "📝 Updating context indexes..."
+
+# Regenerate CODE_TO_WORKFLOW_MAP if code files changed
+CHANGED_CODE=$(git diff --name-only HEAD~1 HEAD | grep -E '\\.(js|ts|py|go|rb|java|cs|php)$' || true)
+
+if [ -n "$CHANGED_CODE" ]; then
+  echo "Code files changed, consider running: npx claude-context generate --code-map"
+fi
+
+exit 0
+`;
+
+/**
+ * Manage git hooks
+ */
+async function hooks(projectRoot, action, options = {}) {
+  const gitDir = path.join(projectRoot, '.git');
+  const hooksDir = path.join(gitDir, 'hooks');
+
+  const results = {
+    success: true,
+    installed: [],
+    uninstalled: [],
+    errors: []
+  };
+
+  // Check if git repo exists
+  if (!fs.existsSync(gitDir)) {
+    console.error(chalk.red('Error: Not a git repository.'));
+    results.success = false;
+    results.errors.push('Not a git repository');
+    return results;
+  }
+
+  // Ensure hooks directory exists
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+  }
+
+  const hooksToManage = [];
+  if (options.preCommit || (!options.preCommit && !options.postCommit)) {
+    hooksToManage.push({ name: 'pre-commit', content: PRE_COMMIT_HOOK });
+  }
+  if (options.postCommit || (!options.preCommit && !options.postCommit)) {
+    hooksToManage.push({ name: 'post-commit', content: POST_COMMIT_HOOK });
+  }
+
+  if (action === 'install') {
+    console.log(chalk.blue('\n📦 Installing git hooks...\n'));
+
+    for (const hook of hooksToManage) {
+      const hookPath = path.join(hooksDir, hook.name);
+
+      // Backup existing hook if present
+      if (fs.existsSync(hookPath)) {
+        const backupPath = `${hookPath}.backup`;
+        fs.copyFileSync(hookPath, backupPath);
+        console.log(chalk.yellow(`  Backed up existing ${hook.name} to ${hook.name}.backup`));
+      }
+
+      // Write new hook
+      fs.writeFileSync(hookPath, hook.content);
+
+      // Make executable (Unix)
+      try {
+        fs.chmodSync(hookPath, '755');
+      } catch {
+        // Windows doesn't need chmod
+      }
+
+      results.installed.push(hook.name);
+      console.log(chalk.green(`  ✓ Installed ${hook.name} hook`));
+    }
+
+  } else if (action === 'uninstall') {
+    console.log(chalk.blue('\n🗑️  Uninstalling git hooks...\n'));
+
+    for (const hook of hooksToManage) {
+      const hookPath = path.join(hooksDir, hook.name);
+
+      if (fs.existsSync(hookPath)) {
+        // Check if it's our hook
+        const content = fs.readFileSync(hookPath, 'utf8');
+        if (content.includes('Claude Context Engineering')) {
+          fs.unlinkSync(hookPath);
+
+          // Restore backup if exists
+          const backupPath = `${hookPath}.backup`;
+          if (fs.existsSync(backupPath)) {
+            fs.renameSync(backupPath, hookPath);
+            console.log(chalk.yellow(`  Restored ${hook.name} from backup`));
+          }
+
+          results.uninstalled.push(hook.name);
+          console.log(chalk.green(`  ✓ Uninstalled ${hook.name} hook`));
+        } else {
+          console.log(chalk.yellow(`  ⚠ Skipped ${hook.name} (not a claude-context hook)`));
+        }
+      } else {
+        console.log(chalk.gray(`  - ${hook.name} not installed`));
+      }
+    }
+  }
+
+  // Summary
+  if (action === 'install') {
+    console.log(chalk.green(`\n✓ Installed ${results.installed.length} hook(s)\n`));
+  } else {
+    console.log(chalk.green(`\n✓ Uninstalled ${results.uninstalled.length} hook(s)\n`));
+  }
+
+  return results;
+}
+
+module.exports = { hooks };

package/lib/index.js

@@ -0,0 +1,17 @@
+/**
+ * Claude Context CLI - Main exports
+ */
+
+const { validate } = require('./validate');
+const { sync } = require('./sync');
+const { hooks } = require('./hooks');
+const { diagnose } = require('./diagnose');
+const { generate } = require('./generate');
+
+module.exports = {
+  validate,
+  sync,
+  hooks,
+  diagnose,
+  generate
+};