tokenlean 0.1.0

package/src/config.mjs

@@ -0,0 +1,271 @@
+/**
+ * Shared configuration system for tokenlean CLI tools
+ *
+ * Config files (in order of priority, higher overrides lower):
+ *   1. .tokenleanrc.json in project root (or parent directories)
+ *   2. ~/.tokenleanrc.json (global defaults)
+ *
+ * Example config:
+ * {
+ *   "output": { "maxLines": 100, "format": "text" },
+ *   "ignore": ["node_modules", "dist"],
+ *   "searchPatterns": { ... },
+ *   "hotspots": { "days": 90 },
+ *   "structure": { "depth": 3 }
+ * }
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { homedir } from 'os';
+
+// ─────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────
+
+const CONFIG_FILENAME = '.tokenleanrc.json';
+const GLOBAL_CONFIG_PATH = join(homedir(), CONFIG_FILENAME);
+
+// Default configuration values
+const DEFAULT_CONFIG = {
+  output: {
+    maxLines: null,
+    maxTokens: null,
+    format: 'text'  // 'text' | 'json'
+  },
+  // Extensions to built-in skip/important lists (always extend, never replace)
+  skipDirs: [],
+  skipExtensions: [],
+  importantDirs: [],
+  importantFiles: [],
+  searchPatterns: {
+    hooks: {
+      description: 'React hooks usage',
+      pattern: 'use[A-Z]\\w+\\(',
+      glob: '**/*.{ts,tsx,js,jsx}'
+    },
+    errors: {
+      description: 'Error handling (throw, catch, Error)',
+      pattern: '(throw |catch\\s*\\(|new Error)',
+      glob: '**/*.{ts,tsx,js,jsx,mjs}'
+    },
+    env: {
+      description: 'Environment variables',
+      pattern: 'process\\.env\\.|import\\.meta\\.env',
+      glob: '**/*.{ts,tsx,js,jsx,mjs}'
+    },
+    routes: {
+      description: 'Route definitions',
+      pattern: '(app|router)\\.(get|post|put|delete|patch|use)\\(|path:\\s*[\'"]/',
+      glob: '**/*.{ts,tsx,js,jsx,mjs}'
+    },
+    exports: {
+      description: 'Exported functions and classes',
+      pattern: '^export (function|class|const|default)',
+      glob: '**/*.{ts,tsx,js,jsx,mjs}'
+    },
+    async: {
+      description: 'Async patterns (async/await, Promise)',
+      pattern: '(async |await |Promise\\.|\\. then\\()',
+      glob: '**/*.{ts,tsx,js,jsx,mjs}'
+    }
+  },
+  hotspots: {
+    days: 90
+  },
+  structure: {
+    depth: 3
+  },
+  symbols: {
+    includePrivate: false
+  },
+  impact: {
+    depth: 2
+  }
+};
+
+// ─────────────────────────────────────────────────────────────
+// Config Loading
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Deep merge two objects (source into target)
+ * Arrays are replaced, not merged
+ */
+function deepMerge(target, source) {
+  const result = { ...target };
+
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      target[key] !== null &&
+      typeof target[key] === 'object' &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Load and parse a JSON config file
+ * Returns null if file doesn't exist or is invalid
+ */
+function loadConfigFile(path) {
+  if (!existsSync(path)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(path, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    // Silently ignore invalid JSON - tools can warn if needed
+    return null;
+  }
+}
+
+/**
+ * Find project config by walking up directory tree
+ * Returns { config, path, root } or null if not found
+ */
+function findProjectConfig(startDir = process.cwd()) {
+  let dir = startDir;
+
+  while (dir !== '/') {
+    const configPath = join(dir, CONFIG_FILENAME);
+
+    if (existsSync(configPath)) {
+      const config = loadConfigFile(configPath);
+      if (config) {
+        return { config, path: configPath, root: dir };
+      }
+    }
+
+    dir = dirname(dir);
+  }
+
+  return null;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Main API
+// ─────────────────────────────────────────────────────────────
+
+// Cached merged config
+let cachedConfig = null;
+let cachedProjectRoot = null;
+
+/**
+ * Load and merge all config sources
+ * Returns the merged configuration object
+ */
+export function loadConfig(options = {}) {
+  const { reload = false, startDir = process.cwd() } = options;
+
+  // Return cached config if available
+  if (cachedConfig && !reload) {
+    return { config: cachedConfig, projectRoot: cachedProjectRoot };
+  }
+
+  // Start with defaults
+  let merged = { ...DEFAULT_CONFIG };
+  let projectRoot = startDir;
+
+  // Load global config
+  const globalConfig = loadConfigFile(GLOBAL_CONFIG_PATH);
+  if (globalConfig) {
+    merged = deepMerge(merged, globalConfig);
+  }
+
+  // Load project config (overrides global)
+  const projectResult = findProjectConfig(startDir);
+  if (projectResult) {
+    merged = deepMerge(merged, projectResult.config);
+    projectRoot = projectResult.root;
+  }
+
+  // Cache the result
+  cachedConfig = merged;
+  cachedProjectRoot = projectRoot;
+
+  return { config: merged, projectRoot };
+}
+
+/**
+ * Get a specific config section
+ */
+export function getConfig(section) {
+  const { config } = loadConfig();
+  return section ? config[section] : config;
+}
+
+/**
+ * Get search patterns from config
+ */
+export function getSearchPatterns() {
+  const { config } = loadConfig();
+  return config.searchPatterns || {};
+}
+
+/**
+ * Get output defaults from config
+ */
+export function getOutputDefaults() {
+  const { config } = loadConfig();
+  return config.output || {};
+}
+
+/**
+ * Get ignore patterns from config
+ */
+export function getIgnorePatterns() {
+  const { config } = loadConfig();
+  return config.ignore || [];
+}
+
+/**
+ * Check if config file exists (either global or project)
+ */
+export function hasConfig() {
+  if (existsSync(GLOBAL_CONFIG_PATH)) return true;
+  return findProjectConfig() !== null;
+}
+
+/**
+ * Get paths to config files that would be loaded
+ */
+export function getConfigPaths() {
+  const paths = [];
+
+  if (existsSync(GLOBAL_CONFIG_PATH)) {
+    paths.push({ type: 'global', path: GLOBAL_CONFIG_PATH });
+  }
+
+  const projectResult = findProjectConfig();
+  if (projectResult) {
+    paths.push({ type: 'project', path: projectResult.path });
+  }
+
+  return paths;
+}
+
+/**
+ * Clear the config cache (useful for testing)
+ */
+export function clearConfigCache() {
+  cachedConfig = null;
+  cachedProjectRoot = null;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Exports for direct access
+// ─────────────────────────────────────────────────────────────
+
+export { CONFIG_FILENAME, GLOBAL_CONFIG_PATH, DEFAULT_CONFIG };

package/src/output.mjs

@@ -0,0 +1,251 @@
+/**
+ * Shared output utilities for tokenlean CLI tools
+ *
+ * Centralizes output formatting, truncation, and common options.
+ */
+
+// ─────────────────────────────────────────────────────────────
+// Shell Escaping
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Escape a string for safe use in shell double-quoted strings
+ * Handles: $ ` \ " !
+ */
+export function shellEscape(str) {
+  return str.replace(/[`$"\\!]/g, '\\$&');
+}
+
+/**
+ * Escape a string for use as a ripgrep pattern (regex escaping + shell escaping)
+ */
+export function rgEscape(str) {
+  // First escape regex special chars
+  const regexEscaped = str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Then escape shell special chars
+  return shellEscape(regexEscaped);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Token Estimation
+// ─────────────────────────────────────────────────────────────
+
+export function estimateTokens(content) {
+  if (typeof content !== 'string') return 0;
+  return Math.ceil(content.length / 4);
+}
+
+export function formatTokens(tokens) {
+  if (tokens >= 1000000) return `${(tokens / 1000000).toFixed(1)}M`;
+  if (tokens >= 1000) return `${(tokens / 1000).toFixed(1)}k`;
+  return String(tokens);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Argument Parsing
+// ─────────────────────────────────────────────────────────────
+
+export function parseCommonArgs(args) {
+  const options = {
+    maxLines: Infinity,
+    maxTokens: Infinity,
+    json: false,
+    quiet: false,
+    help: false,
+    remaining: []
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--max-lines' || arg === '-l') {
+      options.maxLines = parseInt(args[++i], 10) || Infinity;
+    } else if (arg === '--max-tokens' || arg === '-t') {
+      options.maxTokens = parseInt(args[++i], 10) || Infinity;
+    } else if (arg === '--json' || arg === '-j') {
+      options.json = true;
+    } else if (arg === '--quiet' || arg === '-q') {
+      options.quiet = true;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else {
+      options.remaining.push(arg);
+    }
+  }
+
+  return options;
+}
+
+export const COMMON_OPTIONS_HELP = `
+Common options:
+  --max-lines N, -l N   Limit output to N lines
+  --max-tokens N, -t N  Limit output to ~N tokens
+  --json, -j            Output as JSON (for piping)
+  --quiet, -q           Minimal output (no headers/stats)
+  --help, -h            Show help`;
+
+// ─────────────────────────────────────────────────────────────
+// Output Builder
+// ─────────────────────────────────────────────────────────────
+
+export class Output {
+  constructor(options = {}) {
+    this.options = {
+      maxLines: options.maxLines ?? Infinity,
+      maxTokens: options.maxTokens ?? Infinity,
+      json: options.json ?? false,
+      quiet: options.quiet ?? false
+    };
+
+    this.lines = [];
+    this.data = {};        // For JSON output
+    this.truncated = false;
+    this.totalLines = 0;
+  }
+
+  // Add a header line (skipped in quiet mode)
+  header(text) {
+    if (!this.options.quiet) {
+      this.lines.push(text);
+    }
+    return this;
+  }
+
+  // Add a blank line (skipped in quiet mode)
+  blank() {
+    if (!this.options.quiet) {
+      this.lines.push('');
+    }
+    return this;
+  }
+
+  // Add content lines (respects limits)
+  add(text) {
+    this.totalLines++;
+
+    if (this.truncated) return this;
+
+    // Check token limit
+    const currentTokens = estimateTokens(this.lines.join('\n'));
+    const newTokens = estimateTokens(text);
+
+    if (currentTokens + newTokens > this.options.maxTokens) {
+      this.truncated = true;
+      return this;
+    }
+
+    // Check line limit
+    if (this.lines.length >= this.options.maxLines) {
+      this.truncated = true;
+      return this;
+    }
+
+    this.lines.push(text);
+    return this;
+  }
+
+  // Add multiple lines at once
+  addLines(textArray) {
+    for (const line of textArray) {
+      this.add(line);
+      if (this.truncated) break;
+    }
+    return this;
+  }
+
+  // Add a section with title and items
+  section(title, items, formatter = (x) => x) {
+    if (items.length === 0) return this;
+
+    this.add(title);
+    for (const item of items) {
+      this.add(formatter(item));
+      if (this.truncated) break;
+    }
+    this.blank();
+    return this;
+  }
+
+  // Set data for JSON output
+  setData(key, value) {
+    this.data[key] = value;
+    return this;
+  }
+
+  // Add stats footer (skipped in quiet mode)
+  stats(text) {
+    if (!this.options.quiet && !this.truncated) {
+      this.lines.push(text);
+    }
+    return this;
+  }
+
+  // Render the output
+  render() {
+    if (this.options.json) {
+      return JSON.stringify({
+        ...this.data,
+        truncated: this.truncated,
+        totalItems: this.totalLines
+      }, null, 2);
+    }
+
+    let output = this.lines.join('\n');
+
+    if (this.truncated) {
+      const remaining = this.totalLines - this.lines.length;
+      if (remaining > 0) {
+        output += `\n\n... truncated (${remaining} more lines)`;
+      } else {
+        output += '\n\n... truncated';
+      }
+    }
+
+    return output;
+  }
+
+  // Print to stdout
+  print() {
+    console.log(this.render());
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Convenience function for simple outputs
+// ─────────────────────────────────────────────────────────────
+
+export function createOutput(options) {
+  return new Output(options);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Table formatting
+// ─────────────────────────────────────────────────────────────
+
+export function formatTable(rows, options = {}) {
+  if (rows.length === 0) return [];
+
+  const { indent = '', separator = '  ' } = options;
+
+  // Calculate column widths
+  const colWidths = [];
+  for (const row of rows) {
+    row.forEach((cell, i) => {
+      const len = String(cell).length;
+      colWidths[i] = Math.max(colWidths[i] || 0, len);
+    });
+  }
+
+  // Format rows
+  return rows.map(row => {
+    const cells = row.map((cell, i) => {
+      const str = String(cell);
+      // Right-align numbers, left-align text
+      if (typeof cell === 'number' || /^[\d,.]+[kMG]?$/.test(str)) {
+        return str.padStart(colWidths[i]);
+      }
+      return str.padEnd(colWidths[i]);
+    });
+    return indent + cells.join(separator);
+  });
+}