msd-core/hooks/intel-index.js

#!/usr/bin/env node
// Codebase Intelligence - PostToolUse Indexing Hook
// Indexes file exports/imports when Claude writes or edits JS/TS files

const fs = require('fs');
const path = require('path');

// JS/TS file extensions to index
const INDEXABLE_EXTENSIONS = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];

// Convention detection thresholds
const MIN_SAMPLES = 5;
const MIN_MATCH_RATE = 0.70;

// Well-known directory purposes
const DIRECTORY_PURPOSES = {
  'components': 'UI components',
  'hooks': 'React/custom hooks',
  'utils': 'Utility functions',
  'lib': 'Utility functions',
  'services': 'Service layer',
  'api': 'API endpoints',
  'routes': 'API endpoints',
  'types': 'TypeScript types',
  'models': 'Data models',
  'tests': 'Test files',
  '__tests__': 'Test files',
  'test': 'Test files',
  'spec': 'Test files',
  'controllers': 'Controllers',
  'middleware': 'Middleware',
  'config': 'Configuration',
  'constants': 'Constants',
  'assets': 'Static assets',
  'styles': 'Stylesheets',
  'pages': 'Page components',
  'views': 'View templates'
};

// Suffix patterns and their purposes
const SUFFIX_PURPOSES = {
  'test': 'Test files',
  'spec': 'Test files',
  'service': 'Service layer',
  'controller': 'Controllers',
  'model': 'Data models',
  'util': 'Utility functions',
  'utils': 'Utility functions',
  'helper': 'Helper functions',
  'helpers': 'Helper functions',
  'config': 'Configuration',
  'types': 'TypeScript types',
  'type': 'TypeScript types',
  'interface': 'TypeScript interfaces',
  'interfaces': 'TypeScript interfaces',
  'constants': 'Constants',
  'constant': 'Constants',
  'hook': 'React/custom hooks',
  'hooks': 'React/custom hooks',
  'context': 'React context',
  'store': 'State store',
  'slice': 'Redux slice',
  'reducer': 'Redux reducer',
  'action': 'Redux action',
  'actions': 'Redux actions',
  'api': 'API layer',
  'route': 'Route definitions',
  'routes': 'Route definitions',
  'middleware': 'Middleware',
  'schema': 'Schema definitions',
  'styles': 'Stylesheets',
  'mock': 'Mock data',
  'mocks': 'Mock data',
  'fixture': 'Test fixtures',
  'fixtures': 'Test fixtures'
};

/**
 * Extract import sources from file content
 * Returns array of import source paths (e.g., 'react', './utils', '@org/pkg')
 */
function extractImports(content) {
  const imports = new Set();

  // ES6 imports: import { x } from 'y', import x from 'y', import * as x from 'y'
  const es6Named = /import\s+(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]/g;
  let match;
  while ((match = es6Named.exec(content)) !== null) {
    imports.add(match[1]);
  }

  // ES6 side-effect imports: import 'y'
  const es6SideEffect = /import\s+['"]([^'"]+)['"]/g;
  while ((match = es6SideEffect.exec(content)) !== null) {
    // Avoid matching 'from' part of previous pattern
    if (!content.slice(Math.max(0, match.index - 10), match.index).includes('from')) {
      imports.add(match[1]);
    }
  }

  // CommonJS: require('y')
  const cjs = /require\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
  while ((match = cjs.exec(content)) !== null) {
    imports.add(match[1]);
  }

  return Array.from(imports);
}

/**
 * Extract exported symbol names from file content
 * Returns array of export names (e.g., 'functionA', 'ClassB', 'default')
 */
