@massu/core 1.3.0 → 1.4.0

package/src/lsp/enrich.ts

@@ -0,0 +1,127 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 4: LSP enrichment of AST adapter results.
+ *
+ * For each field in `result.conventions`, optionally enrich via LSP responses
+ * (e.g., resolve `Depends` → `fastapi.Depends` via `textDocument/definition`).
+ *
+ * Authority rule (per spec §4 / plan line 173-175):
+ *   - AST is AUTHORITATIVE. LSP only refines (e.g., resolves alias → fully
+ *     qualified import).
+ *   - LSP unavailable / timeout / Zod-fail / version-mismatch → keep AST,
+ *     log warning at field granularity, do NOT crash.
+ *
+ * Failure modes:
+ *   - `lspClient === null` → return original result unchanged (no log; the
+ *     "LSP not configured" path is the common case).
+ *   - LSP method returns null (capability missing, timeout, Zod fail) →
+ *     keep AST value, append a `_lsp_skipped: <reason>` note to provenance.
+ *   - Per-field error → ignore that single field, keep others (per plan).
+ */
+
+import type { AdapterResult, SourceFile } from '../detect/adapters/types.ts';
+import { pathToFileURL } from 'url';
+import type { LSPClient } from './client.ts';
+
+/**
+ * Enrich an `AdapterResult` with LSP data when the client is available.
+ *
+ * The current v1 implementation is intentionally minimal: it walks each
+ * source file and asks the LSP for `textDocument/documentSymbol`. When the
+ * LSP returns a populated symbol list AND a convention field's value matches
+ * a symbol name, the convention's provenance is annotated with the LSP-
+ * provided detail (e.g., the canonical import path).
+ *
+ * AST values are NEVER overwritten — provenance is the only field touched.
+ */
+export async function enrichAdapterResult(
+  result: AdapterResult,
+  lspClient: LSPClient | null,
+  sourceFiles: SourceFile[]
+): Promise<AdapterResult> {
+  if (!lspClient) return result;
+  if (sourceFiles.length === 0) return result;
+
+  // Build a map of convention-value → field-name(s) so we can match symbols.
+  const valueToFields = new Map<string, string[]>();
+  for (const [field, value] of Object.entries(result.conventions)) {
+    if (typeof value !== 'string') continue;
+    const arr = valueToFields.get(value) ?? [];
+    arr.push(field);
+    valueToFields.set(value, arr);
+  }
+  if (valueToFields.size === 0) return result;
+
+  const enrichedProvenance = [...result.provenance];
+
+  for (const file of sourceFiles) {
+    let symbols;
+    try {
+      const uri = pathToFileURL(file.path).toString();
+      symbols = await lspClient.documentSymbol(uri);
+    } catch (e) {
+      process.stderr.write(
+        `[massu/lsp] WARN: documentSymbol threw on ${file.path} — skipping enrichment for this file. (${e instanceof Error ? e.message : String(e)})\n`
+      );
+      continue;
+    }
+    if (!symbols || !Array.isArray(symbols)) continue;
+
+    for (const sym of symbols) {
+      if (!sym || typeof sym !== 'object') continue;
+      const symObj = sym as Record<string, unknown>;
+      const name = typeof symObj.name === 'string' ? symObj.name : null;
+      if (!name) continue;
+      const matchedFields = valueToFields.get(name);
+      if (!matchedFields) continue;
+
+      // Append an LSP-sourced provenance entry for each matched field. The
+      // AST entry stays in place — LSP is enrichment-only.
+      const detail = typeof symObj.detail === 'string' ? symObj.detail : null;
+      const line = extractStartLine(symObj);
+      for (const field of matchedFields) {
+        enrichedProvenance.push({
+          field,
+          sourceFile: file.path,
+          line: line ?? 0,
+          query: detail ? `lsp:documentSymbol(${detail})` : 'lsp:documentSymbol',
+        });
+      }
+    }
+  }
+
+  return {
+    ...result,
+    provenance: enrichedProvenance,
+  };
+}
+
+/**
+ * Pluck the start line from either DocumentSymbol shape (range.start.line) or
+ * SymbolInformation shape (location.range.start.line). Returns null if
+ * neither shape matches.
+ */
+function extractStartLine(sym: Record<string, unknown>): number | null {
+  // DocumentSymbol shape
+  const range = sym.range as Record<string, unknown> | undefined;
+  if (range && typeof range === 'object') {
+    const start = range.start as Record<string, unknown> | undefined;
+    if (start && typeof start.line === 'number') {
+      return start.line + 1; // convert 0-indexed to 1-indexed
+    }
+  }
+  // SymbolInformation shape
+  const loc = sym.location as Record<string, unknown> | undefined;
+  if (loc && typeof loc === 'object') {
+    const locRange = loc.range as Record<string, unknown> | undefined;
+    if (locRange && typeof locRange === 'object') {
+      const start = locRange.start as Record<string, unknown> | undefined;
+      if (start && typeof start.line === 'number') {
+        return start.line + 1;
+      }
+    }
+  }
+  return null;
+}

