prjct-cli 0.44.1 → 0.45.3

package/core/context-tools/index.ts

@@ -0,0 +1,433 @@
+/**
+ * Context Tools - Smart context filtering for AI agents
+ *
+ * Provides terminal tools that Claude can use to explore codebases
+ * efficiently WITHOUT consuming tokens for filtering.
+ *
+ * Tools:
+ * - files: Find relevant files for a task
+ * - signatures: Extract code structure without implementation
+ * - imports: Build dependency graphs
+ * - recent: Find hot files from git history
+ * - summary: Intelligent file summarization
+ *
+ * @module context-tools
+ * @version 1.0.0
+ */
+
+import { metricsStorage } from '../storage/metrics-storage'
+import { getTimestamp } from '../utils/date-helper'
+import { findRelevantFiles } from './files-tool'
+import { analyzeImports } from './imports-tool'
+import { getRecentFiles } from './recent-tool'
+import { extractDirectorySignatures, extractSignatures } from './signatures-tool'
+import { summarizeDirectory, summarizeFile } from './summary-tool'
+import { combineMetrics } from './token-counter'
+import type { ContextToolOutput, ContextToolUsage } from './types'
+
+// =============================================================================
+// CLI Dispatcher
+// =============================================================================
+
+/**
+ * Run a context tool from CLI arguments
+ *
+ * Usage:
+ *   prjct context files "add authentication"
+ *   prjct context signatures core/auth/service.ts
+ *   prjct context imports core/auth/service.ts --reverse
+ *   prjct context recent 50
+ *   prjct context recent --branch
+ *   prjct context summary core/auth/service.ts
+ *
+ * @param args - CLI arguments (tool name + args)
+ * @param projectId - Project ID for metrics tracking
+ * @param projectPath - Project root path
+ * @returns JSON output for Claude
+ */
+export async function runContextTool(
+  args: string[],
+  projectId: string,
+  projectPath: string
+): Promise<ContextToolOutput> {
+  const startTime = Date.now()
+  const [toolName, ...toolArgs] = args
+
+  try {
+    let result: ContextToolOutput
+
+    switch (toolName) {
+      case 'files':
+        result = await runFilesTool(toolArgs, projectPath)
+        break
+
+      case 'signatures':
+        result = await runSignaturesTool(toolArgs, projectPath)
+        break
+
+      case 'imports':
+        result = await runImportsTool(toolArgs, projectPath)
+        break
+
+      case 'recent':
+        result = await runRecentTool(toolArgs, projectPath)
+        break
+
+      case 'summary':
+        result = await runSummaryTool(toolArgs, projectPath)
+        break
+
+      case 'help':
+        return {
+          tool: 'error',
+          result: {
+            error: getHelpText(),
+            code: 'HELP',
+          },
+        }
+
+      default:
+        return {
+          tool: 'error',
+          result: {
+            error: `Unknown tool: ${toolName}. Use 'prjct context help' for usage.`,
+            code: 'UNKNOWN_TOOL',
+          },
+        }
+    }
+
+    // Record usage metrics
+    const duration = Date.now() - startTime
+    const tokensSaved = getTokensSaved(result)
+    const compressionRate = getCompressionRate(result)
+
+    await recordToolUsage(projectId, {
+      tool: toolName as ContextToolUsage['tool'],
+      timestamp: getTimestamp(),
+      inputArgs: toolArgs.join(' '),
+      tokensSaved,
+      compressionRate,
+      duration,
+    })
+
+    return result
+  } catch (error) {
+    return {
+      tool: 'error',
+      result: {
+        error: (error as Error).message,
+        code: 'EXECUTION_ERROR',
+      },
+    }
+  }
+}
+
+// =============================================================================
+// Tool Runners
+// =============================================================================
+
+async function runFilesTool(args: string[], projectPath: string): Promise<ContextToolOutput> {
+  // Parse options
+  const options: { maxFiles?: number; minScore?: number; includeTests?: boolean } = {}
+  const taskParts: string[] = []
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--max' && args[i + 1]) {
+      options.maxFiles = parseInt(args[++i], 10)
+    } else if (args[i] === '--min-score' && args[i + 1]) {
+      options.minScore = parseFloat(args[++i])
+    } else if (args[i] === '--include-tests') {
+      options.includeTests = true
+    } else {
+      taskParts.push(args[i])
+    }
+  }
+
+  const taskDescription = taskParts.join(' ')
+  if (!taskDescription) {
+    return {
+      tool: 'error',
+      result: {
+        error: 'Usage: prjct context files "<task description>"',
+        code: 'MISSING_ARG',
+      },
+    }
+  }
+
+  const result = await findRelevantFiles(taskDescription, projectPath, options)
+  return { tool: 'files', result }
+}
+
+async function runSignaturesTool(args: string[], projectPath: string): Promise<ContextToolOutput> {
+  const filePath = args[0]
+  if (!filePath) {
+    return {
+      tool: 'error',
+      result: {
+        error: 'Usage: prjct context signatures <file_or_directory>',
+        code: 'MISSING_ARG',
+      },
+    }
+  }
+
+  // Check if it's a directory
+  const fs = await import('node:fs/promises')
+  const path = await import('node:path')
+  const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectPath, filePath)
+
+  try {
+    const stat = await fs.stat(fullPath)
+    if (stat.isDirectory()) {
+      // Return multiple results
+      const results = await extractDirectorySignatures(filePath, projectPath, {
+        recursive: args.includes('--recursive') || args.includes('-r'),
+      })
+      // Combine into single output with cost savings
+      const combinedMetrics = combineMetrics(results.map((r) => r.metrics))
+      const combined = {
+        file: filePath,
+        language: 'multiple',
+        signatures: results.flatMap((r) => r.signatures.map((s) => ({ ...s, file: r.file }))),
+        fallback: false,
+        metrics: combinedMetrics,
+      }
+      return { tool: 'signatures', result: combined }
+    }
+  } catch {
+    // Not a directory, try as file
+  }
+
+  const result = await extractSignatures(filePath, projectPath)
+  return { tool: 'signatures', result }
+}
+
+async function runImportsTool(args: string[], projectPath: string): Promise<ContextToolOutput> {
+  const filePath = args[0]
+  if (!filePath) {
+    return {
+      tool: 'error',
+      result: {
+        error: 'Usage: prjct context imports <file> [--reverse] [--depth N]',
+        code: 'MISSING_ARG',
+      },
+    }
+  }
+
+  // Parse options
+  const options: { reverse?: boolean; depth?: number } = {}
+  for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--reverse' || args[i] === '-r') {
+      options.reverse = true
+    } else if ((args[i] === '--depth' || args[i] === '-d') && args[i + 1]) {
+      options.depth = parseInt(args[++i], 10)
+    }
+  }
+
+  const result = await analyzeImports(filePath, projectPath, options)
+  return { tool: 'imports', result }
+}
+
+async function runRecentTool(args: string[], projectPath: string): Promise<ContextToolOutput> {
+  const options: { commits?: number; branch?: boolean; maxFiles?: number } = {}
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--branch' || args[i] === '-b') {
+      options.branch = true
+    } else if (args[i] === '--max' && args[i + 1]) {
+      options.maxFiles = parseInt(args[++i], 10)
+    } else if (/^\d+$/.test(args[i])) {
+      options.commits = parseInt(args[i], 10)
+    }
+  }
+
+  const result = await getRecentFiles(projectPath, options)
+  return { tool: 'recent', result }
+}
+
+async function runSummaryTool(args: string[], projectPath: string): Promise<ContextToolOutput> {
+  const targetPath = args[0]
+  if (!targetPath) {
+    return {
+      tool: 'error',
+      result: {
+        error: 'Usage: prjct context summary <file_or_directory> [--recursive]',
+        code: 'MISSING_ARG',
+      },
+    }
+  }
+
+  // Check if it's a directory
+  const fs = await import('node:fs/promises')
+  const path = await import('node:path')
+  const fullPath = path.isAbsolute(targetPath) ? targetPath : path.join(projectPath, targetPath)
+
+  try {
+    const stat = await fs.stat(fullPath)
+    if (stat.isDirectory()) {
+      const results = await summarizeDirectory(targetPath, projectPath, {
+        recursive: args.includes('--recursive') || args.includes('-r'),
+      })
+      // Combine into aggregate output
+      const combined = {
+        file: targetPath,
+        purpose: `Directory with ${results.length} files`,
+        publicAPI: results.flatMap((r) => r.publicAPI.map((api) => ({ ...api, file: r.file }))),
+        dependencies: [...new Set(results.flatMap((r) => r.dependencies))],
+        metrics: combineMetrics(results.map((r) => r.metrics)),
+      }
+      return { tool: 'summary', result: combined }
+    }
+  } catch {
+    // Not a directory, try as file
+  }
+
+  const result = await summarizeFile(targetPath, projectPath)
+  return { tool: 'summary', result }
+}
+
+// =============================================================================
+// Metrics Helpers
+// =============================================================================
+
+function getTokensSaved(result: ContextToolOutput): number {
+  if (result.tool === 'error') return 0
+
+  switch (result.tool) {
+    case 'signatures':
+    case 'summary':
+      return result.result.metrics.tokens.saved
+    case 'files':
+      // Estimate tokens saved by returning fewer files
+      return result.result.metrics.filesScanned * 50 - result.result.metrics.filesReturned * 50
+    case 'imports':
+      // Estimate based on not needing to read full files
+      return result.result.metrics.totalImports * 20
+    case 'recent':
+      // Estimate based on focused file list
+      return result.result.metrics.totalFilesChanged * 30
+    default:
+      return 0
+  }
+}
+
+function getCompressionRate(result: ContextToolOutput): number {
+  if (result.tool === 'error') return 0
+
+  switch (result.tool) {
+    case 'signatures':
+    case 'summary':
+      return result.result.metrics.compression
+    case 'files': {
+      const scanned = result.result.metrics.filesScanned
+      const returned = result.result.metrics.filesReturned
+      return scanned > 0 ? (scanned - returned) / scanned : 0
+    }
+    default:
+      return 0
+  }
+}
+
+async function recordToolUsage(projectId: string, usage: ContextToolUsage): Promise<void> {
+  try {
+    // Record to metrics storage
+    await metricsStorage.recordSync(projectId, {
+      originalSize: usage.tokensSaved + 100, // Estimate original
+      filteredSize: 100, // Estimate filtered
+      duration: usage.duration,
+      isWatch: false,
+      agents: [`context-${usage.tool}`],
+    })
+  } catch {
+    // Metrics recording failure is non-fatal
+  }
+}
+
+// =============================================================================
+// Help Text
+// =============================================================================
+
+function getHelpText(): string {
+  return `
+Context Tools - Smart context filtering for AI agents
+
+USAGE:
+  prjct context <tool> [args] [options]
+
+TOOLS:
+
+  files <task>
+    Find files relevant to a task description.
+    Options:
+      --max N           Maximum files to return (default: 30)
+      --min-score N     Minimum relevance score 0-1 (default: 0.1)
+      --include-tests   Include test files
+
+    Example:
+      prjct context files "add user authentication"
+
+  signatures <path>
+    Extract code structure without implementation (~90% compression).
+    Path can be a file or directory.
+    Options:
+      --recursive, -r   Process directories recursively
+
+    Example:
+      prjct context signatures core/auth/service.ts
+      prjct context signatures core/auth/ --recursive
+
+  imports <file>
+    Analyze import/dependency relationships.
+    Options:
+      --reverse, -r     Show files that import this file
+      --depth N, -d N   Build dependency tree to depth N
+
+    Example:
+      prjct context imports core/auth/service.ts --reverse
+      prjct context imports core/auth/service.ts --depth 2
+
+  recent [commits]
+    Find recently modified "hot" files.
+    Options:
+      --branch, -b      Only files changed in current branch vs main
+      --max N           Maximum files to return (default: 50)
+
+    Example:
+      prjct context recent
+      prjct context recent 50
+      prjct context recent --branch
+
+  summary <path>
+    Generate intelligent file summary (public API + docs).
+    Options:
+      --recursive, -r   Process directories recursively
+
+    Example:
+      prjct context summary core/auth/service.ts
+      prjct context summary core/services/ --recursive
+
+OUTPUT:
+  All tools output JSON for easy parsing by AI agents.
+  Each output includes metrics showing token savings.
+`.trim()
+}
+
+// =============================================================================
+// Exports
+// =============================================================================
+
+export {
+  // Individual tools for programmatic use
+  findRelevantFiles,
+  extractSignatures,
+  extractDirectorySignatures,
+  analyzeImports,
+  getRecentFiles,
+  summarizeFile,
+  summarizeDirectory,
+}
+
+// Note: runContextTool is already exported at its definition (line 48)
+
+export * from './token-counter'
+// Re-export types
+export * from './types'