@metabob/minibob 0.1.2

package/src/runtime-mapping.ts

@@ -0,0 +1,527 @@
+/**
+ * Runtime Mapping
+ *
+ * Maps runtime behavior (traces) to source code (instructions) to intent (purpose).
+ *
+ * The Three Ideograms:
+ * - VESSEL (Instructional State): Source code, activity templates
+ * - BECOMING (Transient State): Execution traces, function calls
+ * - INSTANCE (Functional State): Running process, outcomes
+ *
+ * This module bridges these states by:
+ * 1. Capturing runtime traces (what happens)
+ * 2. Locating source code (what the code says)
+ * 3. Inferring intent (why the code exists)
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs'
+import { join, relative, extname } from 'path'
+import type { SourceLocation, InferredIntent } from './vessel-registry'
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface TraceToSourceMapping {
+  /** The trace activity ID */
+  traceId: string
+  /** Function/method that was called */
+  functionName: string
+  /** Source location if found */
+  sourceLocation?: SourceLocation
+  /** Inferred intent */
+  intent?: InferredIntent
+  /** Confidence in the mapping */
+  confidence: number
+}
+
+export interface CodebaseAnalysis {
+  /** Root path of the codebase */
+  rootPath: string
+  /** All functions/methods found */
+  functions: FunctionInfo[]
+  /** All classes found */
+  classes: ClassInfo[]
+  /** Module structure */
+  modules: ModuleInfo[]
+  /** Entry points */
+  entryPoints: string[]
+  /** Comments and docstrings */
+  documentation: DocumentationInfo[]
+}
+
+export interface FunctionInfo {
+  name: string
+  file: string
+  line: number
+  params: string[]
+  returnType?: string
+  isAsync: boolean
+  isExported: boolean
+  docstring?: string
+  comments?: string[]
+}
+
+export interface ClassInfo {
+  name: string
+  file: string
+  line: number
+  methods: FunctionInfo[]
+  properties: string[]
+  extends?: string
+  implements?: string[]
+  docstring?: string
+}
+
+export interface ModuleInfo {
+  name: string
+  file: string
+  exports: string[]
+  imports: { from: string; items: string[] }[]
+}
+
+export interface DocumentationInfo {
+  file: string
+  line: number
+  type: 'comment' | 'docstring' | 'jsdoc' | 'inline'
+  content: string
+  associatedWith?: string // function/class name
+}
+
+// =============================================================================
+// SOURCE ANALYSIS
+// =============================================================================
+
+/**
+ * Analyze a codebase to extract function/class/module information
+ */
+export async function analyzeCodebase(rootPath: string): Promise<CodebaseAnalysis> {
+  const functions: FunctionInfo[] = []
+  const classes: ClassInfo[] = []
+  const modules: ModuleInfo[] = []
+  const documentation: DocumentationInfo[] = []
+  const entryPoints: string[] = []
+
+  const sourceExtensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']
+
+  function walkDirectory(dir: string): void {
+    const entries = readdirSync(dir)
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry)
+
+      // Skip node_modules, .git, build artifacts, etc.
+      if (entry === 'node_modules' || entry === '.git' || entry === 'dist' || entry === 'build' ||
+          entry === '.local' || entry === 'test-workspace' || entry === 'coverage' || entry === '.turbo') {
+        continue
+      }
+
+      let stat
+      try {
+        stat = statSync(fullPath)
+      } catch (err) {
+        // Skip broken symlinks or inaccessible files
+        continue
+      }
+
+      if (stat.isDirectory()) {
+        walkDirectory(fullPath)
+      } else if (sourceExtensions.includes(extname(entry))) {
+        analyzeSourceFile(fullPath, rootPath, functions, classes, modules, documentation)
+
+        // Detect entry points
+        if (entry === 'index.ts' || entry === 'index.js' || entry === 'main.ts' || entry === 'main.js') {
+          entryPoints.push(relative(rootPath, fullPath))
+        }
+      }
+    }
+  }
+
+  walkDirectory(rootPath)
+
+  // Also check package.json for entry points
+  const packageJsonPath = join(rootPath, 'package.json')
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'))
+      if (pkg.main) entryPoints.push(pkg.main)
+      if (pkg.module) entryPoints.push(pkg.module)
+      if (pkg.bin) {
+        if (typeof pkg.bin === 'string') {
+          entryPoints.push(pkg.bin)
+        } else {
+          entryPoints.push(...Object.values(pkg.bin) as string[])
+        }
+      }
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  return {
+    rootPath,
+    functions,
+    classes,
+    modules,
+    entryPoints: [...new Set(entryPoints)],
+    documentation,
+  }
+}
+
+/**
+ * Analyze a single source file
+ */
+function analyzeSourceFile(
+  filePath: string,
+  rootPath: string,
+  functions: FunctionInfo[],
+  classes: ClassInfo[],
+  modules: ModuleInfo[],
+  documentation: DocumentationInfo[]
+): void {
+  try {
+    const content = readFileSync(filePath, 'utf-8')
+    const lines = content.split('\n')
+    const relativePath = relative(rootPath, filePath)
+
+    // Extract imports
+    const imports: { from: string; items: string[] }[] = []
+    const exports: string[] = []
+
+    // Simple regex-based extraction (more robust would use AST)
+    const functionRegex = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g
+    const classRegex = /(?:export\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?/g
+    const arrowFunctionRegex = /(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\([^)]*\)\s*=>/g
+    const methodRegex = /(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*\w+)?\s*\{/g
+    const exportRegex = /export\s+(?:default\s+)?(?:const|let|var|function|class|interface|type)\s+(\w+)/g
+    const importRegex = /import\s+(?:{([^}]+)}|(\w+))\s+from\s+['"]([^'"]+)['"]/g
+    const commentRegex = /\/\*\*([\s\S]*?)\*\/|\/\/\s*(.*)/g
+    const docstringRegex = /\/\*\*\s*([\s\S]*?)\s*\*\//g
+
+    // Extract functions
+    let match
+    while ((match = functionRegex.exec(content)) !== null) {
+      const name = match[1]
+      const line = content.slice(0, match.index).split('\n').length
+
+      // Look for preceding docstring
+      const docstring = findPrecedingDocstring(lines, line - 1)
+
+      functions.push({
+        name,
+        file: relativePath,
+        line,
+        params: extractParams(content, match.index),
+        isAsync: match[0].includes('async'),
+        isExported: match[0].includes('export'),
+        docstring,
+      })
+    }
+
+    // Extract arrow functions
+    while ((match = arrowFunctionRegex.exec(content)) !== null) {
+      const name = match[1]
+      const line = content.slice(0, match.index).split('\n').length
+
+      const docstring = findPrecedingDocstring(lines, line - 1)
+
+      functions.push({
+        name,
+        file: relativePath,
+        line,
+        params: extractParams(content, match.index),
+        isAsync: match[0].includes('async'),
+        isExported: match[0].includes('export'),
+        docstring,
+      })
+    }
+
+    // Extract classes
+    while ((match = classRegex.exec(content)) !== null) {
+      const name = match[1]
+      const extendsClass = match[2]
+      const line = content.slice(0, match.index).split('\n').length
+
+      const docstring = findPrecedingDocstring(lines, line - 1)
+
+      // Find methods in the class
+      const classEndIndex = findMatchingBrace(content, content.indexOf('{', match.index))
+      const classBody = content.slice(match.index, classEndIndex)
+      const classMethods: FunctionInfo[] = []
+
+      let methodMatch
+      const classMethodRegex = /(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*[\w<>\[\]]+)?\s*\{/g
+      while ((methodMatch = classMethodRegex.exec(classBody)) !== null) {
+        if (methodMatch[1] !== 'constructor' && methodMatch[1] !== 'if' && methodMatch[1] !== 'for' && methodMatch[1] !== 'while') {
+          classMethods.push({
+            name: methodMatch[1],
+            file: relativePath,
+            line: line + classBody.slice(0, methodMatch.index).split('\n').length - 1,
+            params: extractParams(classBody, methodMatch.index),
+            isAsync: methodMatch[0].includes('async'),
+            isExported: false,
+          })
+        }
+      }
+
+      classes.push({
+        name,
+        file: relativePath,
+        line,
+        methods: classMethods,
+        properties: [],
+        extends: extendsClass,
+        docstring,
+      })
+    }
+
+    // Extract exports
+    while ((match = exportRegex.exec(content)) !== null) {
+      exports.push(match[1])
+    }
+
+    // Extract imports
+    while ((match = importRegex.exec(content)) !== null) {
+      const items = (match[1] || match[2]).split(',').map(s => s.trim())
+      const from = match[3]
+      imports.push({ from, items })
+    }
+
+    if (exports.length > 0 || imports.length > 0) {
+      modules.push({
+        name: relativePath,
+        file: relativePath,
+        exports,
+        imports,
+      })
+    }
+
+    // Extract documentation
+    while ((match = docstringRegex.exec(content)) !== null) {
+      const line = content.slice(0, match.index).split('\n').length
+      documentation.push({
+        file: relativePath,
+        line,
+        type: 'docstring',
+        content: match[1].trim(),
+      })
+    }
+
+  } catch (error) {
+    // Ignore files that can't be read
+  }
+}
+
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+
+function findPrecedingDocstring(lines: string[], lineIndex: number): string | undefined {
+  // Look backwards for a docstring
+  for (let i = lineIndex - 1; i >= 0 && i >= lineIndex - 5; i--) {
+    const line = lines[i]?.trim()
+    if (line?.startsWith('/**')) {
+      // Found start of docstring, collect until */
+      const docLines: string[] = []
+      for (let j = i; j <= lineIndex; j++) {
+        docLines.push(lines[j]?.replace(/^\s*\*\s?/, '').replace(/\*\//, '').trim() || '')
+        if (lines[j]?.includes('*/')) break
+      }
+      return docLines.filter(l => l).join(' ')
+    }
+    if (line?.startsWith('//')) {
+      return line.slice(2).trim()
+    }
+    if (line && !line.startsWith('*')) {
+      break
+    }
+  }
+  return undefined
+}
+
+function extractParams(content: string, startIndex: number): string[] {
+  const parenStart = content.indexOf('(', startIndex)
+  const parenEnd = findMatchingParen(content, parenStart)
+  const paramString = content.slice(parenStart + 1, parenEnd)
+
+  if (!paramString.trim()) return []
+
+  // Simple param extraction
+  return paramString
+    .split(',')
+    .map(p => p.split(':')[0].trim())
+    .filter(p => p && !p.startsWith('{') && !p.startsWith('['))
+}
+
+function findMatchingParen(content: string, startIndex: number): number {
+  let depth = 0
+  for (let i = startIndex; i < content.length; i++) {
+    if (content[i] === '(') depth++
+    if (content[i] === ')') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return startIndex
+}
+
+function findMatchingBrace(content: string, startIndex: number): number {
+  let depth = 0
+  for (let i = startIndex; i < content.length; i++) {
+    if (content[i] === '{') depth++
+    if (content[i] === '}') {
+      depth--
+      if (depth === 0) return i
+    }
+  }
+  return content.length
+}
+
+// =============================================================================
+// INTENT INFERENCE
+// =============================================================================
+
+/**
+ * Infer the intent of a function from its name, params, and context
+ */
+export function inferIntent(
+  func: FunctionInfo,
+  classes: ClassInfo[],
+  documentation: DocumentationInfo[]
+): InferredIntent {
+  const name = func.name
+  const docstring = func.docstring
+
+  // Start with docstring if available
+  if (docstring) {
+    return {
+      purpose: docstring,
+      confidence: 0.9,
+      source: 'docstring',
+    }
+  }
+
+  // Infer from function name patterns
+  const patterns: Array<{ regex: RegExp; purpose: (match: RegExpMatchArray) => string }> = [
+    { regex: /^get(\w+)$/, purpose: (m) => `Retrieve ${camelToSpaces(m[1])}` },
+    { regex: /^set(\w+)$/, purpose: (m) => `Set ${camelToSpaces(m[1])}` },
+    { regex: /^is(\w+)$/, purpose: (m) => `Check if ${camelToSpaces(m[1])}` },
+    { regex: /^has(\w+)$/, purpose: (m) => `Check if has ${camelToSpaces(m[1])}` },
+    { regex: /^create(\w+)$/, purpose: (m) => `Create ${camelToSpaces(m[1])}` },
+    { regex: /^delete(\w+)$/, purpose: (m) => `Delete ${camelToSpaces(m[1])}` },
+    { regex: /^remove(\w+)$/, purpose: (m) => `Remove ${camelToSpaces(m[1])}` },
+    { regex: /^add(\w+)$/, purpose: (m) => `Add ${camelToSpaces(m[1])}` },
+    { regex: /^update(\w+)$/, purpose: (m) => `Update ${camelToSpaces(m[1])}` },
+    { regex: /^fetch(\w+)$/, purpose: (m) => `Fetch ${camelToSpaces(m[1])} from remote` },
+    { regex: /^load(\w+)$/, purpose: (m) => `Load ${camelToSpaces(m[1])}` },
+    { regex: /^save(\w+)$/, purpose: (m) => `Save ${camelToSpaces(m[1])}` },
+    { regex: /^validate(\w+)$/, purpose: (m) => `Validate ${camelToSpaces(m[1])}` },
+    { regex: /^parse(\w+)$/, purpose: (m) => `Parse ${camelToSpaces(m[1])}` },
+    { regex: /^convert(\w+)$/, purpose: (m) => `Convert ${camelToSpaces(m[1])}` },
+    { regex: /^transform(\w+)$/, purpose: (m) => `Transform ${camelToSpaces(m[1])}` },
+    { regex: /^handle(\w+)$/, purpose: (m) => `Handle ${camelToSpaces(m[1])}` },
+    { regex: /^process(\w+)$/, purpose: (m) => `Process ${camelToSpaces(m[1])}` },
+    { regex: /^send(\w+)$/, purpose: (m) => `Send ${camelToSpaces(m[1])}` },
+    { regex: /^receive(\w+)$/, purpose: (m) => `Receive ${camelToSpaces(m[1])}` },
+    { regex: /^init(\w*)$/, purpose: (m) => m[1] ? `Initialize ${camelToSpaces(m[1])}` : 'Initialize' },
+    { regex: /^start(\w*)$/, purpose: (m) => m[1] ? `Start ${camelToSpaces(m[1])}` : 'Start' },
+    { regex: /^stop(\w*)$/, purpose: (m) => m[1] ? `Stop ${camelToSpaces(m[1])}` : 'Stop' },
+    { regex: /^on(\w+)$/, purpose: (m) => `Handler for ${camelToSpaces(m[1])} event` },
+  ]
+
+  for (const { regex, purpose } of patterns) {
+    const match = name.match(regex)
+    if (match) {
+      return {
+        purpose: purpose(match),
+        confidence: 0.7,
+        source: 'function-name',
+        inputs: func.params,
+      }
+    }
+  }
+
+  // Fallback to generic inference from name
+  return {
+    purpose: camelToSpaces(name),
+    confidence: 0.4,
+    source: 'function-name',
+    inputs: func.params,
+  }
+}
+
+function camelToSpaces(str: string): string {
+  return str
+    .replace(/([A-Z])/g, ' $1')
+    .toLowerCase()
+    .trim()
+}
+
+// =============================================================================
+// TRACE TO SOURCE MAPPING
+// =============================================================================
+
+/**
+ * Map a trace's function call to source code location
+ */
+export function mapTraceToSource(
+  functionName: string,
+  analysis: CodebaseAnalysis
+): TraceToSourceMapping {
+  // Search for function in analysis
+  const func = analysis.functions.find(f => f.name === functionName)
+
+  if (func) {
+    const intent = inferIntent(func, analysis.classes, analysis.documentation)
+
+    return {
+      traceId: '',
+      functionName,
+      sourceLocation: {
+        file: func.file,
+        line: func.line,
+        functionName: func.name,
+      },
+      intent,
+      confidence: intent.confidence,
+    }
+  }
+
+  // Search in class methods
+  for (const cls of analysis.classes) {
+    const method = cls.methods.find(m => m.name === functionName)
+    if (method) {
+      const intent = inferIntent(method, analysis.classes, analysis.documentation)
+
+      return {
+        traceId: '',
+        functionName,
+        sourceLocation: {
+          file: method.file,
+          line: method.line,
+          functionName: method.name,
+          className: cls.name,
+        },
+        intent,
+        confidence: intent.confidence,
+      }
+    }
+  }
+
+  // Not found
+  return {
+    traceId: '',
+    functionName,
+    confidence: 0,
+  }
+}
+
+// =============================================================================
+// EXPORTS
+// =============================================================================
+
+export const runtimeMapping = {
+  analyzeCodebase,
+  mapTraceToSource,
+  inferIntent,
+}