package/src/lsp/types.ts

@@ -0,0 +1,221 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Plan 3b — Phase 4: LSP message TypeScript interfaces + Zod runtime schemas.
+ *
+ * Per audit-iter-4 fix DD: every `*Request` / `*Response` / `*Params` /
+ * `ServerCapabilities` type is paired with a co-located `*ResponseSchema` for
+ * runtime validation. `client.ts` imports from here only — no inline Zod
+ * definitions in `client.ts`.
+ *
+ * The schemas validate the LSP `result` payloads we consume (NOT the
+ * full envelope) — `LSPMessageEnvelopeSchema` covers the wire envelope.
+ *
+ * VR check (per plan): `grep -nE 'export (interface|type|const) .*(Schema|
+ * Request|Response|Params|Capabilities)' packages/core/src/lsp/types.ts` MUST
+ * return ≥8 hits after Phase 4.
+ */
+
+import { z } from 'zod';
+
+// ============================================================
+// LSP error codes (subset we reference)
+// ============================================================
+
+/**
+ * JSON-RPC + LSP error codes used by the client. Numeric values match the
+ * LSP 3.17 spec — `MethodNotFound = -32601` is the gatekeeper for the
+ * graceful-degrade path (per plan line 160).
+ */
+export const LSPErrorCode = {
+  ParseError: -32700,
+  InvalidRequest: -32600,
+  MethodNotFound: -32601,
+  InvalidParams: -32602,
+  InternalError: -32603,
+  ServerNotInitialized: -32002,
+  RequestFailed: -32803,
+  ServerCancelled: -32802,
+} as const;
+export type LSPErrorCodeValue = typeof LSPErrorCode[keyof typeof LSPErrorCode];
+
+// ============================================================
+// Wire envelope (every LSP/JSON-RPC message)
+// ============================================================
+
+/**
+ * JSON-RPC 2.0 / LSP envelope. `id` is required for request/response, absent
+ * for notifications. `method` is present on requests/notifications, absent on
+ * responses. `result` xor `error` on responses.
+ */
+export const LSPMessageEnvelopeSchema = z.object({
+  jsonrpc: z.literal('2.0'),
+  id: z.union([z.number(), z.string()]).optional(),
+  method: z.string().optional(),
+  params: z.unknown().optional(),
+  result: z.unknown().optional(),
+  error: z
+    .object({
+      code: z.number(),
+      message: z.string(),
+      data: z.unknown().optional(),
+    })
+    .optional(),
+}).passthrough();
+export type LSPMessageEnvelope = z.infer<typeof LSPMessageEnvelopeSchema>;
+
+// ============================================================
+// Initialize
+// ============================================================
+
+export interface InitializeRequest {
+  processId: number | null;
+  rootUri: string | null;
+  capabilities: Record<string, unknown>;
+  workspaceFolders?: Array<{ uri: string; name: string }> | null;
+}
+
+/**
+ * Subset of LSP `ServerCapabilities` we consume. Everything else is ignored.
+ * Each `*Provider` flag may be absent (treat as false), `true`, or an object
+ * (treat as true — server supports the method but with options we don't use).
+ */
+export interface ServerCapabilities {
+  documentSymbolProvider?: boolean | Record<string, unknown>;
+  workspaceSymbolProvider?: boolean | Record<string, unknown>;
+  definitionProvider?: boolean | Record<string, unknown>;
+}
+
+export const ServerCapabilitiesSchema = z
+  .object({
+    documentSymbolProvider: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
+    workspaceSymbolProvider: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
+    definitionProvider: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
+  })
+  .passthrough();
+
+export interface InitializeResponse {
+  capabilities: ServerCapabilities;
+  serverInfo?: { name: string; version?: string };
+}
+
+export const InitializeResponseSchema = z
+  .object({
+    capabilities: ServerCapabilitiesSchema,
+    serverInfo: z
+      .object({
+        name: z.string(),
+        version: z.string().optional(),
+      })
+      .optional(),
+  })
+  .passthrough();
+
+// ============================================================
+// Position / Range / Location (shared)
+// ============================================================
+
+export const PositionSchema = z.object({
+  line: z.number().int().nonnegative(),
+  character: z.number().int().nonnegative(),
+});
+export type Position = z.infer<typeof PositionSchema>;
+
+export const RangeSchema = z.object({
+  start: PositionSchema,
+  end: PositionSchema,
+});
+export type Range = z.infer<typeof RangeSchema>;
+
+export const LocationSchema = z.object({
+  uri: z.string(),
+  range: RangeSchema,
+});
+export type Location = z.infer<typeof LocationSchema>;
+
+// ============================================================
+// textDocument/documentSymbol
+// ============================================================
+
+export interface DocumentSymbolParams {
+  textDocument: { uri: string };
+}
+
+/**
+ * Document symbols come in two shapes: hierarchical `DocumentSymbol[]` (LSP
+ * 3.10+) or flat `SymbolInformation[]` (legacy). We accept either at the
+ * Zod level — consumers in `enrich.ts` pick the shape they care about.
+ */
+const DocumentSymbolNodeSchema: z.ZodType<unknown> = z.lazy(() =>
+  z
+    .object({
+      name: z.string(),
+      kind: z.number(),
+      range: RangeSchema,
+      selectionRange: RangeSchema,
+      detail: z.string().optional(),
+      children: z.array(DocumentSymbolNodeSchema).optional(),
+    })
+    .passthrough()
+);
+
+const SymbolInformationNodeSchema = z
+  .object({
+    name: z.string(),
+    kind: z.number(),
+    location: LocationSchema,
+    containerName: z.string().optional(),
+  })
+  .passthrough();
+
+export const DocumentSymbolResponseSchema = z.union([
+  z.array(DocumentSymbolNodeSchema),
+  z.array(SymbolInformationNodeSchema),
+  z.null(),
+]);
+export type DocumentSymbolResponse = z.infer<typeof DocumentSymbolResponseSchema>;
+
+// ============================================================
+// workspace/symbol
+// ============================================================
+
+export interface WorkspaceSymbolParams {
+  query: string;
+}
+
+export const WorkspaceSymbolResponseSchema = z.union([
+  z.array(SymbolInformationNodeSchema),
+  z.null(),
+]);
+export type WorkspaceSymbolResponse = z.infer<typeof WorkspaceSymbolResponseSchema>;
+
+// ============================================================
+// textDocument/definition
+// ============================================================
+
+export interface DefinitionParams {
+  textDocument: { uri: string };
+  position: Position;
+}
+
+/**
+ * Definition can be a single Location, an array of Locations, or null.
+ * (LSP also allows `LocationLink[]` — we accept it via passthrough but
+ * downstream consumers stick to `Location`.)
+ */
+export const DefinitionResponseSchema = z.union([
+  LocationSchema,
+  z.array(LocationSchema),
+  z.array(
+    z
+      .object({
+        targetUri: z.string(),
+        targetRange: RangeSchema,
+        targetSelectionRange: RangeSchema,
+      })
+      .passthrough()
+  ),
+  z.null(),
+]);
+export type DefinitionResponse = z.infer<typeof DefinitionResponseSchema>;