function extractExports(content) {
  const exports = new Set();

  // Named exports: export { x, y, z }
  const namedExport = /export\s*\{([^}]+)\}/g;
  let match;
  while ((match = namedExport.exec(content)) !== null) {
    const names = match[1].split(',').map(n => {
      // Handle "x as y" syntax - export the alias
      const parts = n.trim().split(/\s+as\s+/);
      return parts[parts.length - 1].trim();
    }).filter(n => n);
    names.forEach(n => exports.add(n));
  }

  // Declaration exports: export const|let|var|function|async function|class
  const declExport = /export\s+(?:const|let|var|function\*?|async\s+function|class)\s+(\w+)/g;
  while ((match = declExport.exec(content)) !== null) {
    exports.add(match[1]);
  }

  // Default export: export default (with optional identifier)
  const defaultExport = /export\s+default\s+(?:function\s*\*?\s*|class\s+)?(\w+)?/g;
  while ((match = defaultExport.exec(content)) !== null) {
    exports.add('default');
    if (match[1]) {
      exports.add(match[1]);
    }
  }

  // CommonJS: module.exports = { x, y }
  const cjsExport = /module\.exports\s*=\s*\{([^}]+)\}/g;
  while ((match = cjsExport.exec(content)) !== null) {
    const names = match[1].split(',').map(n => {
      // Handle "x: y" syntax - export the key
      const parts = n.trim().split(/\s*:\s*/);
      return parts[0].trim();
    }).filter(n => n && /^\w+$/.test(n));
    names.forEach(n => exports.add(n));
  }

  // CommonJS: module.exports = identifier
  const cjsSingleExport = /module\.exports\s*=\s*(\w+)\s*[;\n]/g;
  while ((match = cjsSingleExport.exec(content)) !== null) {
    exports.add('default');
    exports.add(match[1]);
  }

  // TypeScript: export type X, export interface X
  const tsExport = /export\s+(?:type|interface)\s+(\w+)/g;
  while ((match = tsExport.exec(content)) !== null) {
    exports.add(match[1]);
  }

  return Array.from(exports);
}

/**
 * Detect naming convention case type for a given name
 * Returns: 'camelCase' | 'PascalCase' | 'snake_case' | 'SCREAMING_SNAKE' | 'kebab-case' | null
 */
function detectCase(name) {
  if (!name || typeof name !== 'string') return null;

  // Skip 'default' as it's a keyword, not a naming convention indicator
  if (name === 'default') return null;

  // Case detection patterns (order matters for specificity)
  const patterns = [
    { name: 'SCREAMING_SNAKE', regex: /^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$/ },
    { name: 'snake_case', regex: /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/ },
    { name: 'kebab-case', regex: /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/ },
    { name: 'PascalCase', regex: /^[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)*$/ },
    { name: 'camelCase', regex: /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]+)+$/ }
  ];

  for (const { name: caseName, regex } of patterns) {
    if (regex.test(name)) {
      return caseName;
    }
  }

  // Single lowercase word could be camelCase (e.g., 'main', 'app')
  if (/^[a-z][a-z0-9]*$/.test(name)) {
    return 'camelCase';
  }

  // Single PascalCase word (e.g., 'App', 'Main')
  if (/^[A-Z][a-z0-9]+$/.test(name)) {
    return 'PascalCase';
  }

  // Single SCREAMING word (e.g., 'DEBUG', 'API')
  if (/^[A-Z][A-Z0-9]*$/.test(name)) {
    return 'SCREAMING_SNAKE';
  }

  return null;
}

/**
 * Detect conventions from the index
 * Analyzes exports, directories, and file suffixes
 * Returns conventions object with detected patterns
 */
