skannr 0.1.1

package/src/cli.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for skannr
+ */
+
+import { analyzeProject, getCacheManager } from './index';
+import * as path from 'path';
+import { loadConfig } from './config';
+import { discoverModules } from './scanner';
+
+interface CliArgs {
+  root: string;
+  question: string;
+  limit: number;
+  limitProvided: boolean;
+  generateMapping: boolean;
+  mappingOutputPath?: string;
+  moduleKeys?: string[];
+  lang: 'typescript' | 'javascript' | 'python' | 'auto';
+  skipCache?: boolean;
+  cacheCommand?: 'clear' | 'stats';
+}
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs(): CliArgs | null {
+  const args = process.argv.slice(2);
+
+  let root = process.cwd();
+  let question = '';
+  let limit = 10;
+  let limitProvided = false;
+  let generateMapping = false;
+  let mappingOutputPath: string | undefined;
+  let moduleKeys: string[] | undefined;
+  let lang: 'typescript' | 'javascript' | 'python' | 'auto' = 'auto';
+  let skipCache = false;
+  let cacheCommand: 'clear' | 'stats' | undefined;
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--root' && i + 1 < args.length) {
+      root = args[i + 1];
+      i++;
+    } else if (arg === '--question' && i + 1 < args.length) {
+      question = args[i + 1];
+      i++;
+    } else if (arg === '--limit' && i + 1 < args.length) {
+      limit = parseInt(args[i + 1], 10);
+      if (isNaN(limit) || limit < 1) {
+        console.error('Error: --limit must be a positive number');
+        return null;
+      }
+      limitProvided = true;
+      i++;
+    } else if (arg === '--with-mapping') {
+      generateMapping = true;
+    } else if (arg === '--mapping-output' && i + 1 < args.length) {
+      mappingOutputPath = args[i + 1];
+      generateMapping = true; // Implies mapping generation
+      i++;
+    } else if (arg === '--modules' && i + 1 < args.length) {
+      moduleKeys = args[i + 1].split(',').map(k => k.trim());
+      i++;
+    } else if (arg === '--lang' && i + 1 < args.length) {
+      const langArg = args[i + 1].toLowerCase();
+      if (langArg !== 'typescript' && langArg !== 'javascript' && langArg !== 'python' && langArg !== 'auto') {
+        console.error('Error: --lang must be one of: typescript, javascript, python, auto');
+        return null;
+      }
+      lang = langArg as CliArgs['lang'];
+      i++;
+    } else if (arg === '--skip-cache') {
+      skipCache = true;
+    } else if (arg === '--cache-clear') {
+      cacheCommand = 'clear';
+    } else if (arg === '--cache-stats') {
+      cacheCommand = 'stats';
+    } else if (arg === '--help' || arg === '-h') {
+      printHelp();
+      return null;
+    } else {
+      console.error(`Unknown argument: ${arg}`);
+      printHelp();
+      return null;
+    }
+  }
+
+  // Handle cache commands
+  if (cacheCommand) {
+    return { root, question: '', limit, limitProvided, generateMapping, moduleKeys, lang, cacheCommand };
+  }
+
+  if (!question) {
+    console.error('Error: --question is required (or use --cache-* for cache management)\n');
+    printHelp();
+    return null;
+  }
+
+  return { root, question, limit, limitProvided, generateMapping, mappingOutputPath, moduleKeys, lang, skipCache };
+}
+
+/**
+ * Print help message
+ */
+function printHelp(): void {
+  console.log(`
+uca - Universal Code Analyzer
+
+Usage:
+  uca --question "<text>" [options]
+  uca --cache-clear    # Clear all caches
+  uca --cache-stats    # Show cache statistics
+
+Options:
+  --root <path>            Project root directory (default: current directory)
+  --question "<text>"      Natural language question about the codebase (required)
+  --limit <number>         Number of top files to analyze (default: 10)
+  --with-mapping           Generate symbol mapping for on-demand retrieval
+  --modules <keys>         Comma-separated module keys (auto-discovered when omitted)
+  --lang <mode>            typescript | javascript | python | auto (default: auto)
+  --mapping-output <path>  Custom path for mapping file (implies --with-mapping)
+  --skip-cache             Skip cache and force full analysis
+  --cache-clear            Clear all cached analysis results
+  --cache-stats            Show cache statistics (hits, misses, size)
+  --help, -h               Show this help message
+
+Example:
+  uca --question "authentication logic" --limit 5
+  uca --root ./my-project --question "database models"
+  uca --question "API endpoints" --with-mapping
+  uca --question "permissions" --modules auth,middleware --skip-cache
+  uca --question "class structure" --lang python
+  uca --cache-stats
+  uca --cache-clear
+
+Output:
+  JSON object with ranked files and their code skeletons
+  `);
+}
+
+/**
+ * Main CLI function
+ */
+async function main(): Promise<void> {
+  const args = parseArgs();
+
+  if (!args) {
+    process.exit(1);
+  }
+
+  try {
+    // Handle cache commands
+    if (args.cacheCommand === 'clear') {
+      const cacheManager = getCacheManager();
+      cacheManager.clear();
+      console.log('✅ Cache cleared successfully');
+      process.exit(0);
+    }
+
+    if (args.cacheCommand === 'stats') {
+      const cacheManager = getCacheManager();
+      const stats = cacheManager.getStats();
+      console.log('\n📊 Cache Statistics:');
+      console.log(`   Hits: ${stats.hits}`);
+      console.log(`   Misses: ${stats.misses}`);
+      console.log(`   Hit Rate: ${stats.hitRate}%`);
+      console.log(`   Cache Size: ${(stats.cacheSize / 1024).toFixed(2)} KB`);
+      console.log(`   Cache Dir: ${cacheManager.getCacheDir()}\n`);
+      process.exit(0);
+    }
+
+    const absoluteRoot = path.resolve(args.root);
+    const config = loadConfig(absoluteRoot);
+    const moduleKeys =
+      args.moduleKeys
+      ?? (config.modules ? Object.keys(config.modules) : discoverModules(absoluteRoot));
+
+    const resolvedLimit = args.limitProvided ? args.limit : (config.defaultLimit ?? args.limit);
+    const langExtensions = resolveExtensionsForLanguage(args.lang);
+    const extensions = langExtensions ?? config.extensions;
+
+    const result = await analyzeProject({
+      root: absoluteRoot,
+      question: args.question,
+      limit: resolvedLimit,
+      generateMapping: args.generateMapping,
+      mappingOutputPath: args.mappingOutputPath,
+      moduleKeys,
+      moduleDefinitions: config.modules,
+      lang: args.lang,
+      skipCache: args.skipCache,
+      exclude: config.exclude,
+      extensions,
+    });
+    console.log(JSON.stringify(result, null, 2));
+  } catch (error) {
+    console.error('Error analyzing project:', error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+}
+
+// Run CLI
+main().catch((error) => {
+  console.error('Unexpected error:', error);
+  process.exit(1);
+});
+
+function resolveExtensionsForLanguage(lang: CliArgs['lang']): string[] | undefined {
+  switch (lang) {
+    case 'typescript':
+    case 'javascript':
+      return ['.ts', '.tsx', '.js', '.jsx'];
+    case 'python':
+      return ['.py', '.pyi'];
+    case 'auto':
+    default:
+      return undefined;
+  }
+}

package/src/config.ts

@@ -0,0 +1,22 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface AnalyzerConfig {
+  modules?: Record<string, string[]>;
+  exclude?: string[];
+  extensions?: string[];
+  defaultLimit?: number;
+}
+
+export function loadConfig(root: string): AnalyzerConfig {
+  const configPath = path.join(root, 'code-analyzer.config.json');
+  if (fs.existsSync(configPath)) {
+    try {
+      const raw = fs.readFileSync(configPath, 'utf-8');
+      return JSON.parse(raw) as AnalyzerConfig;
+    } catch {
+      console.warn('[config] Failed to parse code-analyzer.config.json, using defaults');
+    }
+  }
+  return {};
+}

package/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * Main library exports for skannr
+ */
+
+import * as path from 'path';
+import { discoverModules, readFileContent, scanFiles, scanRocketChatFiles, scanTypeScriptFiles } from './scanner';
+import { rankFiles } from './ranker';
+import { rankFilesEnhanced } from './ranker-enhanced';
+import { buildSkeletonForFile } from './skeletonizer';
+import { countTokens } from './tokenizer';
+import {
+  buildSkeletonWithMapping,
+  saveMappingToFile,
+  type SymbolMapping,
+} from './mapper';
+import {
+  AnalyzeOptions,
+  AnalysisResult,
+  FileAnalysis,
+} from './types';
+import { getCacheManager, type CacheConfig } from './cache';
+import { detectRepoLanguages, getAdapter } from './languages/registry';
+
+export async function analyzeProject(
+  options?: AnalyzeOptions & {
+    skipCache?: boolean;
+    cacheConfig?: Partial<CacheConfig>;
+  }
+): Promise<AnalysisResult> {
+  if (!options) {
+    throw new Error('Options are required (must include root and question)');
+  }
+
+  const {
+    root,
+    question,
+    limit = 10,
+    generateMapping = false,
+    mappingOutputPath,
+    enhancedRanking = false,
+    moduleKeys,
+    moduleDefinitions,
+    exclude,
+    extensions,
+    lang = 'auto',
+    skipCache = false,
+    cacheConfig,
+  } = options;
+
+  const absoluteRoot = path.resolve(root);
+  const effectiveModuleKeys =
+    moduleKeys && moduleKeys.length > 0 ? moduleKeys : discoverModules(absoluteRoot);
+  const effectiveExtensions = resolveExtensions(absoluteRoot, lang, extensions);
+
+  const allFiles = scanFiles(absoluteRoot, {
+    extensions: effectiveExtensions,
+    exclude,
+    moduleKeys: effectiveModuleKeys,
+    moduleDefinitions,
+  });
+
+  if (allFiles.length === 0) {
+    return {
+      question,
+      root: absoluteRoot,
+      limit,
+      files: [],
+    };
+  }
+
+  const cacheManager = cacheConfig ? getCacheManager() : getCacheManager();
+  if (cacheConfig) {
+    // cache manager behavior intentionally unchanged
+  }
+
+  if (!skipCache) {
+    const cachedResult = cacheManager.get(
+      absoluteRoot,
+      question,
+      allFiles,
+      effectiveModuleKeys,
+      enhancedRanking,
+      limit
+    );
+    if (cachedResult) {
+      console.log('📦 Cache hit! Using cached analysis result');
+      return cachedResult;
+    }
+  }
+
+  const rankedFiles = enhancedRanking
+    ? rankFilesEnhanced(allFiles, question, limit, absoluteRoot)
+    : rankFiles(allFiles, question, limit);
+
+  const fileAnalyses: FileAnalysis[] = [];
+  const symbolMapping: SymbolMapping = {
+    generatedAt: new Date().toISOString(),
+    rootPath: absoluteRoot,
+    files: {},
+  };
+
+  for (const rankedFile of rankedFiles) {
+    const originalContent = readFileContent(rankedFile.path);
+    if (!originalContent) {
+      continue;
+    }
+
+    const relativePath = path.relative(absoluteRoot, rankedFile.path);
+    const adapter = getAdapter(rankedFile.path);
+
+    let skeleton: string;
+    if (generateMapping && adapter.name === 'typescript') {
+      const mappingResult = buildSkeletonWithMapping(rankedFile.path, absoluteRoot);
+      skeleton = mappingResult.skeleton;
+      if (mappingResult.symbols.length > 0) {
+        symbolMapping.files[relativePath] = {
+          originalPath: rankedFile.path,
+          symbols: mappingResult.symbols,
+        };
+      }
+    } else {
+      skeleton = buildSkeletonForFile(rankedFile.path);
+    }
+
+    fileAnalyses.push({
+      path: relativePath,
+      score: rankedFile.score,
+      skeleton,
+      originalTokenCount: countTokens(originalContent),
+      skeletonTokenCount: countTokens(skeleton),
+    });
+  }
+
+  const result: AnalysisResult = {
+    question,
+    root: absoluteRoot,
+    limit,
+    files: fileAnalyses,
+  };
+
+  if (!skipCache) {
+    cacheManager.set(
+      absoluteRoot,
+      question,
+      allFiles,
+      result,
+      effectiveModuleKeys,
+      enhancedRanking,
+      limit
+    );
+  }
+
+  if (generateMapping && Object.keys(symbolMapping.files).length > 0) {
+    const mappingPath = mappingOutputPath || path.join(absoluteRoot, 'code-analyzer.mapping.json');
+    saveMappingToFile(symbolMapping, mappingPath);
+    console.log(`Symbol mapping saved to: ${mappingPath}`);
+  }
+
+  return result;
+}
+
+function resolveExtensions(
+  root: string,
+  lang: AnalyzeOptions['lang'],
+  explicit?: string[]
+): string[] | undefined {
+  if (explicit && explicit.length > 0) {
+    return explicit.map((ext) => ext.toLowerCase());
+  }
+
+  if (lang === 'typescript' || lang === 'javascript') {
+    return ['.ts', '.tsx', '.js', '.jsx'];
+  }
+
+  if (lang === 'python') {
+    return ['.py', '.pyi'];
+  }
+
+  if (lang === 'auto') {
+    detectRepoLanguages(root);
+    return undefined;
+  }
+
+  return undefined;
+}
+
+export { rankFiles } from './ranker';
+export { rankFilesEnhanced } from './ranker-enhanced';
+export { buildSkeletonForFile } from './skeletonizer';
+export { scanTypeScriptFiles, scanRocketChatFiles, scanFiles, discoverModules } from './scanner';
+export { countTokens } from './tokenizer';
+export {
+  buildSkeletonWithMapping,
+  getSymbolDetails,
+  saveMappingToFile,
+  loadMappingFromFile,
+  type SymbolMapping,
+  type SymbolLocation,
+} from './mapper';
+
+export type {
+  AnalyzeOptions,
+  AnalysisResult,
+  FileAnalysis,
+  RankedFile,
+} from './types';
+
+export {
+  CacheManager,
+  getCacheManager,
+  initializeCacheManager,
+  DEFAULT_CACHE_CONFIG,
+  type CacheConfig,
+  type CacheEntry,
+} from './cache';

package/src/languages/GenericAdapter.ts

@@ -0,0 +1,44 @@
+import { LanguageAdapter, Symbol } from './LanguageAdapter';
+
+export class GenericAdapter implements LanguageAdapter {
+  name = 'generic';
+  extensions: string[] = [];
+
+  canHandle(): boolean {
+    return true;
+  }
+
+  generateSkeleton(content: string): string {
+    return content.split('\n').slice(0, 50).join('\n');
+  }
+
+  extractSymbols(content: string): Symbol[] {
+    const symbols: Symbol[] = [];
+    const lines = content.split('\n');
+    const seen = new Set<string>();
+
+    lines.forEach((line, idx) => {
+      const matches = line.match(/\b([A-Z][A-Za-z0-9]+|[a-z]+_[a-z0-9_]+)\b/g) || [];
+      for (const match of matches) {
+        if (seen.has(match)) {
+          continue;
+        }
+        seen.add(match);
+        symbols.push({
+          name: match,
+          kind: 'variable',
+          line: idx + 1,
+        });
+      }
+    });
+
+    return symbols;
+  }
+
+  extractImports(content: string): string[] {
+    const lines = content.split('\n').slice(0, 100);
+    return lines
+      .filter((line) => /^\s*(import|from|#include)\b/.test(line))
+      .map((line) => line.trim());
+  }
+}

package/src/languages/LanguageAdapter.ts

@@ -0,0 +1,14 @@
+export interface Symbol {
+  name: string;
+  kind: 'function' | 'class' | 'interface' | 'type' | 'variable' | 'export';
+  line: number;
+}
+
+export interface LanguageAdapter {
+  name: string;
+  extensions: string[];
+  canHandle(filePath: string): boolean;
+  generateSkeleton(content: string, filePath: string): string;
+  extractSymbols(content: string): Symbol[];
+  extractImports(content: string): string[];
+}

package/src/languages/PythonAdapter.ts

@@ -0,0 +1,74 @@
+import * as path from 'path';
+import { LanguageAdapter, Symbol } from './LanguageAdapter';
+
+export class PythonAdapter implements LanguageAdapter {
+  name = 'python';
+  extensions = ['.py', '.pyi'];
+
+  canHandle(filePath: string): boolean {
+    return this.extensions.includes(path.extname(filePath).toLowerCase());
+  }
+
+  generateSkeleton(content: string): string {
+    const lines = content.split('\n');
+    const output: string[] = [];
+    const keepers = /^(?:\s*(?:@[\w.]+(?:\([^)]*\))?|(?:async\s+)?def\s+[\w_]+\s*\(.*\)\s*(?:->\s*[^:]+)?\s*:|class\s+[\w_]+(?:\([^)]*\))?\s*:|(?:from\s+\S+\s+import\s+.+)|(?:import\s+.+)|[A-Za-z_]\w*\s*=.+))/;
+
+    for (const line of lines) {
+      if (!keepers.test(line)) {
+        continue;
+      }
+
+      if (/^\s*(?:async\s+)?def\s+/.test(line)) {
+        const indent = line.match(/^(\s*)/)?.[1] ?? '';
+        output.push(line);
+        output.push(`${indent}    ...`);
+        continue;
+      }
+
+      output.push(line);
+    }
+
+    return output.join('\n').trim();
+  }
+
+  extractSymbols(content: string): Symbol[] {
+    const lines = content.split('\n');
+    const symbols: Symbol[] = [];
+
+    lines.forEach((line, idx) => {
+      const classMatch = line.match(/^\s*class\s+([A-Za-z_]\w*)/);
+      if (classMatch) {
+        symbols.push({ name: classMatch[1], kind: 'class', line: idx + 1 });
+      }
+
+      const functionMatch = line.match(/^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)/);
+      if (functionMatch) {
+        symbols.push({ name: functionMatch[1], kind: 'function', line: idx + 1 });
+      }
+
+      const variableMatch = line.match(/^([A-Za-z_]\w*)\s*=/);
+      if (variableMatch) {
+        symbols.push({ name: variableMatch[1], kind: 'variable', line: idx + 1 });
+      }
+    });
+
+    return symbols;
+  }
+
+  extractImports(content: string): string[] {
+    const imports: string[] = [];
+    const lines = content.split('\n');
+    for (const line of lines) {
+      const fromMatch = line.match(/^\s*from\s+([A-Za-z0-9_.]+)\s+import\s+/);
+      if (fromMatch) {
+        imports.push(fromMatch[1]);
+      }
+      const importMatch = line.match(/^\s*import\s+(.+)/);
+      if (importMatch) {
+        imports.push(importMatch[1].split(',')[0].trim());
+      }
+    }
+    return imports;
+  }
+}