tokenlean 0.1.0

package/bin/tl-flow.mjs

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+
+/**
+ * tl-flow - Show call graph for a function
+ *
+ * Traces what calls a function and what it calls.
+ * Helps understand code paths without reading entire files.
+ *
+ * Usage: tl-flow <function-name> [file]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-flow',
+    desc: 'Call graph: what calls this, what it calls',
+    when: 'before-read',
+    example: 'tl-flow handleSubmit'
+  }));
+  process.exit(0);
+}
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { basename, dirname, relative, resolve, extname } from 'path';
+import {
+  createOutput,
+  parseCommonArgs,
+  shellEscape,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot } from '../src/project.mjs';
+
+const HELP = `
+tl-flow - Show call graph for a function
+
+Usage: tl-flow <function-name> [options]
+
+Options:
+  --file, -f <file>     Limit search to specific file
+  --depth N, -d N       Max depth for call tree (default: 2)
+  --callers             Show only what calls this function
+  --callees             Show only what this function calls
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-flow handleSubmit           # Find handleSubmit and trace calls
+  tl-flow loadConfig -f src/     # Search only in src/
+  tl-flow parseArgs --callers    # Only show what calls parseArgs
+  tl-flow render --depth 3       # Deeper call tree
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Function Finding
+// ─────────────────────────────────────────────────────────────
+
+function findFunctionDefinitions(name, projectRoot, limitPath) {
+  const searchPath = limitPath || projectRoot;
+  const definitions = [];
+
+  try {
+    // Pattern to find function definitions
+    const patterns = [
+      `function ${name}\\s*\\(`,           // function name(
+      `(const|let|var)\\s+${name}\\s*=`,   // const name =
+      `${name}\\s*:\\s*\\(`,               // name: ( (object method)
+      `${name}\\s*\\([^)]*\\)\\s*\\{`,     // name() { (class method)
+      `async\\s+${name}\\s*\\(`,           // async name(
+    ];
+
+    const pattern = `(${patterns.join('|')})`;
+    const cmd = `rg -n -g "*.{ts,tsx,js,jsx,mjs}" --no-heading -e "${shellEscape(pattern)}" "${shellEscape(searchPath)}" 2>/dev/null || true`;
+
+    const result = execSync(cmd, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+
+    for (const line of result.trim().split('\n')) {
+      if (!line) continue;
+      const match = line.match(/^([^:]+):(\d+):(.*)$/);
+      if (!match) continue;
+
+      const [, file, lineNum, content] = match;
+      if (file.includes('node_modules')) continue;
+      if (file.includes('.test.') || file.includes('.spec.')) continue;
+
+      definitions.push({
+        file,
+        line: parseInt(lineNum, 10),
+        content: content.trim()
+      });
+    }
+  } catch (e) {
+    // rg error
+  }
+
+  return definitions;
+}
+
+function findCallers(name, projectRoot, excludeFile) {
+  const callers = [];
+
+  try {
+    // Find calls to the function
+    const pattern = `${name}\\s*\\(`;
+    const cmd = `rg -n -g "*.{ts,tsx,js,jsx,mjs}" --no-heading -e "${shellEscape(pattern)}" "${shellEscape(projectRoot)}" 2>/dev/null || true`;
+
+    const result = execSync(cmd, { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 });
+
+    for (const line of result.trim().split('\n')) {
+      if (!line) continue;
+      const match = line.match(/^([^:]+):(\d+):(.*)$/);
+      if (!match) continue;
+
+      const [, file, lineNum, content] = match;
+      if (file.includes('node_modules')) continue;
+
+      // Skip the definition itself
+      if (content.includes(`function ${name}`) ||
+          content.includes(`const ${name}`) ||
+          content.includes(`let ${name}`) ||
+          content.includes(`var ${name}`)) {
+        continue;
+      }
+
+      // Find which function contains this call
+      const containingFn = findContainingFunction(file, parseInt(lineNum, 10));
+
+      callers.push({
+        file,
+        line: parseInt(lineNum, 10),
+        content: content.trim(),
+        caller: containingFn
+      });
+    }
+  } catch (e) {
+    // rg error
+  }
+
+  // Dedupe by file+caller
+  const seen = new Set();
+  return callers.filter(c => {
+    const key = `${c.file}:${c.caller || 'top'}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function findContainingFunction(file, lineNum) {
+  try {
+    const content = readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    // Look backwards for function definition
+    for (let i = lineNum - 1; i >= 0; i--) {
+      const line = lines[i];
+
+      // Match function definitions
+      const fnMatch = line.match(/(?:function|async function)\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\(|(\w+)\s*\([^)]*\)\s*\{/);
+      if (fnMatch) {
+        return fnMatch[1] || fnMatch[2] || fnMatch[3];
+      }
+
+      // Match class method
+      const methodMatch = line.match(/^\s*(?:async\s+)?(\w+)\s*\([^)]*\)\s*\{/);
+      if (methodMatch && !line.includes('if') && !line.includes('while') && !line.includes('for')) {
+        return methodMatch[1];
+      }
+    }
+  } catch (e) {
+    // Can't read file
+  }
+
+  return null;
+}
+
+function findCallees(file, fnName, lineNum) {
+  const callees = [];
+
+  try {
+    const content = readFileSync(file, 'utf-8');
+    const lines = content.split('\n');
+
+    // Find the function body
+    let braceCount = 0;
+    let inFunction = false;
+    let startLine = lineNum - 1;
+
+    // Find start of function
+    for (let i = startLine; i < lines.length; i++) {
+      const line = lines[i];
+
+      if (!inFunction && line.includes('{')) {
+        inFunction = true;
+      }
+
+      if (inFunction) {
+        braceCount += (line.match(/\{/g) || []).length;
+        braceCount -= (line.match(/\}/g) || []).length;
+
+        // Find function calls in this line
+        const callMatches = line.matchAll(/(\w+)\s*\(/g);
+        for (const match of callMatches) {
+          const callee = match[1];
+          // Skip common keywords
+          if (['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof', 'new'].includes(callee)) {
+            continue;
+          }
+          // Skip the function's own name (recursion is fine but don't list as primary callee)
+          if (callee === fnName) continue;
+
+          if (!callees.includes(callee)) {
+            callees.push(callee);
+          }
+        }
+
+        if (braceCount === 0) break;
+      }
+    }
+  } catch (e) {
+    // Can't read file
+  }
+
+  return callees;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+if (options.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+// Parse tool-specific options
+let targetFile = null;
+let depth = 2;
+let showCallers = true;
+let showCallees = true;
+
+const remaining = [];
+for (let i = 0; i < options.remaining.length; i++) {
+  const arg = options.remaining[i];
+  if ((arg === '--file' || arg === '-f') && options.remaining[i + 1]) {
+    targetFile = options.remaining[++i];
+  } else if ((arg === '--depth' || arg === '-d') && options.remaining[i + 1]) {
+    depth = parseInt(options.remaining[++i], 10);
+  } else if (arg === '--callers') {
+    showCallees = false;
+  } else if (arg === '--callees') {
+    showCallers = false;
+  } else if (!arg.startsWith('-')) {
+    remaining.push(arg);
+  }
+}
+
+const fnName = remaining[0];
+
+if (!fnName) {
+  console.log(HELP);
+  process.exit(1);
+}
+
+const projectRoot = findProjectRoot();
+const out = createOutput(options);
+
+out.header(`\n🔀 Call flow: ${fnName}`);
+
+// Find function definitions
+const definitions = findFunctionDefinitions(fnName, projectRoot, targetFile);
+
+if (definitions.length === 0) {
+  out.add(`\n  No definition found for "${fnName}"`);
+  out.print();
+  process.exit(0);
+}
+
+// Show definitions
+out.add('\n📍 Defined in:');
+for (const def of definitions.slice(0, 5)) {
+  const rel = relative(projectRoot, def.file);
+  out.add(`   ${rel}:${def.line}`);
+}
+
+// Show callers
+if (showCallers) {
+  const callers = findCallers(fnName, projectRoot);
+
+  if (callers.length > 0) {
+    out.add('\n⬅️  Called by:');
+    for (const caller of callers.slice(0, 10)) {
+      const rel = relative(projectRoot, caller.file);
+      const from = caller.caller ? ` (in ${caller.caller})` : '';
+      out.add(`   ${rel}:${caller.line}${from}`);
+    }
+    if (callers.length > 10) {
+      out.add(`   ... and ${callers.length - 10} more`);
+    }
+  } else {
+    out.add('\n⬅️  Called by: (no callers found)');
+  }
+}
+
+// Show callees
+if (showCallees && definitions.length > 0) {
+  const def = definitions[0];
+  const callees = findCallees(def.file, fnName, def.line);
+
+  if (callees.length > 0) {
+    out.add('\n➡️  Calls:');
+    out.add(`   ${callees.slice(0, 15).join(', ')}`);
+    if (callees.length > 15) {
+      out.add(`   ... and ${callees.length - 15} more`);
+    }
+  } else {
+    out.add('\n➡️  Calls: (no function calls found)');
+  }
+}
+
+out.add('');
+out.print();

package/bin/tl-history.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+
+/**
+ * tl-history - Recent changes to a file, summarized
+ *
+ * Shows commit history for a file without full diffs - just commit messages,
+ * authors, and dates. Perfect for understanding how a file has evolved.
+ *
+ * Usage: tl-history <file> [--limit N]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-history',
+    desc: 'Recent changes to a file (commits only)',
+    when: 'before-read',
+    example: 'tl-history src/api.ts'
+  }));
+  process.exit(0);
+}
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { basename, relative } from 'path';
+import {
+  createOutput,
+  parseCommonArgs,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot } from '../src/project.mjs';
+
+const HELP = `
+tl-history - Recent changes to a file, summarized
+
+Usage: tl-history <file> [options]
+
+Options:
+  --limit N, -n N       Number of commits to show (default: 20)
+  --since <date>        Only commits after date (e.g., "2 weeks ago", "2024-01-01")
+  --author <name>       Filter by author
+  --stat                Show file change stats (+/- lines)
+  --oneline             Ultra-compact one-line format
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-history src/api.ts              # Recent commits
+  tl-history src/api.ts -n 50        # Last 50 commits
+  tl-history src/api.ts --since "1 month ago"
+  tl-history src/api.ts --stat       # With change stats
+  tl-history src/api.ts --oneline    # Compact format
+
+Output includes:
+  - Commit hash (short)
+  - Date
+  - Author
+  - Commit message
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Git Operations
+// ─────────────────────────────────────────────────────────────
+
+function getFileHistory(filePath, options = {}) {
+  const {
+    limit = 20,
+    since = null,
+    author = null,
+    stat = false
+  } = options;
+
+  const args = ['log', `--max-count=${limit}`, '--pretty=format:%H|%h|%ai|%an|%s'];
+
+  if (since) {
+    args.push(`--since=${since}`);
+  }
+
+  if (author) {
+    args.push(`--author=${author}`);
+  }
+
+  if (stat) {
+    args.push('--numstat');
+  }
+
+  args.push('--follow');  // Follow file renames
+  args.push('--', filePath);
+
+  const result = spawnSync('git', args, {
+    encoding: 'utf-8',
+    maxBuffer: 10 * 1024 * 1024
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  if (result.status !== 0 && result.stderr) {
+    if (result.stderr.includes('not a git repository')) {
+      throw new Error('Not in a git repository');
+    }
+    throw new Error(result.stderr);
+  }
+
+  return parseGitLog(result.stdout || '', stat);
+}
+
+function parseGitLog(output, includeStat) {
+  const commits = [];
+  const lines = output.trim().split('\n');
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line) {
+      i++;
+      continue;
+    }
+
+    // Parse commit line: hash|shortHash|date|author|message
+    const parts = line.split('|');
+    if (parts.length >= 5) {
+      const commit = {
+        hash: parts[0],
+        shortHash: parts[1],
+        date: parts[2],
+        author: parts[3],
+        message: parts.slice(4).join('|'),  // Message might contain |
+        stats: null
+      };
+
+      i++;
+
+      // If stat mode, parse numstat lines
+      if (includeStat) {
+        let added = 0;
+        let deleted = 0;
+
+        while (i < lines.length && lines[i] && !lines[i].includes('|')) {
+          const statLine = lines[i].trim();
+          if (statLine) {
+            const statParts = statLine.split('\t');
+            if (statParts.length >= 2) {
+              const a = parseInt(statParts[0], 10) || 0;
+              const d = parseInt(statParts[1], 10) || 0;
+              added += a;
+              deleted += d;
+            }
+          }
+          i++;
+        }
+
+        if (added > 0 || deleted > 0) {
+          commit.stats = { added, deleted };
+        }
+      }
+
+      commits.push(commit);
+    } else {
+      i++;
+    }
+  }
+
+  return commits;
+}
+
+function formatDate(isoDate) {
+  // Convert "2024-01-15 14:30:45 +0000" to "Jan 15"
+  const date = new Date(isoDate);
+  const now = new Date();
+  const diffDays = Math.floor((now - date) / (1000 * 60 * 60 * 24));
+
+  if (diffDays === 0) return 'today';
+  if (diffDays === 1) return 'yesterday';
+  if (diffDays < 7) return `${diffDays}d ago`;
+
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const month = months[date.getMonth()];
+  const day = date.getDate();
+
+  if (date.getFullYear() === now.getFullYear()) {
+    return `${month} ${day}`;
+  }
+
+  return `${month} ${day}, ${date.getFullYear()}`;
+}
+
+function formatStats(stats) {
+  if (!stats) return '';
+  const { added, deleted } = stats;
+  const parts = [];
+  if (added > 0) parts.push(`+${added}`);
+  if (deleted > 0) parts.push(`-${deleted}`);
+  return parts.length > 0 ? ` (${parts.join('/')})` : '';
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+// Parse custom options
+let limit = 20;
+let since = null;
+let author = null;
+let showStat = false;
+let oneline = false;
+
+const remaining = [];
+for (let i = 0; i < options.remaining.length; i++) {
+  const arg = options.remaining[i];
+
+  if (arg === '--limit' || arg === '-n') {
+    limit = parseInt(options.remaining[++i], 10) || 20;
+  } else if (arg === '--since') {
+    since = options.remaining[++i];
+  } else if (arg === '--author') {
+    author = options.remaining[++i];
+  } else if (arg === '--stat') {
+    showStat = true;
+  } else if (arg === '--oneline') {
+    oneline = true;
+  } else if (!arg.startsWith('-')) {
+    remaining.push(arg);
+  }
+}
+
+const filePath = remaining[0];
+
+if (options.help || !filePath) {
+  console.log(HELP);
+  process.exit(options.help ? 0 : 1);
+}
+
+if (!existsSync(filePath)) {
+  console.error(`File not found: ${filePath}`);
+  process.exit(1);
+}
+
+const projectRoot = findProjectRoot();
+const relPath = relative(projectRoot, filePath);
+const out = createOutput(options);
+
+try {
+  const commits = getFileHistory(filePath, { limit, since, author, stat: showStat });
+
+  if (commits.length === 0) {
+    console.log('No commits found for this file');
+    process.exit(0);
+  }
+
+  // Set JSON data
+  out.setData('file', relPath);
+  out.setData('commits', commits);
+  out.setData('totalCommits', commits.length);
+
+  // Format output
+  out.header(`📜 ${relPath} - ${commits.length} recent commits`);
+  out.blank();
+
+  for (const commit of commits) {
+    if (oneline) {
+      const statsStr = formatStats(commit.stats);
+      out.add(`${commit.shortHash} ${formatDate(commit.date)} ${commit.message}${statsStr}`);
+    } else {
+      const statsStr = formatStats(commit.stats);
+      out.add(`${commit.shortHash}  ${formatDate(commit.date).padEnd(12)}  ${commit.author}`);
+      out.add(`        ${commit.message}${statsStr}`);
+      out.blank();
+    }
+  }
+
+  // Summary
+  if (!options.quiet && !oneline) {
+    const authors = new Set(commits.map(c => c.author));
+    const oldestDate = commits[commits.length - 1]?.date;
+    const oldest = oldestDate ? formatDate(oldestDate) : '';
+
+    out.add(`---`);
+    out.add(`${commits.length} commits by ${authors.size} author(s), oldest: ${oldest}`);
+  }
+
+  out.print();
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}