function detectConventions(index) {
  const conventions = {
    version: 1,
    updated: Date.now(),
    naming: {},
    directories: {},
    suffixes: {}
  };

  if (!index || !index.files) {
    return conventions;
  }

  // Collect all exports across all files for naming analysis
  const caseCounts = {};
  let totalExports = 0;

  // Collect directory info
  const directoryCounts = {};

  // Collect suffix patterns
  const suffixCounts = {};

  for (const [filePath, fileData] of Object.entries(index.files)) {
    // Analyze exports for naming conventions
    if (fileData.exports && Array.isArray(fileData.exports)) {
      for (const exportName of fileData.exports) {
        const caseType = detectCase(exportName);
        if (caseType) {
          caseCounts[caseType] = (caseCounts[caseType] || 0) + 1;
          totalExports++;
        }
      }
    }

    // Analyze directory structure
    const dirParts = filePath.split(path.sep);
    for (const dirName of dirParts) {
      const purpose = DIRECTORY_PURPOSES[dirName];
      if (purpose) {
        const dirKey = dirName;
        if (!directoryCounts[dirKey]) {
          directoryCounts[dirKey] = { purpose, files: 0 };
        }
        directoryCounts[dirKey].files++;
      }
    }

    // Analyze file suffix patterns
    const suffixMatch = filePath.match(/\.([a-z]+)\.(js|ts|jsx|tsx|mjs|cjs)$/i);
    if (suffixMatch) {
      const suffix = suffixMatch[1].toLowerCase();
      const fullSuffix = `.${suffix}.${suffixMatch[2].toLowerCase()}`;
      if (!suffixCounts[fullSuffix]) {
        const purpose = SUFFIX_PURPOSES[suffix] || 'Unknown';
        suffixCounts[fullSuffix] = { purpose, count: 0 };
      }
      suffixCounts[fullSuffix].count++;
    }
  }

  // Determine dominant naming convention for exports
  if (totalExports >= MIN_SAMPLES) {
    let dominant = null;
    let maxCount = 0;

    for (const [caseType, count] of Object.entries(caseCounts)) {
      if (count > maxCount) {
        maxCount = count;
        dominant = caseType;
      }
    }

    if (dominant && (maxCount / totalExports) >= MIN_MATCH_RATE) {
      conventions.naming.exports = {
        dominant,
        count: maxCount,
        percentage: Math.round((maxCount / totalExports) * 100)
      };
    }
  }

  // Include directories with known purposes
  for (const [dirName, data] of Object.entries(directoryCounts)) {
    conventions.directories[dirName] = {
      purpose: data.purpose,
      files: data.files
    };
  }

  // Include suffix patterns with 5+ occurrences
  for (const [suffix, data] of Object.entries(suffixCounts)) {
    if (data.count >= MIN_SAMPLES) {
      conventions.suffixes[suffix] = {
        purpose: data.purpose,
        count: data.count
      };
    }
  }

  return conventions;
}

/**
 * Update the index.json file with new file entry
 * Uses read-modify-write pattern with synchronous operations
 */
function updateIndex(filePath, exports, imports) {
  const indexPath = path.join(process.cwd(), '.planning', 'intel', 'index.json');

  // Read existing index or create new
  let index = { version: 1, updated: null, files: {} };
  try {
    const content = fs.readFileSync(indexPath, 'utf8');
    index = JSON.parse(content);
  } catch (e) {
    // File doesn't exist or invalid JSON - start fresh
  }

  // Normalize file path to absolute
  const normalizedPath = path.resolve(filePath);

  // Update single file entry (incremental)
  index.files[normalizedPath] = {
    exports,
    imports,
    indexed: Date.now()
  };
  index.updated = Date.now();

  // Ensure directory exists
  fs.mkdirSync(path.dirname(indexPath), { recursive: true });

  // Write atomically
  fs.writeFileSync(indexPath, JSON.stringify(index, null, 2));

  // Detect and save conventions (regenerated on every index update)
  const conventions = detectConventions(index);
  const conventionsPath = path.join(process.cwd(), '.planning', 'intel', 'conventions.json');
  fs.writeFileSync(conventionsPath, JSON.stringify(conventions, null, 2));
}

// Read JSON from stdin (standard hook pattern)
let input = '';
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
  try {
    const data = JSON.parse(input);

    // Only process Write and Edit tools
    if (!['Write', 'Edit'].includes(data.tool_name)) {
      process.exit(0);
    }

    const filePath = data.tool_input?.file_path;
    if (!filePath) {
      process.exit(0);
    }

    // Only index JS/TS files
    const ext = path.extname(filePath).toLowerCase();
    if (!INDEXABLE_EXTENSIONS.includes(ext)) {
      process.exit(0);
    }

    // Get file content
    // Write tool provides content in tool_input
    // Edit tool only provides old_string/new_string, so read from disk
    let content = data.tool_input?.content;
    if (!content) {
      // Edit tool - read file from disk
      const resolvedPath = path.resolve(filePath);
      if (fs.existsSync(resolvedPath)) {
        content = fs.readFileSync(resolvedPath, 'utf8');
      } else {
        // File doesn't exist (shouldn't happen after Edit, but be safe)
        process.exit(0);
      }
    }

    // Extract imports and exports
    const exports = extractExports(content);
    const imports = extractImports(content);

    // Update index
    updateIndex(filePath, exports, imports);

    process.exit(0);
  } catch (error) {
    // Silent failure - never block Claude
    process.exit(0);
  }
});