tokenlean 0.1.0

package/bin/tl-hotspots.mjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+/**
+ * tl-hotspots - Find frequently changed files (git churn analysis)
+ *
+ * Identifies files that change often - these are usually the most
+ * important to understand when working on a codebase. High churn
+ * files often indicate core logic, bugs, or areas needing refactoring.
+ *
+ * Usage: tl-hotspots [path] [--days N]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-hotspots',
+    desc: 'Find frequently changed files (git churn)',
+    when: 'before-modify',
+    example: 'tl-hotspots --days 30'
+  }));
+  process.exit(0);
+}
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { basename, relative, resolve } from 'path';
+import {
+  createOutput,
+  parseCommonArgs,
+  estimateTokens,
+  formatTokens,
+  shellEscape,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot, shouldSkip, isCodeFile } from '../src/project.mjs';
+import { getConfig } from '../src/config.mjs';
+
+const HELP = `
+tl-hotspots - Find frequently changed files (git churn analysis)
+
+Usage: tl-hotspots [path] [options]
+
+Options:
+  --days N, -d N        Analyze last N days (default: 90)
+  --top N, -n N         Show top N files (default: 20)
+  --authors, -a         Group by author
+  --code-only, -c       Only show code files (no config/docs)
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-hotspots                       # Top 20 hotspots in last 90 days
+  tl-hotspots src/ -d 30            # Hotspots in src/ from last 30 days
+  tl-hotspots -n 10 -c              # Top 10 code files only
+  tl-hotspots -a                    # Show who changes what most
+
+Output shows:
+  • Files sorted by change frequency
+  • Number of commits touching each file
+  • Lines added/removed
+  • Token cost to read the file
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Git Analysis
+// ─────────────────────────────────────────────────────────────
+
+function getGitLog(path, days, projectRoot) {
+  try {
+    // Single quotes around format to prevent shell interpretation of %
+    const cmd = `git -C "${shellEscape(projectRoot)}" log --since="${days} days ago" --format='%H|%an|%ad|%s' --date=short --name-only -- "${shellEscape(path)}"`;
+
+    const output = execSync(cmd, {
+      encoding: 'utf-8',
+      maxBuffer: 50 * 1024 * 1024
+    });
+
+    return parseGitLog(output);
+  } catch (e) {
+    return { commits: [], fileChanges: new Map(), authorChanges: new Map() };
+  }
+}
+
+function parseGitLog(output) {
+  const commits = [];
+  const fileChanges = new Map(); // file -> { commits, additions, deletions, authors }
+  const authorChanges = new Map(); // author -> { commits, files }
+
+  const lines = output.trim().split('\n');
+  let currentCommit = null;
+
+  for (const line of lines) {
+    if (line.includes('|')) {
+      // Commit line: hash|author|date|subject
+      const [hash, author, date, ...subjectParts] = line.split('|');
+      currentCommit = {
+        hash,
+        author,
+        date,
+        subject: subjectParts.join('|'),
+        files: []
+      };
+      commits.push(currentCommit);
+
+      // Track author
+      if (!authorChanges.has(author)) {
+        authorChanges.set(author, { commits: 0, files: new Set() });
+      }
+      authorChanges.get(author).commits++;
+    } else if (line.trim() && currentCommit) {
+      // File line
+      const file = line.trim();
+      currentCommit.files.push(file);
+
+      // Track file changes
+      if (!fileChanges.has(file)) {
+        fileChanges.set(file, { commits: 0, authors: new Set() });
+      }
+      const fc = fileChanges.get(file);
+      fc.commits++;
+      fc.authors.add(currentCommit.author);
+
+      // Track author's files
+      authorChanges.get(currentCommit.author).files.add(file);
+    }
+  }
+
+  return { commits, fileChanges, authorChanges };
+}
+
+function getFileStats(files, projectRoot) {
+  const stats = [];
+
+  for (const [file, data] of files) {
+    const fullPath = resolve(projectRoot, file);
+
+    // Skip if file doesn't exist (deleted) or should be skipped
+    if (!existsSync(fullPath)) {
+      continue;
+    }
+
+    const name = basename(file);
+    if (shouldSkip(name, false)) {
+      continue;
+    }
+
+    try {
+      const content = readFileSync(fullPath, 'utf-8');
+      const tokens = estimateTokens(content);
+      const lines = content.split('\n').length;
+
+      stats.push({
+        file,
+        commits: data.commits,
+        authors: [...data.authors],
+        authorCount: data.authors.size,
+        tokens,
+        lines
+      });
+    } catch {
+      // Can't read file
+    }
+  }
+
+  return stats;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Output Formatting
+// ─────────────────────────────────────────────────────────────
+
+function formatHotspots(stats, out, showAuthors, topN) {
+  // Sort by commit count descending
+  stats.sort((a, b) => b.commits - a.commits);
+
+  const top = stats.slice(0, topN);
+  let totalTokens = 0;
+
+  for (const item of top) {
+    totalTokens += item.tokens;
+
+    let line = `  ${item.commits.toString().padStart(3)} commits`;
+    line += `  ${item.authorCount.toString().padStart(2)} authors`;
+    line += `  ~${formatTokens(item.tokens).padStart(5)}`;
+    line += `  ${item.file}`;
+
+    out.add(line);
+
+    if (showAuthors && item.authors.length > 0) {
+      out.add(`      └─ ${item.authors.slice(0, 3).join(', ')}${item.authors.length > 3 ? '...' : ''}`);
+    }
+  }
+
+  return { count: top.length, totalTokens };
+}
+
+function formatAuthorSummary(authorChanges, out, topN) {
+  const authors = [...authorChanges.entries()]
+    .map(([name, data]) => ({
+      name,
+      commits: data.commits,
+      fileCount: data.files.size
+    }))
+    .sort((a, b) => b.commits - a.commits)
+    .slice(0, topN);
+
+  out.blank();
+  out.add('👥 Top contributors:');
+
+  for (const author of authors) {
+    out.add(`  ${author.commits.toString().padStart(3)} commits  ${author.fileCount.toString().padStart(3)} files  ${author.name}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+// Get config defaults
+const hotspotsConfig = getConfig('hotspots') || {};
+
+// Parse tool-specific options (CLI overrides config)
+let days = hotspotsConfig.days || 90;
+let topN = hotspotsConfig.top || 20;
+let showAuthors = false;
+let codeOnly = false;
+
+const consumedIndices = new Set();
+
+for (let i = 0; i < options.remaining.length; i++) {
+  const arg = options.remaining[i];
+  if ((arg === '--days' || arg === '-d') && options.remaining[i + 1]) {
+    days = parseInt(options.remaining[i + 1], 10);
+    consumedIndices.add(i);
+    consumedIndices.add(i + 1);
+    i++;
+  } else if ((arg === '--top' || arg === '-n') && options.remaining[i + 1]) {
+    topN = parseInt(options.remaining[i + 1], 10);
+    consumedIndices.add(i);
+    consumedIndices.add(i + 1);
+    i++;
+  } else if (arg === '--authors' || arg === '-a') {
+    showAuthors = true;
+    consumedIndices.add(i);
+  } else if (arg === '--code-only' || arg === '-c') {
+    codeOnly = true;
+    consumedIndices.add(i);
+  }
+}
+
+const targetPath = options.remaining.find((a, i) => !a.startsWith('-') && !consumedIndices.has(i)) || '.';
+
+if (options.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const projectRoot = findProjectRoot();
+const resolvedPath = resolve(targetPath);
+const relPath = relative(projectRoot, resolvedPath) || '.';
+
+// Check if we're in a git repo
+try {
+  execSync(`git -C "${shellEscape(projectRoot)}" rev-parse --git-dir`, { encoding: 'utf-8', stdio: 'pipe' });
+} catch {
+  console.error('Error: Not in a git repository');
+  process.exit(1);
+}
+
+const out = createOutput(options);
+
+out.header(`\n🔥 Hotspots: ${relPath === '.' ? basename(projectRoot) : relPath}`);
+out.header(`   Last ${days} days, top ${topN} files`);
+out.blank();
+
+const { commits, fileChanges, authorChanges } = getGitLog(relPath, days, projectRoot);
+
+if (commits.length === 0) {
+  out.add('No commits found in the specified time range.');
+  out.print();
+  process.exit(0);
+}
+
+// Filter to code files if requested
+let filteredChanges = fileChanges;
+if (codeOnly) {
+  filteredChanges = new Map(
+    [...fileChanges.entries()].filter(([file]) => isCodeFile(file))
+  );
+}
+
+const stats = getFileStats(filteredChanges, projectRoot);
+
+if (stats.length === 0) {
+  out.add('No matching files found.');
+  out.print();
+  process.exit(0);
+}
+
+const { count, totalTokens } = formatHotspots(stats, out, showAuthors, topN);
+
+if (showAuthors && authorChanges.size > 0) {
+  formatAuthorSummary(authorChanges, out, 5);
+}
+
+out.blank();
+out.stats('─'.repeat(50));
+out.stats(`📊 ${commits.length} commits, ${stats.length} files changed`);
+out.stats(`   Top ${count} files: ~${formatTokens(totalTokens)} tokens to review`);
+out.blank();
+
+// JSON data
+out.setData('path', relPath);
+out.setData('days', days);
+out.setData('totalCommits', commits.length);
+out.setData('totalFiles', stats.length);
+out.setData('hotspots', stats.slice(0, topN));
+
+out.print();

package/bin/tl-impact.mjs

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+
+/**
+ * tl-impact - Analyze the blast radius of changing a file
+ *
+ * Shows which files import/depend on the target file, helping you
+ * understand the impact of changes before you make them.
+ *
+ * Usage: tl-impact <file> [--depth N]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-impact',
+    desc: 'Blast radius - what depends on this file',
+    when: 'before-modify',
+    example: 'tl-impact src/utils.ts'
+  }));
+  process.exit(0);
+}
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { basename, dirname, extname, relative, resolve } from 'path';
+import {
+  createOutput,
+  parseCommonArgs,
+  estimateTokens,
+  formatTokens,
+  shellEscape,
+  rgEscape,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot, categorizeFile } from '../src/project.mjs';
+
+const HELP = `
+tl-impact - Analyze the blast radius of changing a file
+
+Usage: tl-impact <file> [options]
+
+Options:
+  --depth N, -d N       Include transitive importers up to N levels (default: 1)
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-impact src/utils/api.ts         # Direct importers only
+  tl-impact src/utils/api.ts -d 2    # Include files that import the importers
+  tl-impact src/utils/api.ts -j      # JSON output
+
+Output shows:
+  • Which files import the target
+  • Token cost of each importer
+  • Line number of the import
+  • Categorized by source/test/story/mock
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Import Detection
+// ─────────────────────────────────────────────────────────────
+
+// Use rgEscape from output.mjs for shell-safe regex patterns
+
+function findDirectImporters(filePath, projectRoot) {
+  const ext = extname(filePath);
+  const baseName = basename(filePath, ext);
+  const importers = new Map();
+
+  // Search for the baseName in import/require statements
+  // Use simple pattern to find candidates, then verify in JS
+  const searchTerms = [baseName];
+
+  if (baseName === 'index') {
+    const parentDir = basename(dirname(filePath));
+    searchTerms.push(parentDir);
+  }
+
+  // Use -e for multiple patterns, simpler matching
+  const patterns = searchTerms.map(t => `-e "${rgEscape(t)}"`).join(' ');
+
+  try {
+    const rgCommand = `rg -l --type-add 'code:*.{js,jsx,ts,tsx,mjs,mts,cjs}' -t code ${patterns} "${projectRoot}" 2>/dev/null || true`;
+    const result = execSync(rgCommand, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+    const candidates = result.trim().split('\n').filter(Boolean);
+
+    for (const candidate of candidates) {
+      if (candidate === filePath) continue;
+      if (!existsSync(candidate)) continue;
+
+      const verification = verifyImport(candidate, filePath, projectRoot);
+      if (verification) {
+        importers.set(candidate, verification);
+      }
+    }
+  } catch (e) {
+    // ripgrep error
+  }
+
+  return importers;
+}
+
+function verifyImport(importerPath, targetPath, projectRoot) {
+  try {
+    const content = readFileSync(importerPath, 'utf-8');
+    const lines = content.split('\n');
+    const targetDir = dirname(targetPath);
+    const targetName = basename(targetPath).replace(/\.[^.]+$/, '');
+    const importerDir = dirname(importerPath);
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      const importMatches = [
+        ...line.matchAll(/from\s+['"]([^'"]+)['"]/g),
+        ...line.matchAll(/import\s+['"]([^'"]+)['"]/g),
+        ...line.matchAll(/require\s*\(\s*['"]([^'"]+)['"]\s*\)/g),
+        ...line.matchAll(/import\s*\(\s*['"]([^'"]+)['"]\s*\)/g),
+      ];
+
+      for (const match of importMatches) {
+        const importPath = match[1];
+
+        if (resolveImportPath(importPath, importerDir, targetPath, projectRoot)) {
+          let importType = 'import';
+          if (line.includes('require(')) importType = 'require';
+          if (line.includes('import(')) importType = 'dynamic import';
+          if (line.match(/import\s+type/)) importType = 'type import';
+
+          return { line: i + 1, importType, statement: line.trim().substring(0, 80) };
+        }
+      }
+    }
+  } catch (e) {
+    // File read error
+  }
+
+  return null;
+}
+
+function resolveImportPath(importPath, importerDir, targetPath, projectRoot) {
+  const targetExt = extname(targetPath);
+  const targetName = basename(targetPath, targetExt);
+  const targetDir = dirname(targetPath);
+
+  if (!importPath.startsWith('.') && !importPath.startsWith('/')) {
+    return false;
+  }
+
+  let resolvedPath = resolve(importerDir, importPath);
+  const extensions = ['', '.js', '.jsx', '.ts', '.tsx', '.mjs', '.mts', '/index.js', '/index.ts', '/index.tsx'];
+
+  for (const ext of extensions) {
+    const tryPath = resolvedPath + ext;
+    if (tryPath === targetPath || resolve(tryPath) === resolve(targetPath)) {
+      return true;
+    }
+  }
+
+  if (targetName === 'index') {
+    if (resolvedPath === targetDir || resolve(resolvedPath) === resolve(targetDir)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function findTransitiveImporters(directImporters, targetPath, projectRoot, maxDepth = 2) {
+  const allImporters = new Map(directImporters);
+  const processed = new Set([targetPath]);
+  let currentLevel = [...directImporters.keys()];
+
+  for (let depth = 1; depth < maxDepth && currentLevel.length > 0; depth++) {
+    const nextLevel = [];
+
+    for (const filePath of currentLevel) {
+      if (processed.has(filePath)) continue;
+      processed.add(filePath);
+
+      const importers = findDirectImporters(filePath, projectRoot);
+
+      for (const [path, info] of importers) {
+        if (!allImporters.has(path) && !processed.has(path)) {
+          allImporters.set(path, { ...info, depth, via: basename(filePath) });
+          nextLevel.push(path);
+        }
+      }
+    }
+
+    currentLevel = nextLevel;
+  }
+
+  return allImporters;
+}
+
+
+// ─────────────────────────────────────────────────────────────
+// Output
+// ─────────────────────────────────────────────────────────────
+
+function buildResults(importers, projectRoot) {
+  const categories = { source: [], test: [], story: [], mock: [] };
+
+  for (const [path, info] of importers) {
+    const category = categorizeFile(path, projectRoot);
+    const tokens = estimateTokens(readFileSync(path, 'utf-8'));
+    categories[category].push({
+      path,
+      relPath: relative(projectRoot, path),
+      tokens,
+      ...info
+    });
+  }
+
+  for (const cat of Object.keys(categories)) {
+    categories[cat].sort((a, b) => {
+      if ((a.depth || 0) !== (b.depth || 0)) return (a.depth || 0) - (b.depth || 0);
+      return a.path.localeCompare(b.path);
+    });
+  }
+
+  return categories;
+}
+
+function printCategory(out, title, files, emoji) {
+  if (files.length === 0) return { totalFiles: 0, totalTokens: 0 };
+
+  out.add(`${emoji} ${title} (${files.length}):`);
+
+  let totalTokens = 0;
+  for (const file of files) {
+    totalTokens += file.tokens;
+    let line = `   ${file.relPath} (~${formatTokens(file.tokens)}) L${file.line}`;
+    if (file.depth && file.depth > 0) {
+      line += ` [via ${file.via}]`;
+    }
+    out.add(line);
+  }
+  out.blank();
+
+  return { totalFiles: files.length, totalTokens };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+// Parse tool-specific options
+let maxDepth = 1;
+for (let i = 0; i < options.remaining.length; i++) {
+  const arg = options.remaining[i];
+  if ((arg === '--depth' || arg === '-d') && options.remaining[i + 1]) {
+    maxDepth = parseInt(options.remaining[i + 1], 10);
+    i++;
+  }
+}
+
+const filePath = options.remaining.find(a => !a.startsWith('-'));
+
+if (options.help || !filePath) {
+  console.log(HELP);
+  process.exit(options.help ? 0 : 1);
+}
+
+const resolvedPath = resolve(filePath);
+
+if (!existsSync(resolvedPath)) {
+  console.error(`File not found: ${filePath}`);
+  process.exit(1);
+}
+
+const projectRoot = findProjectRoot();
+const relPath = relative(projectRoot, resolvedPath);
+const targetTokens = estimateTokens(readFileSync(resolvedPath, 'utf-8'));
+
+const out = createOutput(options);
+
+out.header(`\n🎯 Impact analysis: ${relPath}`);
+out.header(`   Target file: ~${formatTokens(targetTokens)} tokens`);
+
+if (maxDepth > 1) {
+  out.header(`   Analyzing ${maxDepth} levels of dependencies...`);
+}
+out.blank();
+
+const directImporters = findDirectImporters(resolvedPath, projectRoot);
+let importers = directImporters;
+if (maxDepth > 1) {
+  importers = findTransitiveImporters(directImporters, resolvedPath, projectRoot, maxDepth);
+}
+
+// Set JSON data
+out.setData('target', relPath);
+out.setData('targetTokens', targetTokens);
+out.setData('maxDepth', maxDepth);
+
+if (importers.size === 0) {
+  out.add('✨ No importers found - this file has no dependents!');
+  out.blank();
+  out.add('This could mean:');
+  out.add('  • It\'s an entry point (main, index)');
+  out.add('  • It\'s a standalone script');
+  out.add('  • It\'s unused and can be safely deleted');
+  out.blank();
+
+  out.setData('importers', []);
+  out.setData('totalFiles', 0);
+  out.setData('totalTokens', 0);
+
+  out.print();
+  process.exit(0);
+}
+
+const categories = buildResults(importers, projectRoot);
+
+// Set JSON data
+out.setData('importers', categories);
+
+let totalFiles = 0;
+let totalTokens = 0;
+
+const s = printCategory(out, 'Source files', categories.source, '📦');
+totalFiles += s.totalFiles; totalTokens += s.totalTokens;
+
+const t = printCategory(out, 'Test files', categories.test, '🧪');
+totalFiles += t.totalFiles; totalTokens += t.totalTokens;
+
+const st = printCategory(out, 'Stories', categories.story, '📖');
+totalFiles += st.totalFiles; totalTokens += st.totalTokens;
+
+const m = printCategory(out, 'Mocks/Fixtures', categories.mock, '🎭');
+totalFiles += m.totalFiles; totalTokens += m.totalTokens;
+
+out.setData('totalFiles', totalFiles);
+out.setData('totalTokens', totalTokens);
+
+out.stats('─'.repeat(50));
+out.stats(`📊 Total impact: ${totalFiles} files, ~${formatTokens(totalTokens)} tokens`);
+out.stats(`   Changing ${basename(resolvedPath)} may affect all listed files.`);
+out.blank();
+
+out.print();