tokenlean 0.1.0 → 0.3.0

package/README.md

@@ -18,7 +18,7 @@ the API surface.
 
 ## The Solution
 
-tokenlean provides **25 specialized CLI tools** that give you (or your AI agent) exactly the information needed - no
+tokenlean provides **26 specialized CLI tools** that give you (or your AI agent) exactly the information needed - no
 more, no less. Each tool is designed to answer a specific question about your codebase with minimal token overhead.
 
 Instead of reading a 500-line file to understand its exports, run `tl-exports` (~50 tokens). Instead of reading all your
@@ -128,6 +128,7 @@ Search and discover code patterns.
 
 | Tool        | Description                    | Example               |
 |-------------|--------------------------------|-----------------------|
+| `tl-cache`  | Manage ripgrep result cache    | `tl-cache stats`      |
 | `tl-config` | Show/manage configuration      | `tl-config --init`    |
 | `tl-prompt` | Generate AI agent instructions | `tl-prompt --minimal` |
 
@@ -190,6 +191,48 @@ Project config overrides global config. Both are optional.
 
 Config values extend built-in defaults (they don't replace them).
 
+## Caching
+
+tokenlean caches expensive ripgrep operations to speed up repeated searches. The cache uses **git-based invalidation** - it automatically invalidates when you make commits or modify files.
+
+```bash
+tl-cache stats      # View cache statistics
+tl-cache clear      # Clear cache for current project
+tl-cache clear-all  # Clear all cached data
+```
+
+Cache is stored in `~/.tokenlean/cache/` and is enabled by default.
+
+### Cache Configuration
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "ttl": 300,
+    "maxSize": "100MB",
+    "location": null
+  }
+}
+```
+
+| Option     | Default            | Description                                |
+|------------|--------------------|--------------------------------------------|
+| `enabled`  | `true`             | Enable/disable caching                     |
+| `ttl`      | `300`              | Max age in seconds (fallback for non-git)  |
+| `maxSize`  | `"100MB"`          | Max cache size per project                 |
+| `location` | `null`             | Override default `~/.tokenlean/cache`      |
+
+### Disable Caching
+
+```bash
+# Disable for a single command
+TOKENLEAN_CACHE=0 tl-search hooks
+
+# Disable in config
+echo '{"cache":{"enabled":false}}' > .tokenleanrc.json
+```
+
 ## Example Workflows
 
 ### Starting work on an unfamiliar codebase

package/bin/tl-cache.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+
+/**
+ * tl-cache - Manage tokenlean cache
+ *
+ * View cache statistics and clear cached data.
+ *
+ * Usage: tl-cache [command]
+ */
+
+// Prompt info for tl-prompt
+if (process.argv.includes('--prompt')) {
+  console.log(JSON.stringify({
+    name: 'tl-cache',
+    desc: 'Manage tokenlean cache (stats, clear)',
+    when: 'maintenance',
+    example: 'tl-cache stats'
+  }));
+  process.exit(0);
+}
+
+import {
+  createOutput,
+  parseCommonArgs,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot } from '../src/project.mjs';
+import {
+  getCacheConfig,
+  getCacheStats,
+  clearCache,
+  getCacheDir
+} from '../src/cache.mjs';
+
+const HELP = `
+tl-cache - Manage tokenlean cache
+
+Usage: tl-cache <command> [options]
+
+Commands:
+  stats       Show cache statistics (default)
+  clear       Clear cache for current project
+  clear-all   Clear cache for all projects
+
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-cache                   # Show stats for current project
+  tl-cache stats             # Same as above
+  tl-cache clear             # Clear cache for this project
+  tl-cache clear-all         # Clear all cached data
+
+Configuration:
+  Cache can be configured in .tokenleanrc.json:
+  {
+    "cache": {
+      "enabled": true,       // Enable/disable caching
+      "ttl": 300,            // Max age in seconds (for non-git repos)
+      "maxSize": "100MB",    // Max cache size per project
+      "location": null       // Override ~/.tokenlean/cache
+    }
+  }
+
+Environment:
+  TOKENLEAN_CACHE=0          Disable caching for this run
+`;
+
+// ─────────────────────────────────────────────────────────────
+// Commands
+// ─────────────────────────────────────────────────────────────
+
+function showStats(out, projectRoot) {
+  const config = getCacheConfig();
+  const projectStats = getCacheStats(projectRoot);
+  const globalStats = getCacheStats(null);
+
+  out.header('Cache Configuration:');
+  out.add(`  Enabled:    ${config.enabled ? 'yes' : 'no'}`);
+  out.add(`  Location:   ${config.location}`);
+  out.add(`  Max size:   ${projectStats.maxSizeFormatted}`);
+  out.add(`  TTL:        ${config.ttl}s (fallback for non-git repos)`);
+  out.blank();
+
+  out.header('Current Project Cache:');
+  out.add(`  Directory:  ${projectStats.location}`);
+  out.add(`  Entries:    ${projectStats.entries}`);
+  out.add(`  Size:       ${projectStats.sizeFormatted}`);
+  out.blank();
+
+  out.header('Global Cache:');
+  out.add(`  Projects:   ${globalStats.projects}`);
+  out.add(`  Entries:    ${globalStats.totalEntries}`);
+  out.add(`  Total size: ${globalStats.totalSizeFormatted}`);
+  out.blank();
+
+  // Set JSON data
+  out.setData('config', config);
+  out.setData('project', projectStats);
+  out.setData('global', globalStats);
+}
+
+function doClear(out, projectRoot) {
+  const before = getCacheStats(projectRoot);
+  clearCache(projectRoot);
+  const after = getCacheStats(projectRoot);
+
+  out.add(`Cleared ${before.entries} cache entries (${before.sizeFormatted})`);
+  out.blank();
+
+  out.setData('cleared', {
+    entries: before.entries,
+    size: before.size,
+    sizeFormatted: before.sizeFormatted
+  });
+}
+
+function doClearAll(out) {
+  const before = getCacheStats(null);
+  clearCache(null);
+  const after = getCacheStats(null);
+
+  out.add(`Cleared ${before.totalEntries} cache entries across ${before.projects} projects (${before.totalSizeFormatted})`);
+  out.blank();
+
+  out.setData('cleared', {
+    projects: before.projects,
+    entries: before.totalEntries,
+    size: before.totalSize,
+    sizeFormatted: before.totalSizeFormatted
+  });
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main
+// ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const options = parseCommonArgs(args);
+
+if (options.help) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+const command = options.remaining.find(a => !a.startsWith('-')) || 'stats';
+const projectRoot = findProjectRoot();
+const out = createOutput(options);
+
+switch (command) {
+  case 'stats':
+    showStats(out, projectRoot);
+    break;
+
+  case 'clear':
+    doClear(out, projectRoot);
+    break;
+
+  case 'clear-all':
+    doClearAll(out);
+    break;
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.log('Use: stats, clear, or clear-all');
+    process.exit(1);
+}
+
+out.print();

package/bin/tl-component.mjs

@@ -21,16 +21,27 @@ if (process.argv.includes('--prompt')) {
 }
 
 import { readFileSync, existsSync } from 'fs';
-import { join, relative, dirname, basename } from 'path';
-
-function findProjectRoot() {
-  let dir = process.cwd();
-  while (dir !== '/') {
-    if (existsSync(join(dir, 'package.json'))) return dir;
-    dir = dirname(dir);
-  }
-  return process.cwd();
-}
+import { join, relative } from 'path';
+import {
+  createOutput,
+  parseCommonArgs,
+  estimateTokens,
+  formatTokens,
+  COMMON_OPTIONS_HELP
+} from '../src/output.mjs';
+import { findProjectRoot } from '../src/project.mjs';
+
+const HELP = `
+tl-component - React component analyzer
+
+Usage: tl-component <file.tsx> [options]
+${COMMON_OPTIONS_HELP}
+
+Examples:
+  tl-component src/Button.tsx       # Analyze component
+  tl-component src/App.tsx -j       # JSON output
+  tl-component src/Modal.tsx -q     # Quiet (minimal)
+`;
 
 function extractImports(content) {
   const imports = {
@@ -175,79 +186,14 @@ function extractRedux(content) {
   return redux;
 }
 
-function printAnalysis(analysis) {
-  const { file, lines, tokens, imports, hooks, propsInfo, components, styles, redux } = analysis;
-
-  console.log(`\n🧩 Component Analysis: ${file}`);
-  console.log(`   ${lines} lines, ~${tokens} tokens\n`);
-
-  // Components
-  if (components.length > 0) {
-    console.log(`📦 Components: ${components.join(', ')}`);
-  }
-
-  // Props
-  if (propsInfo) {
-    console.log(`\n📋 ${propsInfo.name}:`);
-    for (const p of propsInfo.props) {
-      const opt = p.optional ? '?' : '';
-      console.log(`   ${p.name}${opt}: ${p.type}`);
-    }
-  }
-
-  // Hooks
-  if (hooks.length > 0) {
-    console.log(`\n🪝 Hooks: ${hooks.join(', ')}`);
-  }
-
-  // Redux
-  if (redux.dispatch || redux.selectors.length > 0) {
-    console.log(`\n📦 Redux:`);
-    if (redux.selectors.length > 0) {
-      console.log(`   Selectors: ${redux.selectors.join(', ')}`);
-    }
-    if (redux.actions.length > 0) {
-      console.log(`   Actions: ${redux.actions.join(', ')}`);
-    }
-  }
-
-  // Imports summary
-  console.log(`\n📥 Imports:`);
-  if (imports.react.length > 0) {
-    console.log(`   React: ${imports.react.join(', ')}`);
-  }
-  if (imports.reactNative.length > 0) {
-    console.log(`   React Native: ${imports.reactNative.join(', ')}`);
-  }
-  if (imports.internal.length > 0) {
-    console.log(`   Internal: ${imports.internal.length} modules`);
-    for (const i of imports.internal.slice(0, 5)) {
-      console.log(`     ${i.source}`);
-    }
-    if (imports.internal.length > 5) {
-      console.log(`     ... and ${imports.internal.length - 5} more`);
-    }
-  }
-  if (imports.external.length > 0) {
-    console.log(`   External: ${imports.external.map(i => i.source).join(', ')}`);
-  }
-
-  // Styles
-  if (styles.length > 0) {
-    console.log(`\n🎨 Styling: ${styles.join(', ')}`);
-  }
-
-  console.log();
-}
-
 // Main
 const args = process.argv.slice(2);
-const targetFile = args[0];
+const options = parseCommonArgs(args);
+const targetFile = options.remaining.find(a => !a.startsWith('-'));
 
-if (!targetFile) {
-  console.log('\nUsage: claude-component <file.tsx>\n');
-  console.log('Analyzes a React component to show props, hooks, and dependencies.');
-  process.exit(1);
+if (options.help || !targetFile) {
+  console.log(HELP);
+  process.exit(options.help ? 0 : 1);
 }
 
 const fullPath = targetFile.startsWith('/') ? targetFile : join(process.cwd(), targetFile);
@@ -258,11 +204,12 @@ if (!existsSync(fullPath)) {
 
 const content = readFileSync(fullPath, 'utf-8');
 const projectRoot = findProjectRoot();
+const relPath = relative(projectRoot, fullPath);
 
 const analysis = {
-  file: relative(projectRoot, fullPath),
+  file: relPath,
   lines: content.split('\n').length,
-  tokens: Math.ceil(content.length / 4),
+  tokens: estimateTokens(content),
   imports: extractImports(content),
   hooks: extractHooks(content),
   propsInfo: extractProps(content),
@@ -271,4 +218,83 @@ const analysis = {
   redux: extractRedux(content)
 };
 
-printAnalysis(analysis);
+const out = createOutput(options);
+
+// Set JSON data
+out.setData('file', analysis.file);
+out.setData('lines', analysis.lines);
+out.setData('tokens', analysis.tokens);
+out.setData('components', analysis.components);
+out.setData('props', analysis.propsInfo);
+out.setData('hooks', analysis.hooks);
+out.setData('imports', analysis.imports);
+out.setData('styles', analysis.styles);
+out.setData('redux', analysis.redux);
+
+// Headers
+out.header(`Component Analysis: ${analysis.file}`);
+out.header(`${analysis.lines} lines, ~${formatTokens(analysis.tokens)} tokens`);
+out.blank();
+
+// Components
+if (analysis.components.length > 0) {
+  out.add(`Components: ${analysis.components.join(', ')}`);
+}
+
+// Props
+if (analysis.propsInfo) {
+  out.blank();
+  out.add(`${analysis.propsInfo.name}:`);
+  for (const p of analysis.propsInfo.props) {
+    const opt = p.optional ? '?' : '';
+    out.add(`  ${p.name}${opt}: ${p.type}`);
+  }
+}
+
+// Hooks
+if (analysis.hooks.length > 0) {
+  out.blank();
+  out.add(`Hooks: ${analysis.hooks.join(', ')}`);
+}
+
+// Redux
+if (analysis.redux.dispatch || analysis.redux.selectors.length > 0) {
+  out.blank();
+  out.add('Redux:');
+  if (analysis.redux.selectors.length > 0) {
+    out.add(`  Selectors: ${analysis.redux.selectors.join(', ')}`);
+  }
+  if (analysis.redux.actions.length > 0) {
+    out.add(`  Actions: ${analysis.redux.actions.join(', ')}`);
+  }
+}
+
+// Imports summary
+out.blank();
+out.add('Imports:');
+if (analysis.imports.react.length > 0) {
+  out.add(`  React: ${analysis.imports.react.join(', ')}`);
+}
+if (analysis.imports.reactNative.length > 0) {
+  out.add(`  React Native: ${analysis.imports.reactNative.join(', ')}`);
+}
+if (analysis.imports.internal.length > 0) {
+  out.add(`  Internal: ${analysis.imports.internal.length} modules`);
+  for (const i of analysis.imports.internal.slice(0, 5)) {
+    out.add(`    ${i.source}`);
+  }
+  if (analysis.imports.internal.length > 5) {
+    out.add(`    ... and ${analysis.imports.internal.length - 5} more`);
+  }
+}
+if (analysis.imports.external.length > 0) {
+  out.add(`  External: ${analysis.imports.external.map(i => i.source).join(', ')}`);
+}
+
+// Styles
+if (analysis.styles.length > 0) {
+  out.blank();
+  out.add(`Styling: ${analysis.styles.join(', ')}`);
+}
+
+out.print();