@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/context/lsp-client.ts

@@ -0,0 +1,283 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'child_process';
+import { readFileSync } from 'fs';
+import { relative, resolve, sep } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+export type LspNavigationKind = 'definition' | 'references' | 'implementations';
+
+export interface LspNavigationRequest {
+  navigation: LspNavigationKind;
+  path: string;
+  line: number;
+  column: number;
+}
+
+export interface LspNavigationLocation {
+  path: string;
+  line: number;
+  column: number;
+}
+
+export interface LanguageServerClientErrorCodes {
+  unavailable: string;
+  exited: string;
+  protocol: string;
+  requestFailed: string;
+  timeout: string;
+}
+
+export interface LanguageServerClientOptions {
+  repoRoot: string;
+  workspaceRoot: string;
+  command: readonly string[];
+  languageId: string;
+  serverName: string;
+  errorCodes: LanguageServerClientErrorCodes;
+  initializationOptions?: unknown;
+  clientCapabilities?: Record<string, unknown>;
+  workspaceConfiguration?: unknown;
+  maxStderrChars?: number;
+}
+
+type PendingRequest = {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: NodeJS.Timeout;
+};
+
+function normalizedRelative(root: string, absolute: string): string | undefined {
+  const value = relative(root, absolute).split(sep).join('/');
+  if (!value || value === '.' || value === '..' || value.startsWith('../')) return undefined;
+  return value;
+}
+
+function roundMs(value: number): number {
+  return Math.round(value * 100) / 100;
+}
+
+/**
+ * Small stdio JSON-RPC/LSP client shared by semantic providers.
+ *
+ * It deliberately owns transport/lifecycle only. Workspace discovery, build
+ * settings readiness, source identity and evidence freshness remain provider or
+ * Context Plane responsibilities so a language server can never become source
+ * authority merely because it returned a location.
+ */
+export class LanguageServerClient {
+  private readonly child: ChildProcessWithoutNullStreams;
+  private readonly pending = new Map<number, PendingRequest>();
+  private readonly openedDocuments = new Map<string, { version: number; text: string }>();
+  private nextId = 1;
+  private stdout = Buffer.alloc(0);
+  private stderr = '';
+  private processError: Error | undefined;
+  private closed = false;
+
+  constructor(private readonly options: LanguageServerClientOptions) {
+    if (!options.command[0]) throw new Error(`${options.errorCodes.unavailable}: ${options.serverName} command is empty.`);
+    this.child = spawn(options.command[0], [...options.command.slice(1)], {
+      cwd: options.workspaceRoot,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    this.child.unref();
+    for (const stream of [this.child.stdin, this.child.stdout, this.child.stderr]) {
+      (stream as typeof stream & { unref?: () => void }).unref?.();
+    }
+    this.child.stdout.on('data', (chunk: Buffer) => this.onStdout(chunk));
+    this.child.stderr.on('data', (chunk: Buffer) => {
+      this.stderr = `${this.stderr}${chunk.toString('utf8')}`.slice(-(options.maxStderrChars ?? 8_000));
+    });
+    this.child.on('error', (error) => {
+      this.processError = error;
+      this.rejectAll(new Error(`${options.errorCodes.unavailable}: ${error.message}`));
+    });
+    this.child.on('exit', (code, signal) => {
+      if (this.closed && this.pending.size === 0) return;
+      const detail = this.stderr.trim() || `exit=${String(code)} signal=${String(signal)}`;
+      const error = new Error(`${options.errorCodes.exited}: ${detail}`);
+      this.processError = error;
+      if (this.pending.size > 0) this.rejectAll(error);
+    });
+  }
+
+  pendingRequestCount(): number {
+    return this.pending.size;
+  }
+
+  private rejectAll(error: Error): void {
+    for (const request of this.pending.values()) {
+      clearTimeout(request.timer);
+      request.reject(error);
+    }
+    this.pending.clear();
+  }
+
+  private onStdout(chunk: Buffer): void {
+    this.stdout = Buffer.concat([this.stdout, chunk]);
+    while (true) {
+      const headerEnd = this.stdout.indexOf('\r\n\r\n');
+      if (headerEnd < 0) return;
+      const header = this.stdout.subarray(0, headerEnd).toString('utf8');
+      const match = /Content-Length:\s*(\d+)/i.exec(header);
+      if (!match) {
+        this.rejectAll(new Error(`${this.options.errorCodes.protocol}: ${this.options.serverName} response omitted Content-Length.`));
+        return;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      if (this.stdout.length < bodyStart + length) return;
+      const raw = this.stdout.subarray(bodyStart, bodyStart + length).toString('utf8');
+      this.stdout = this.stdout.subarray(bodyStart + length);
+      let message: { id?: number | string; method?: string; params?: unknown; result?: unknown; error?: { message?: string } };
+      try {
+        message = JSON.parse(raw) as typeof message;
+      } catch {
+        this.rejectAll(new Error(`${this.options.errorCodes.protocol}: ${this.options.serverName} returned invalid JSON.`));
+        continue;
+      }
+      if (message.method) {
+        if (message.id !== undefined) this.respondToServerRequest(message.id, message.method, message.params);
+        continue;
+      }
+      if (typeof message.id !== 'number') continue;
+      const pending = this.pending.get(message.id);
+      if (!pending) continue;
+      this.pending.delete(message.id);
+      clearTimeout(pending.timer);
+      if (message.error) pending.reject(new Error(`${this.options.errorCodes.requestFailed}: ${message.error.message ?? `unknown ${this.options.serverName} error`}`));
+      else pending.resolve(message.result);
+    }
+  }
+
+  private respondToServerRequest(id: number | string, method: string, params: unknown): void {
+    let result: unknown = null;
+    if (method === 'workspace/workspaceFolders') {
+      const uri = pathToFileURL(this.options.workspaceRoot).href;
+      result = [{ uri, name: this.options.workspaceRoot.split(sep).pop() || 'workspace' }];
+    } else if (method === 'workspace/configuration') {
+      const items = params && typeof params === 'object' && Array.isArray((params as { items?: unknown[] }).items)
+        ? (params as { items: unknown[] }).items
+        : [];
+      result = items.map(() => this.options.workspaceConfiguration ?? null);
+    }
+    try {
+      this.write({ jsonrpc: '2.0', id, result });
+    } catch {
+      // The process may have exited while handling a best-effort server request.
+    }
+  }
+
+  private write(message: Record<string, unknown>): void {
+    if (this.processError) throw this.processError;
+    if (this.closed) throw new Error(`${this.options.errorCodes.exited}: ${this.options.serverName} client is closed.`);
+    const body = JSON.stringify(message);
+    this.child.stdin.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+  }
+
+  request(method: string, params: unknown, timeoutMs: number): Promise<unknown> {
+    const id = this.nextId++;
+    return new Promise((resolveRequest, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        try {
+          this.notify('$/cancelRequest', { id });
+        } catch {
+          // The language server may already have exited; timeout remains authoritative.
+        }
+        reject(new Error(`${this.options.errorCodes.timeout}: ${method} exceeded ${timeoutMs}ms.`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve: resolveRequest, reject, timer });
+      try {
+        this.write({ jsonrpc: '2.0', id, method, params });
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      }
+    });
+  }
+
+  notify(method: string, params: unknown): void {
+    this.write({ jsonrpc: '2.0', method, params });
+  }
+
+  async initialize(timeoutMs: number): Promise<number> {
+    const startedAt = performance.now();
+    const uri = pathToFileURL(this.options.workspaceRoot).href;
+    await this.request('initialize', {
+      processId: process.pid,
+      rootUri: uri,
+      workspaceFolders: [{ uri, name: this.options.workspaceRoot.split(sep).pop() || 'workspace' }],
+      capabilities: this.options.clientCapabilities ?? { workspace: { workspaceFolders: true, configuration: true } },
+      clientInfo: { name: 'Forge', version: '1' },
+      ...(this.options.initializationOptions === undefined ? {} : { initializationOptions: this.options.initializationOptions }),
+    }, timeoutMs);
+    this.notify('initialized', {});
+    return roundMs(performance.now() - startedAt);
+  }
+
+  syncDocument(relativePath: string): void {
+    const absolute = resolve(this.options.workspaceRoot, relativePath);
+    const uri = pathToFileURL(absolute).href;
+    const text = readFileSync(absolute, 'utf8');
+    const existing = this.openedDocuments.get(relativePath);
+    if (!existing) {
+      this.notify('textDocument/didOpen', {
+        textDocument: { uri, languageId: this.options.languageId, version: 1, text },
+      });
+      this.openedDocuments.set(relativePath, { version: 1, text });
+      return;
+    }
+    if (existing.text === text) return;
+    const version = existing.version + 1;
+    this.notify('textDocument/didChange', {
+      textDocument: { uri, version },
+      contentChanges: [{ text }],
+    });
+    this.openedDocuments.set(relativePath, { version, text });
+  }
+
+  async navigate(
+    request: LspNavigationRequest,
+    workspaceRelativePath: string,
+    timeoutMs: number,
+  ): Promise<{ locations: LspNavigationLocation[]; navigationMs: number }> {
+    const uri = pathToFileURL(resolve(this.options.workspaceRoot, workspaceRelativePath)).href;
+    const params = {
+      textDocument: { uri },
+      position: { line: request.line - 1, character: request.column - 1 },
+    };
+    const startedAt = performance.now();
+    const raw = request.navigation === 'references'
+      ? await this.request('textDocument/references', { ...params, context: { includeDeclaration: true } }, timeoutMs)
+      : request.navigation === 'implementations'
+        ? await this.request('textDocument/implementation', params, timeoutMs)
+        : await this.request('textDocument/definition', params, timeoutMs);
+    const navigationMs = roundMs(performance.now() - startedAt);
+    const values = raw === null || raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+    const locations: LspNavigationLocation[] = [];
+    for (const value of values) {
+      if (!value || typeof value !== 'object') continue;
+      const item = value as Record<string, unknown>;
+      const locationUri = typeof item.uri === 'string' ? item.uri : typeof item.targetUri === 'string' ? item.targetUri : undefined;
+      const range = (item.range ?? item.targetSelectionRange ?? item.targetRange) as Record<string, unknown> | undefined;
+      const start = range?.start as Record<string, unknown> | undefined;
+      if (!locationUri?.startsWith('file:') || typeof start?.line !== 'number' || typeof start?.character !== 'number') continue;
+      let absolute: string;
+      try { absolute = fileURLToPath(locationUri); } catch { continue; }
+      const repoRelative = normalizedRelative(this.options.repoRoot, absolute);
+      if (!repoRelative) continue;
+      locations.push({ path: repoRelative, line: start.line + 1, column: start.character + 1 });
+    }
+    return { locations, navigationMs };
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    try { await this.request('shutdown', null, 500); } catch { /* bounded best effort */ }
+    try { this.notify('exit', null); } catch { /* process may already be gone */ }
+    this.closed = true;
+    this.child.kill();
+    this.rejectAll(new Error(`${this.options.errorCodes.exited}: ${this.options.serverName} client closed.`));
+  }
+}

package/src/runtime/context/semantic-navigation-contract.ts

@@ -0,0 +1,61 @@
+export type SemanticNavigationKind = 'definition' | 'references' | 'implementations';
+
+export interface SemanticNavigationRequest {
+  navigation: SemanticNavigationKind;
+  path: string;
+  line: number;
+  column: number;
+  tsconfigPath?: string;
+  language?: string;
+}
+
+export interface SemanticNavigationLocation {
+  path: string;
+  line: number;
+  column: number;
+  name?: string;
+  kind?: string;
+}
+
+export interface SemanticNavigationResult {
+  providerId: string;
+  providerIdentity?: string;
+  language: string;
+  navigation: SemanticNavigationKind;
+  target: { path: string; line: number; column: number };
+  locations: SemanticNavigationLocation[];
+  policyDeniedReads?: number;
+  details?: Record<string, unknown>;
+}
+
+export type SemanticNavigationOutcome =
+  | { ok: true; result: SemanticNavigationResult }
+  | { ok: false; code: string; message: string };
+
+export interface SemanticNavigationAccess {
+  cacheScope: string;
+  sourceIdentity?: string;
+  profile: string;
+  allowRepositoryPath(relativePath: string): boolean;
+}
+
+export interface SemanticNavigationProvider {
+  id: string;
+  languages: readonly string[];
+  supports(request: SemanticNavigationRequest): boolean;
+  navigate(
+    repoRoot: string,
+    requests: SemanticNavigationRequest[],
+    access: SemanticNavigationAccess,
+  ): Promise<SemanticNavigationOutcome[]>;
+}
+
+export interface IndexedSemanticNavigationRequest {
+  index: number;
+  request: SemanticNavigationRequest;
+}
+
+export interface IndexedSemanticNavigationOutcome {
+  index: number;
+  outcome: SemanticNavigationOutcome;
+}

package/src/runtime/context/semantic-navigation.ts

@@ -0,0 +1,223 @@
+import { extname } from 'path';
+import { navigateTypeScriptSymbol } from './typescript-navigation';
+import { navigateSwiftSymbols } from './swift-navigation';
+import { GenericLspSemanticProvider, type GenericLspProviderDescriptor } from './generic-lsp-provider';
+
+export * from './semantic-navigation-contract';
+import type {
+  IndexedSemanticNavigationOutcome,
+  IndexedSemanticNavigationRequest,
+  SemanticNavigationAccess,
+  SemanticNavigationOutcome,
+  SemanticNavigationProvider,
+  SemanticNavigationRequest,
+} from './semantic-navigation-contract';
+
+function extensionMatches(path: string, values: readonly string[]): boolean {
+  return values.includes(extname(path).toLowerCase());
+}
+
+const typeScriptProvider: SemanticNavigationProvider = {
+  id: 'typescript-language-service',
+  languages: ['typescript'],
+  supports: (request) => {
+    const extensionSupported = extensionMatches(request.path, ['.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs']);
+    return extensionSupported && (!request.language || request.language.toLowerCase() === 'typescript');
+  },
+  async navigate(repoRoot, requests, access) {
+    return requests.map((request) => {
+      let policyDeniedReads = 0;
+      try {
+        const result = navigateTypeScriptSymbol(repoRoot, {
+          navigation: request.navigation,
+          path: request.path,
+          line: request.line,
+          column: request.column,
+          tsconfigPath: request.tsconfigPath,
+        }, {
+          cacheScope: access.cacheScope,
+          sourceIdentity: access.sourceIdentity,
+          allowRepositoryPath: (relativePath) => {
+            const allowed = access.allowRepositoryPath(relativePath);
+            if (!allowed) policyDeniedReads += 1;
+            return allowed;
+          },
+        });
+        return {
+          ok: true,
+          result: {
+            providerId: 'typescript-language-service',
+            language: 'typescript',
+            navigation: result.navigation,
+            target: result.target,
+            locations: result.locations,
+            policyDeniedReads,
+          },
+        } satisfies SemanticNavigationOutcome;
+      } catch (error) {
+        return { ok: false, code: 'SEMANTIC_NAVIGATION_FAILED', message: error instanceof Error ? error.message : String(error) } satisfies SemanticNavigationOutcome;
+      }
+    });
+  },
+};
+
+const swiftProvider: SemanticNavigationProvider = {
+  id: 'sourcekit-lsp',
+  languages: ['swift'],
+  supports: (request) => extensionMatches(request.path, ['.swift'])
+    && (!request.language || request.language.toLowerCase() === 'swift'),
+  async navigate(repoRoot, requests, access) {
+    const invalid = new Map<number, SemanticNavigationOutcome>();
+    const eligible: Array<{ index: number; request: SemanticNavigationRequest }> = [];
+    requests.forEach((request, index) => {
+      if (request.tsconfigPath) {
+        invalid.set(index, { ok: false, code: 'SWIFT_SEMANTIC_TSCONFIG_UNSUPPORTED', message: 'tsconfig_path applies only to TypeScript semantic navigation.' });
+      } else if (access.profile !== 'controller') {
+        invalid.set(index, { ok: false, code: 'SWIFT_SEMANTIC_READ_SCOPE_UNSUPPORTED', message: 'External SourceKit-LSP navigation is restricted to the controller read profile; use lexical/CodeGraph evidence under narrower read policies.' });
+      } else {
+        eligible.push({ index, request });
+      }
+    });
+    const outputs: Array<SemanticNavigationOutcome | undefined> = new Array(requests.length);
+    for (const [index, outcome] of invalid) outputs[index] = outcome;
+    if (eligible.length > 0) {
+      const outcomes = await navigateSwiftSymbols(repoRoot, eligible.map(({ request }) => ({
+        navigation: request.navigation,
+        path: request.path,
+        line: request.line,
+        column: request.column,
+      })), {
+        allowRepositoryPath: access.allowRepositoryPath,
+      });
+      outcomes.forEach((outcome, offset) => {
+        const original = eligible[offset]!;
+        outputs[original.index] = outcome.ok
+          ? {
+              ok: true,
+              result: {
+                providerId: 'sourcekit-lsp',
+                providerIdentity: outcome.result.workspace.buildSettingsFingerprint,
+                language: 'swift',
+                navigation: outcome.result.navigation,
+                target: outcome.result.target,
+                locations: outcome.result.locations,
+                policyDeniedReads: 0,
+                details: { workspace: outcome.result.workspace, timingsMs: outcome.result.timingsMs },
+              },
+            }
+          : outcome;
+      });
+    }
+    return outputs.map((outcome) => outcome ?? ({ ok: false, code: 'SWIFT_SEMANTIC_NAVIGATION_FAILED', message: 'Swift semantic provider produced no outcome.' }));
+  },
+};
+
+export class SemanticProviderRegistry {
+  private readonly providers: SemanticNavigationProvider[] = [];
+
+  register(provider: SemanticNavigationProvider): this {
+    if (this.providers.some((candidate) => candidate.id === provider.id)) {
+      throw new Error(`SEMANTIC_PROVIDER_DUPLICATE: ${provider.id}`);
+    }
+    this.providers.push(provider);
+    return this;
+  }
+
+  list(): Array<{ id: string; languages: readonly string[] }> {
+    return this.providers.map((provider) => ({ id: provider.id, languages: provider.languages }));
+  }
+
+  resolve(request: SemanticNavigationRequest): SemanticNavigationProvider | undefined {
+    return this.providers.find((provider) => provider.supports(request));
+  }
+
+  async navigate(
+    repoRoot: string,
+    requests: IndexedSemanticNavigationRequest[],
+    access: SemanticNavigationAccess,
+  ): Promise<IndexedSemanticNavigationOutcome[]> {
+    const output: IndexedSemanticNavigationOutcome[] = [];
+    const groups = new Map<SemanticNavigationProvider, IndexedSemanticNavigationRequest[]>();
+    for (const entry of requests) {
+      const provider = this.resolve(entry.request);
+      if (!provider) {
+        output.push({
+          index: entry.index,
+          outcome: {
+            ok: false,
+            code: 'SEMANTIC_PROVIDER_UNAVAILABLE',
+            message: `No semantic provider is registered for ${entry.request.path}${entry.request.language ? ` (language=${entry.request.language})` : ''}.`,
+          },
+        });
+        continue;
+      }
+      const group = groups.get(provider) ?? [];
+      group.push(entry);
+      groups.set(provider, group);
+    }
+    for (const [provider, group] of groups) {
+      let outcomes: SemanticNavigationOutcome[];
+      try {
+        outcomes = await provider.navigate(repoRoot, group.map((entry) => entry.request), access);
+      } catch (error) {
+        outcomes = group.map(() => ({ ok: false, code: 'SEMANTIC_PROVIDER_FAILED', message: error instanceof Error ? error.message : String(error) }));
+      }
+      group.forEach((entry, offset) => {
+        output.push({
+          index: entry.index,
+          outcome: outcomes[offset] ?? { ok: false, code: 'SEMANTIC_PROVIDER_FAILED', message: `${provider.id} returned no outcome.` },
+        });
+      });
+    }
+    return output.sort((left, right) => left.index - right.index);
+  }
+}
+
+export const DEFAULT_GENERIC_LSP_DESCRIPTORS: readonly GenericLspProviderDescriptor[] = [
+  {
+    id: 'rust-analyzer',
+    language: 'rust',
+    languageId: 'rust',
+    command: ['rust-analyzer'],
+    extensions: ['.rs'],
+    rootMarkers: ['Cargo.toml'],
+    identityFiles: ['Cargo.lock', 'rust-toolchain.toml', 'rust-toolchain'],
+  },
+  {
+    id: 'gopls',
+    language: 'go',
+    languageId: 'go',
+    command: ['gopls'],
+    extensions: ['.go'],
+    rootMarkers: ['go.work', 'go.mod'],
+    identityFiles: ['go.sum'],
+  },
+  {
+    id: 'basedpyright',
+    language: 'python',
+    languageId: 'python',
+    command: ['basedpyright-langserver', '--stdio'],
+    extensions: ['.py', '.pyi'],
+    rootMarkers: ['pyproject.toml', 'basedpyrightconfig.json', 'pyrightconfig.json'],
+    identityFiles: ['uv.lock', 'poetry.lock', 'requirements.txt'],
+  },
+  {
+    id: 'clangd',
+    language: 'cpp',
+    languageId: 'cpp',
+    command: ['clangd'],
+    extensions: ['.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx'],
+    rootMarkers: ['compile_commands.json', '.clangd', 'CMakeLists.txt'],
+    identityFiles: ['compile_flags.txt'],
+  },
+];
+
+export function createDefaultSemanticProviderRegistry(): SemanticProviderRegistry {
+  const registry = new SemanticProviderRegistry()
+    .register(typeScriptProvider)
+    .register(swiftProvider);
+  for (const descriptor of DEFAULT_GENERIC_LSP_DESCRIPTORS) registry.register(new GenericLspSemanticProvider(descriptor));
+  return registry;
+}
+
+export const defaultSemanticProviderRegistry = createDefaultSemanticProviderRegistry();