@metabob/minibob 0.1.2

package/src/understanding/explorer.ts

@@ -0,0 +1,488 @@
+/**
+ * CodeExplorer - Fast static analysis of codebase structure
+ *
+ * Uses Bun file APIs to analyze code without LLM calls.
+ * Provides foundation for semantic understanding.
+ */
+
+import type {
+  CodeStructure,
+  DirectoryNode,
+  Dependencies,
+  FileAnalysis,
+  Import,
+  Export,
+  FunctionDeclaration,
+  Component
+} from './types'
+
+export class CodeExplorer {
+  private ignorePatterns: string[] = [
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '.next',
+    '.cache',
+    'coverage',
+    '.DS_Store',
+    '*.log',
+    '.env',
+    '.env.local',
+    'bun.lockb',
+    'package-lock.json',
+    'yarn.lock'
+  ]
+
+  constructor(
+    private workingDir: string = process.cwd(),
+    additionalIgnore?: string[]
+  ) {
+    if (additionalIgnore) {
+      this.ignorePatterns.push(...additionalIgnore)
+    }
+  }
+
+  /**
+   * Safe wrapper for Bun.file() with better error handling
+   */
+  private safeReadFile(path: string): ReturnType<typeof Bun.file> {
+    if (!path || typeof path !== 'string') {
+      throw new Error(`Invalid file path: expected string, got ${typeof path}`)
+    }
+    try {
+      return Bun.file(path)
+    } catch (error) {
+      throw new Error(`Failed to create file handle for '${path}': ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+
+  /**
+   * Explore codebase and return comprehensive structure
+   */
+  async explore(rootPath: string): Promise<CodeStructure> {
+    const absolutePath = this.resolvePath(rootPath)
+    const files = await this.listAllFiles(absolutePath)
+
+    const filesByType = this.groupByExtension(files)
+    const dependencies = await this.extractDependencies(absolutePath, files)
+    const entryPoints = await this.findEntryPoints(absolutePath, files)
+    const { totalSize, totalLoc } = await this.calculateCodebaseSize(absolutePath, files)
+    const directoryStructure = await this.analyzeDirectoryStructure(absolutePath)
+
+    return {
+      totalFiles: files.length,
+      filesByType,
+      directoryStructure,
+      dependencies,
+      entryPoints,
+      totalSize,
+      totalLoc
+    }
+  }
+
+  /**
+   * Analyze specific file in detail
+   */
+  async analyzeFile(filePath: string): Promise<FileAnalysis> {
+    const absolutePath = this.resolvePath(filePath)
+    const bunFile = this.safeReadFile(absolutePath)
+    const content = await bunFile.text()
+    const size = await bunFile.size
+
+    return {
+      path: filePath,
+      imports: this.extractImports(content),
+      exports: this.extractExports(content),
+      functions: this.extractFunctions(content),
+      components: this.extractReactComponents(content),
+      loc: content.split('\n').length,
+      size
+    }
+  }
+
+  /**
+   * List all files in directory (non-ignored)
+   */
+  private async listAllFiles(rootPath: string): Promise<string[]> {
+    const glob = new Bun.Glob("**/*")
+    const files: string[] = []
+
+    for await (const file of glob.scan({ cwd: rootPath })) {
+      if (!this.shouldIgnore(file)) {
+        files.push(file)
+      }
+    }
+
+    return files
+  }
+
+  /**
+   * Check if file should be ignored
+   */
+  private shouldIgnore(path: string): boolean {
+    return this.ignorePatterns.some(pattern => {
+      // Simple pattern matching (could be enhanced with minimatch)
+      if (pattern.includes('*')) {
+        const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$')
+        return regex.test(path)
+      }
+      return path.includes(pattern)
+    })
+  }
+
+  /**
+   * Group files by extension
+   */
+  private groupByExtension(files: string[]): Record<string, number> {
+    const groups: Record<string, number> = {}
+
+    for (const file of files) {
+      const ext = file.split('.').pop() || 'unknown'
+      groups[ext] = (groups[ext] || 0) + 1
+    }
+
+    return groups
+  }
+
+  /**
+   * Extract dependencies from package.json files
+   */
+  private async extractDependencies(rootPath: string, files: string[]): Promise<Dependencies> {
+    const packageJsons = files.filter(f => f === 'package.json' || f.endsWith('/package.json'))
+    const dependencies: Dependencies = {
+      runtime: {},
+      dev: {},
+      frameworks: [],
+      internal: []
+    }
+
+    for (const pkgPath of packageJsons) {
+      try {
+        const content = await this.safeReadFile(`${rootPath}/${pkgPath}`).text()
+        const pkg = JSON.parse(content)
+
+        // Extract runtime dependencies
+        if (pkg.dependencies) {
+          Object.assign(dependencies.runtime, pkg.dependencies)
+        }
+
+        // Extract dev dependencies
+        if (pkg.devDependencies) {
+          Object.assign(dependencies.dev, pkg.devDependencies)
+        }
+
+        // Identify common frameworks
+        if (pkg.dependencies?.['react'] || pkg.devDependencies?.['react']) {
+          dependencies.frameworks.push('React')
+        }
+        if (pkg.dependencies?.['@hono/hono'] || pkg.dependencies?.['hono']) {
+          dependencies.frameworks.push('Hono')
+        }
+        if (pkg.dependencies?.['express']) {
+          dependencies.frameworks.push('Express')
+        }
+        if (pkg.dependencies?.['next']) {
+          dependencies.frameworks.push('Next.js')
+        }
+      } catch (error) {
+        // Ignore malformed package.json
+        console.warn(`Could not parse ${pkgPath}:`, error)
+      }
+    }
+
+    // Deduplicate frameworks
+    dependencies.frameworks = Array.from(new Set(dependencies.frameworks))
+
+    return dependencies
+  }
+
+  /**
+   * Find application entry points
+   */
+  private async findEntryPoints(rootPath: string, files: string[]): Promise<string[]> {
+    const entryPoints: string[] = []
+    const candidates = [
+      'index.ts',
+      'index.js',
+      'index.tsx',
+      'index.jsx',
+      'main.ts',
+      'main.js',
+      'app.ts',
+      'app.js',
+      'server.ts',
+      'server.js',
+      'cli.ts',
+      'cli.js'
+    ]
+
+    for (const candidate of candidates) {
+      // Check root level
+      if (files.includes(candidate)) {
+        entryPoints.push(candidate)
+      }
+
+      // Check src/ directory
+      if (files.includes(`src/${candidate}`)) {
+        entryPoints.push(`src/${candidate}`)
+      }
+    }
+
+    // Also check package.json for main/bin entries
+    if (files.includes('package.json')) {
+      try {
+        const content = await this.safeReadFile(`${rootPath}/package.json`).text()
+        const pkg = JSON.parse(content)
+
+        if (pkg.main && !entryPoints.includes(pkg.main)) {
+          entryPoints.push(pkg.main)
+        }
+
+        if (pkg.bin) {
+          const binEntries = typeof pkg.bin === 'string' ? [pkg.bin] : Object.values(pkg.bin)
+          for (const binEntry of binEntries) {
+            if (typeof binEntry === 'string' && !entryPoints.includes(binEntry)) {
+              entryPoints.push(binEntry)
+            }
+          }
+        }
+      } catch (error) {
+        // Ignore
+      }
+    }
+
+    return entryPoints
+  }
+
+  /**
+   * Calculate total size and lines of code
+   */
+  private async calculateCodebaseSize(rootPath: string, files: string[]): Promise<{
+    totalSize: number
+    totalLoc: number
+  }> {
+    let totalSize = 0
+    let totalLoc = 0
+
+    const codeExtensions = ['ts', 'tsx', 'js', 'jsx', 'py', 'go', 'rs', 'java', 'c', 'cpp', 'h']
+
+    for (const file of files) {
+      const ext = file.split('.').pop()
+      if (ext && codeExtensions.includes(ext)) {
+        try {
+          const filePath = `${rootPath}/${file}`
+          const bunFile = this.safeReadFile(filePath)
+          totalSize += await bunFile.size
+          const content = await bunFile.text()
+          totalLoc += content.split('\n').length
+        } catch (error) {
+          // Skip files we can't read
+        }
+      }
+    }
+
+    return { totalSize, totalLoc }
+  }
+
+  /**
+   * Build directory structure tree
+   */
+  private async analyzeDirectoryStructure(rootPath: string): Promise<DirectoryNode> {
+    const files = await this.listAllFiles(rootPath)
+
+    const root: DirectoryNode = {
+      name: rootPath.split('/').pop() || 'root',
+      path: '',
+      type: 'directory',
+      children: []
+    }
+
+    for (const file of files) {
+      const parts = file.split('/')
+      let currentNode = root
+
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i]
+        const isFile = i === parts.length - 1
+
+        if (!currentNode.children) {
+          currentNode.children = []
+        }
+
+        let child = currentNode.children.find(c => c.name === part)
+
+        if (!child) {
+          child = {
+            name: part,
+            path: parts.slice(0, i + 1).join('/'),
+            type: isFile ? 'file' : 'directory',
+            children: isFile ? undefined : []
+          }
+
+          if (isFile) {
+            child.extension = part.split('.').pop()
+          }
+
+          currentNode.children.push(child)
+        }
+
+        currentNode = child
+      }
+    }
+
+    return root
+  }
+
+  /**
+   * Extract imports from file content
+   */
+  private extractImports(content: string): Import[] {
+    const imports: Import[] = []
+
+    // ES6 imports: import { a, b } from 'module'
+    const es6ImportRegex = /import\s+(?:{([^}]+)}|(\w+))\s+from\s+['"]([^'"]+)['"]/g
+    let match
+
+    while ((match = es6ImportRegex.exec(content)) !== null) {
+      imports.push({
+        named: match[1]?.split(',').map(s => s.trim()).filter(Boolean) || [],
+        default: match[2] || undefined,
+        source: match[3]
+      })
+    }
+
+    // CommonJS require: const x = require('module')
+    const requireRegex = /(?:const|let|var)\s+(?:{([^}]+)}|(\w+))\s*=\s*require\(['"]([^'"]+)['"]\)/g
+
+    while ((match = requireRegex.exec(content)) !== null) {
+      imports.push({
+        named: match[1]?.split(',').map(s => s.trim()).filter(Boolean) || [],
+        default: match[2] || undefined,
+        source: match[3]
+      })
+    }
+
+    return imports
+  }
+
+  /**
+   * Extract exports from file content
+   */
+  private extractExports(content: string): Export[] {
+    const exports: Export[] = []
+
+    // export function name()
+    const exportFunctionRegex = /export\s+(?:async\s+)?function\s+(\w+)/g
+    let match
+
+    while ((match = exportFunctionRegex.exec(content)) !== null) {
+      exports.push({
+        name: match[1],
+        type: 'function'
+      })
+    }
+
+    // export class Name
+    const exportClassRegex = /export\s+class\s+(\w+)/g
+
+    while ((match = exportClassRegex.exec(content)) !== null) {
+      exports.push({
+        name: match[1],
+        type: 'class'
+      })
+    }
+
+    // export const name
+    const exportConstRegex = /export\s+const\s+(\w+)/g
+
+    while ((match = exportConstRegex.exec(content)) !== null) {
+      exports.push({
+        name: match[1],
+        type: 'const'
+      })
+    }
+
+    // export default
+    if (content.includes('export default')) {
+      exports.push({
+        name: 'default',
+        type: 'default'
+      })
+    }
+
+    return exports
+  }
+
+  /**
+   * Extract function declarations
+   */
+  private extractFunctions(content: string): FunctionDeclaration[] {
+    const functions: FunctionDeclaration[] = []
+
+    // function name(params)
+    const functionRegex = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/g
+    let match
+
+    while ((match = functionRegex.exec(content)) !== null) {
+      functions.push({
+        name: match[1],
+        isAsync: content.substring(match.index, match.index + 20).includes('async'),
+        parameters: match[2].split(',').map(s => s.trim()).filter(Boolean)
+      })
+    }
+
+    // const name = function(params) or const name = (params) =>
+    const arrowFunctionRegex = /const\s+(\w+)\s*=\s*(?:async\s+)?\(?([^)]*)\)?\s*=>/g
+
+    while ((match = arrowFunctionRegex.exec(content)) !== null) {
+      functions.push({
+        name: match[1],
+        isAsync: content.substring(match.index, match.index + 30).includes('async'),
+        parameters: match[2].split(',').map(s => s.trim()).filter(Boolean)
+      })
+    }
+
+    return functions
+  }
+
+  /**
+   * Extract React components
+   */
+  private extractReactComponents(content: string): Component[] {
+    const components: Component[] = []
+
+    // Functional components: function Name() or const Name = () =>
+    const functionalRegex = /(?:export\s+)?(?:function|const)\s+([A-Z]\w+)\s*[=:()].*(?:React\.FC|=>|:.*JSX\.Element)/g
+    let match
+
+    while ((match = functionalRegex.exec(content)) !== null) {
+      components.push({
+        name: match[1],
+        type: 'functional'
+      })
+    }
+
+    // Class components: class Name extends React.Component
+    const classRegex = /class\s+([A-Z]\w+)\s+extends\s+(?:React\.)?(?:Component|PureComponent)/g
+
+    while ((match = classRegex.exec(content)) !== null) {
+      components.push({
+        name: match[1],
+        type: 'class'
+      })
+    }
+
+    return components
+  }
+
+  /**
+   * Resolve path relative to working directory
+   */
+  private resolvePath(path: string): string {
+    if (path.startsWith('/')) {
+      return path
+    }
+    return `${this.workingDir}/${path}`.replace(/\/+/g, '/')
+  }
+}

package/src/understanding/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Understanding module exports
+ */
+
+export { CodeExplorer } from './explorer'
+export { ApplicationAnalyzer } from './analyzer'
+
+export type {
+  CodeStructure,
+  DirectoryNode,
+  Dependencies,
+  FileAnalysis,
+  Import,
+  Export,
+  FunctionDeclaration,
+  Component,
+  AnalyzeOptions,
+  Analysis,
+  ArchitectureAnalysis,
+  ComponentAnalysis,
+  DataFlowAnalysis,
+  EntryPointAnalysis,
+  DependencyAnalysis,
+  TechStackAnalysis,
+  Diagnosis,
+  Pattern
+} from './types'

package/src/understanding/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Type definitions for understanding capabilities
+ */
+
+export interface CodeStructure {
+  totalFiles: number
+  filesByType: Record<string, number>
+  directoryStructure: DirectoryNode
+  dependencies: Dependencies
+  entryPoints: string[]
+  totalSize: number
+  totalLoc: number
+}
+
+export interface DirectoryNode {
+  name: string
+  path: string
+  type: 'file' | 'directory'
+  children?: DirectoryNode[]
+  size?: number
+  extension?: string
+}
+
+export interface Dependencies {
+  runtime: Record<string, string>
+  dev: Record<string, string>
+  frameworks: string[]
+  internal: string[]
+}
+
+export interface FileAnalysis {
+  path: string
+  imports: Import[]
+  exports: Export[]
+  functions: FunctionDeclaration[]
+  components: Component[]
+  loc: number
+  size: number
+}
+
+export interface Import {
+  named: string[]
+  default?: string
+  source: string
+  line?: number
+}
+
+export interface Export {
+  name: string
+  type: 'function' | 'class' | 'const' | 'default'
+  line?: number
+}
+
+export interface FunctionDeclaration {
+  name: string
+  isAsync: boolean
+  parameters: string[]
+  line?: number
+}
+
+export interface Component {
+  name: string
+  type: 'functional' | 'class'
+  props?: string[]
+  line?: number
+}
+
+export interface AnalyzeOptions {
+  rootPath: string
+  focus?: 'architecture' | 'dependencies' | 'components' | 'all'
+  depth?: 'shallow' | 'medium' | 'deep'
+  ignorePatterns?: string[]
+}
+
+export interface Analysis {
+  architecture: ArchitectureAnalysis
+  components: ComponentAnalysis
+  dataFlow: DataFlowAnalysis
+  entryPoints: EntryPointAnalysis
+  dependencies: DependencyAnalysis
+  techStack: TechStackAnalysis
+}
+
+export interface ArchitectureAnalysis {
+  pattern: string
+  description: string
+  layers: string[]
+}
+
+export interface ComponentAnalysis {
+  summary: string
+  keyModules: Array<{
+    name: string
+    purpose: string
+    files: string[]
+  }>
+}
+
+export interface DataFlowAnalysis {
+  description: string
+  flows: Array<{
+    source: string
+    destination: string
+    dataType: string
+  }>
+}
+
+export interface EntryPointAnalysis {
+  main: string[]
+  server?: string
+  client?: string
+  cli?: string
+}
+
+export interface DependencyAnalysis {
+  external: Array<{
+    name: string
+    version: string
+    purpose: string
+  }>
+  internal: Array<{
+    module: string
+    dependsOn: string[]
+  }>
+}
+
+export interface TechStackAnalysis {
+  runtime: string
+  framework: string[]
+  language: string[]
+  tools: string[]
+}
+
+export interface Diagnosis {
+  symptoms: string[]
+  rootCause: string
+  affectedFiles: string[]
+  recommendedFix: string
+  validationSteps: string[]
+  confidence: 'low' | 'medium' | 'high'
+}
+
+export interface Pattern {
+  type: 'architecture' | 'design' | 'security' | 'performance'
+  name: string
+  description: string
+  instances: Array<{
+    file: string
+    line?: number
+    context?: string
+  }>
+  recommendation?: string
+}