forge-server 0.1.0

package/src/ingestion/parser.ts

@@ -0,0 +1,475 @@
+/**
+ * Tree-sitter AST parser for TypeScript/TSX/JavaScript/JSX (ADR-3).
+ * Extracts entities: functions, classes, interfaces, type aliases, exported variables, imports, exports.
+ * Falls back to empty result on parse error (error-tolerant).
+ */
+
+import { readFile } from 'fs/promises';
+import { extname } from 'path';
+import type { ParseResult, ParsedEntity, ParsedImport } from '../util/types.js';
+import { logger } from '../util/logger.js';
+
+// tree-sitter imports - native C addon
+// We use dynamic import with fallback to web-tree-sitter (WASM)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let Parser: any = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let TypeScriptGrammar: any = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let TSXGrammar: any = null;
+
+let parserInitialized = false;
+// Eagerly kick off initialization when the module loads.
+// This allows synchronous callers (parseContent) to find the parser ready
+// by the time test fixtures set up via async beforeAll blocks.
+let _initPromiseEager: Promise<boolean> | null = null;
+
+// Start loading immediately (non-blocking, fire-and-forget in module scope)
+// The promise is stored so callers can await it if needed.
+_initPromiseEager = (async () => {
+  try {
+    const treeSitter = await import('tree-sitter');
+    Parser = treeSitter.default;
+    const tsGrammar = await import('tree-sitter-typescript');
+    TypeScriptGrammar = (tsGrammar.default as { typescript: unknown; tsx: unknown }).typescript;
+    TSXGrammar = (tsGrammar.default as { typescript: unknown; tsx: unknown }).tsx;
+    parserInitialized = true;
+    return true;
+  } catch {
+    parserInitialized = true;
+    return false;
+  }
+})();
+
+export async function initParser(): Promise<boolean> {
+  // Reuse the eager init promise if it's still running.
+  if (_initPromiseEager) {
+    const result = await _initPromiseEager;
+    _initPromiseEager = null;
+    if (result) {
+      logger.info('tree-sitter parser initialized (native)');
+    } else {
+      logger.warn('tree-sitter native addon failed to load, parser will return empty results', {});
+    }
+    return result;
+  }
+  return Parser !== null;
+}
+
+/**
+ * Determine language from file extension.
+ */
+export function getLanguage(filePath: string): string | null {
+  const ext = extname(filePath).toLowerCase();
+  const map: Record<string, string> = {
+    '.ts': 'typescript',
+    '.tsx': 'tsx',
+    '.js': 'javascript',
+    '.jsx': 'tsx',
+    '.mts': 'typescript',
+    '.cts': 'typescript',
+    '.mjs': 'javascript',
+    '.cjs': 'javascript',
+  };
+  return map[ext] ?? null;
+}
+
+/**
+ * Parse a TypeScript/JavaScript file and extract entities.
+ */
+export async function parseFile(filePath: string, repoId: string): Promise<ParseResult> {
+  await initParser();
+
+  const lang = getLanguage(filePath);
+  if (!lang) {
+    return {
+      entities: [],
+      imports: [],
+      filePath,
+      language: 'unknown',
+      success: false,
+      error: 'Unsupported file extension',
+    };
+  }
+
+  let content: string;
+  try {
+    content = await readFile(filePath, 'utf8');
+  } catch (err) {
+    return {
+      entities: [],
+      imports: [],
+      filePath,
+      language: lang,
+      success: false,
+      error: `Failed to read file: ${String(err)}`,
+    };
+  }
+
+  return parseContent(content, filePath, repoId, lang);
+}
+
+/**
+ * Parse content string (useful for testing without filesystem).
+ */
+export function parseContent(
+  content: string,
+  filePath: string,
+  repoId: string,
+  language: string
+): ParseResult {
+  if (!Parser || !TypeScriptGrammar) {
+    // Parser not available - return empty but successful result
+    return {
+      entities: [],
+      imports: [],
+      filePath,
+      language,
+      success: false,
+      error: 'Parser not initialized (WASM fallback not implemented)',
+    };
+  }
+
+  try {
+    const parser = new Parser();
+
+    if (language === 'tsx') {
+      parser.setLanguage(TSXGrammar);
+    } else {
+      parser.setLanguage(TypeScriptGrammar);
+    }
+
+    const tree = parser.parse(content);
+    const rootNode = tree.rootNode;
+
+    const entities: ParsedEntity[] = [];
+    const imports: ParsedImport[] = [];
+
+    // Walk the AST
+    walkNode(rootNode, content, filePath, repoId, entities, imports);
+
+    return {
+      entities,
+      imports,
+      filePath,
+      language,
+      success: true,
+    };
+  } catch (err) {
+    logger.warn('AST parse error', { filePath, error: String(err) });
+    return {
+      entities: [],
+      imports: [],
+      filePath,
+      language,
+      success: false,
+      error: String(err),
+    };
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function walkNode(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  content: string,
+  filePath: string,
+  repoId: string,
+  entities: ParsedEntity[],
+  imports: ParsedImport[]
+): void {
+  const type = node.type as string;
+
+  // Import declarations — tree-sitter-typescript uses `import_statement`
+  if (type === 'import_statement' || type === 'import_declaration') {
+    const importNode = extractImport(node, content);
+    if (importNode) imports.push(importNode);
+    return; // Don't recurse into imports
+  }
+
+  // Export statements - check what they export
+  // tree-sitter-typescript uses `export_statement`
+  if (type === 'export_statement') {
+    extractExportedEntities(node, content, filePath, repoId, entities);
+    return;
+  }
+
+  // Function declarations at top level
+  if (type === 'function_declaration' || type === 'generator_function_declaration') {
+    const entity = extractFunction(node, content, filePath, repoId, false);
+    if (entity) entities.push(entity);
+    return;
+  }
+
+  // Class declarations at top level
+  if (type === 'class_declaration') {
+    const entity = extractClass(node, content, filePath, repoId, false);
+    if (entity) entities.push(entity);
+    return;
+  }
+
+  // Interface declarations (TypeScript)
+  if (type === 'interface_declaration') {
+    const entity = extractInterface(node, content, filePath, repoId, false);
+    if (entity) entities.push(entity);
+    return;
+  }
+
+  // Type alias declarations (TypeScript)
+  if (type === 'type_alias_declaration') {
+    const entity = extractTypeAlias(node, content, filePath, repoId, false);
+    if (entity) entities.push(entity);
+    return;
+  }
+
+  // Lexical declarations (const/let/var) at top level - only exported ones captured in export_statement
+  // Variable declarations handled in export context
+
+  // Recurse into children for top-level nodes only
+  // We only care about top-level declarations
+  if (
+    type === 'program' ||
+    type === 'module' ||
+    type === 'statement_block'
+  ) {
+    for (let i = 0; i < node.childCount; i++) {
+      walkNode(node.child(i), content, filePath, repoId, entities, imports);
+    }
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractImport(node: any, content: string): ParsedImport | null {
+  try {
+    // Find the string source (module specifier)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let fromPath = '';
+    let specifiers = '';
+    let isDefault = false;
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'string') {
+        fromPath = content.slice(child.startIndex + 1, child.endIndex - 1); // strip quotes
+      }
+      if (child.type === 'import_clause') {
+        const clauseText = content.slice(child.startIndex, child.endIndex);
+        specifiers = clauseText.trim();
+        isDefault = !clauseText.includes('{');
+      }
+    }
+
+    if (!fromPath) return null;
+
+    return { fromPath, specifiers, isDefault };
+  } catch {
+    return null;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractExportedEntities(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  content: string,
+  filePath: string,
+  repoId: string,
+  entities: ParsedEntity[]
+): void {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let isDefault = false;
+
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child.type === 'default') {
+      isDefault = true;
+      continue;
+    }
+
+    if (child.type === 'function_declaration' || child.type === 'generator_function_declaration') {
+      const entity = extractFunction(child, content, filePath, repoId, true);
+      if (entity) {
+        entity.isDefault = isDefault;
+        entities.push(entity);
+      }
+    } else if (child.type === 'class_declaration') {
+      const entity = extractClass(child, content, filePath, repoId, true);
+      if (entity) {
+        entity.isDefault = isDefault;
+        entities.push(entity);
+      }
+    } else if (child.type === 'interface_declaration') {
+      const entity = extractInterface(child, content, filePath, repoId, true);
+      if (entity) entities.push(entity);
+    } else if (child.type === 'type_alias_declaration') {
+      const entity = extractTypeAlias(child, content, filePath, repoId, true);
+      if (entity) entities.push(entity);
+    } else if (child.type === 'lexical_declaration' || child.type === 'variable_declaration') {
+      // export const foo = ...
+      extractVariables(child, content, filePath, repoId, true, entities);
+    }
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractFunction(node: any, content: string, filePath: string, repoId: string, isExported: boolean): ParsedEntity | null {
+  try {
+    let name = '';
+    let params = '';
+    let isAsync = false;
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'async') isAsync = true;
+      if (child.type === 'identifier') name = content.slice(child.startIndex, child.endIndex);
+      if (child.type === 'formal_parameters') {
+        params = content.slice(child.startIndex, child.endIndex);
+      }
+    }
+
+    if (!name) return null;
+
+    return {
+      name,
+      type: 'function',
+      filePath,
+      repoId,
+      startLine: node.startPosition.row + 1,
+      endLine: node.endPosition.row + 1,
+      isExported,
+      isAsync,
+      params,
+      sourceText: content.slice(node.startIndex, node.endIndex),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractClass(node: any, content: string, filePath: string, repoId: string, isExported: boolean): ParsedEntity | null {
+  try {
+    let name = '';
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'type_identifier' || child.type === 'identifier') {
+        name = content.slice(child.startIndex, child.endIndex);
+        break;
+      }
+    }
+
+    if (!name) return null;
+
+    return {
+      name,
+      type: 'class',
+      filePath,
+      repoId,
+      startLine: node.startPosition.row + 1,
+      endLine: node.endPosition.row + 1,
+      isExported,
+      sourceText: content.slice(node.startIndex, node.endIndex),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractInterface(node: any, content: string, filePath: string, repoId: string, isExported: boolean): ParsedEntity | null {
+  try {
+    let name = '';
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'type_identifier' || child.type === 'identifier') {
+        name = content.slice(child.startIndex, child.endIndex);
+        break;
+      }
+    }
+
+    if (!name) return null;
+
+    return {
+      name,
+      type: 'interface',
+      filePath,
+      repoId,
+      startLine: node.startPosition.row + 1,
+      endLine: node.endPosition.row + 1,
+      isExported,
+      sourceText: content.slice(node.startIndex, node.endIndex),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractTypeAlias(node: any, content: string, filePath: string, repoId: string, isExported: boolean): ParsedEntity | null {
+  try {
+    let name = '';
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'type_identifier' || child.type === 'identifier') {
+        name = content.slice(child.startIndex, child.endIndex);
+        break;
+      }
+    }
+
+    if (!name) return null;
+
+    return {
+      name,
+      type: 'type_alias',
+      filePath,
+      repoId,
+      startLine: node.startPosition.row + 1,
+      endLine: node.endPosition.row + 1,
+      isExported,
+      sourceText: content.slice(node.startIndex, node.endIndex),
+    };
+  } catch {
+    return null;
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractVariables(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  content: string,
+  filePath: string,
+  repoId: string,
+  isExported: boolean,
+  entities: ParsedEntity[]
+): void {
+  try {
+    const isConst = content.slice(node.startIndex, node.startIndex + 5).startsWith('const');
+
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (child.type === 'variable_declarator') {
+        const nameNode = child.child(0);
+        if (nameNode && (nameNode.type === 'identifier' || nameNode.type === 'type_identifier')) {
+          const name = content.slice(nameNode.startIndex, nameNode.endIndex);
+          entities.push({
+            name,
+            type: 'variable',
+            filePath,
+            repoId,
+            startLine: node.startPosition.row + 1,
+            endLine: node.endPosition.row + 1,
+            isExported,
+            isConst,
+            sourceText: content.slice(node.startIndex, node.endIndex),
+          });
+        }
+      }
+    }
+  } catch {
+    // Skip malformed variable declarations
+  }
+}

package/src/ingestion/watcher.ts

@@ -0,0 +1,182 @@
+/**
+ * File system watcher using chokidar (ADR, section 4.5).
+ * Watches configured repo directories, debounces rapid saves (500ms),
+ * respects .gitignore patterns, and detects git HEAD changes for branch switches.
+ */
+
+import { EventEmitter } from 'events';
+import { join } from 'path';
+import { readFile } from 'fs/promises';
+import type { RepoConfig } from '../util/types.js';
+import { logger } from '../util/logger.js';
+
+// Chokidar dynamic import (ESM compatible)
+type ChokidarWatcher = {
+  on(event: string, handler: (path: string) => void): void;
+  close(): Promise<void>;
+};
+
+type WatchEvent = 'add' | 'change' | 'unlink';
+
+export interface FileChangeEvent {
+  type: WatchEvent;
+  filePath: string;
+  repoId: string;
+}
+
+const WATCHED_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs',
+  '.json', '.yaml', '.yml', '.md', '.mdx', '.graphql', '.gql', '.sql',
+]);
+
+const DEFAULT_IGNORED = [
+  '**/node_modules/**',
+  '**/.git/**',
+  '**/dist/**',
+  '**/build/**',
+  '**/.cache/**',
+  '**/*.map',
+  '**/*.min.js',
+  '**/*.min.css',
+  '**/package-lock.json',
+  '**/pnpm-lock.yaml',
+  '**/.DS_Store',
+  '**/Thumbs.db',
+];
+
+export class FileWatcher extends EventEmitter {
+  private watchers: Map<string, ChokidarWatcher> = new Map();
+  private debounceTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+  private gitHeadValues: Map<string, string> = new Map();
+  private readonly debounceMs: number;
+
+  constructor(debounceMs: number = 500) {
+    super();
+    this.debounceMs = debounceMs;
+  }
+
+  async watch(repoConfig: RepoConfig, additionalIgnored: string[] = []): Promise<void> {
+    const { id: repoId, path: repoPath } = repoConfig;
+
+    try {
+      const { default: chokidar } = await import('chokidar');
+
+      const ignored = [...DEFAULT_IGNORED, ...additionalIgnored];
+
+      const watcher = chokidar.watch(repoPath, {
+        ignored,
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: {
+          stabilityThreshold: 100,
+          pollInterval: 50,
+        },
+        usePolling: false,
+        // Windows-specific: use polling as fallback for network drives
+        interval: 500,
+        binaryInterval: 1000,
+      });
+
+      // Watch git HEAD for branch switches
+      const gitHeadPath = join(repoPath, '.git', 'HEAD');
+      await this.initGitHead(repoId, gitHeadPath);
+
+      watcher.on('add', (filePath: string) => this.handleChange('add', filePath, repoId));
+      watcher.on('change', (filePath: string) => this.handleChange('change', filePath, repoId));
+      watcher.on('unlink', (filePath: string) => this.handleChange('unlink', filePath, repoId));
+      watcher.on('error', (error: unknown) => {
+        const msg = error instanceof Error ? error.message : String(error);
+        logger.error('Watcher error', { repoId, error: msg });
+      });
+
+      // Watch .git/HEAD separately for branch switch detection.
+      // The main watcher ignores .git/** so we need a dedicated watcher.
+      const gitHeadWatcher = chokidar.watch(gitHeadPath, {
+        persistent: true,
+        ignoreInitial: true,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 50 },
+        usePolling: false,
+        interval: 500,
+      });
+      gitHeadWatcher.on('change', () => this.handleGitHeadChange(repoId, gitHeadPath));
+
+      this.watchers.set(repoId, watcher);
+      logger.info('Watching repo', { repoId, path: repoPath });
+    } catch (err) {
+      logger.error('Failed to start watcher', { repoId, error: String(err) });
+    }
+  }
+
+  async stop(repoId?: string): Promise<void> {
+    if (repoId) {
+      const watcher = this.watchers.get(repoId);
+      if (watcher) {
+        await watcher.close();
+        this.watchers.delete(repoId);
+      }
+    } else {
+      for (const [id, watcher] of this.watchers) {
+        await watcher.close();
+        this.watchers.delete(id);
+      }
+    }
+  }
+
+  private handleChange(type: WatchEvent, filePath: string, repoId: string): void {
+    // Filter by extension
+    const ext = filePath.slice(filePath.lastIndexOf('.')).toLowerCase();
+    if (!WATCHED_EXTENSIONS.has(ext) && !filePath.endsWith('HEAD')) return;
+
+    // Debounce
+    const debounceKey = `${repoId}:${filePath}`;
+    const existing = this.debounceTimers.get(debounceKey);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(debounceKey);
+      this.handleFileChangeDebounced(type, filePath, repoId);
+    }, this.debounceMs);
+
+    this.debounceTimers.set(debounceKey, timer);
+  }
+
+  private async handleFileChangeDebounced(
+    type: WatchEvent,
+    filePath: string,
+    repoId: string
+  ): Promise<void> {
+    // Check for git HEAD changes (branch switch detection)
+    if (filePath.endsWith('.git/HEAD') || filePath.endsWith('.git\\HEAD')) {
+      await this.handleGitHeadChange(repoId, filePath);
+      return;
+    }
+
+    const event: FileChangeEvent = { type, filePath, repoId };
+    this.emit('file-change', event);
+    logger.debug('File change detected', { type, filePath, repoId });
+  }
+
+  private async initGitHead(repoId: string, headPath: string): Promise<void> {
+    try {
+      const content = await readFile(headPath, 'utf8');
+      this.gitHeadValues.set(repoId, content.trim());
+    } catch {
+      // .git/HEAD may not exist for non-git repos
+    }
+  }
+
+  private async handleGitHeadChange(repoId: string, headPath: string): Promise<void> {
+    try {
+      const newHead = (await readFile(headPath, 'utf8')).trim();
+      const oldHead = this.gitHeadValues.get(repoId);
+
+      if (oldHead !== newHead) {
+        this.gitHeadValues.set(repoId, newHead);
+        logger.info('Git branch switch detected', { repoId, from: oldHead, to: newHead });
+        this.emit('branch-switch', { repoId, from: oldHead, to: newHead });
+      }
+    } catch {
+      // Ignore errors reading git HEAD
+    }
+  }
+}