@rank-lang/lsp 0.3.0

package/src/server.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import path from "node:path";
+import {
+  createConnection,
+  ProposedFeatures,
+  TextDocumentSyncKind,
+  TextDocuments,
+} from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+import { fileURLToPath } from "node:url";
+import { ProjectSession } from "./session.js";
+import { publishDiagnostics } from "./features/diagnostics.js";
+import { handleHover } from "./features/hover.js";
+import { handleDefinition } from "./features/definition.js";
+import { handleCompletion } from "./features/completion.js";
+
+const connection = createConnection(ProposedFeatures.all);
+const documents = new TextDocuments(TextDocument);
+const session = new ProjectSession();
+
+connection.onInitialize(() => ({
+  capabilities: {
+    textDocumentSync: TextDocumentSyncKind.Incremental,
+    hoverProvider: true,
+    definitionProvider: true,
+    completionProvider: {
+      triggerCharacters: [".", ":", " "],
+    },
+  },
+}));
+
+documents.onDidOpen(({ document }) => {
+  const filePath = fileURLToPath(document.uri);
+  void publishDiagnostics(connection, session, filePath);
+});
+
+documents.onDidChangeContent(({ document }) => {
+  const filePath = fileURLToPath(document.uri);
+  session.invalidate(filePath);
+  void publishDiagnostics(connection, session, filePath);
+});
+
+documents.onDidSave(({ document }) => {
+  const filePath = fileURLToPath(document.uri);
+  session.invalidate(filePath);
+  void publishDiagnostics(connection, session, filePath);
+});
+
+connection.onDidChangeWatchedFiles(({ changes }) => {
+  const manifestChanges = changes
+    .map(({ uri }) => fileURLToPath(uri))
+    .filter((filePath) => path.basename(filePath) === "rank.toml");
+
+  if (manifestChanges.length === 0) {
+    return;
+  }
+
+  for (const manifestPath of manifestChanges) {
+    session.invalidate(manifestPath);
+  }
+
+  for (const document of documents.all()) {
+    const filePath = fileURLToPath(document.uri);
+    void publishDiagnostics(connection, session, filePath);
+  }
+});
+
+connection.onHover((params) => handleHover(params, session, documents.get(params.textDocument.uri)));
+connection.onDefinition((params) => handleDefinition(params, session, documents.get(params.textDocument.uri)));
+connection.onCompletion((params) => handleCompletion(params, session, documents.get(params.textDocument.uri)));
+
+documents.listen(connection);
+connection.listen();

package/src/session.ts

@@ -0,0 +1,224 @@
+import path from "node:path";
+import fs from "node:fs";
+import {
+  loadNearestRankManifestIfValid,
+  loadProjectModuleGraphAsync,
+  resolveSecurityOptions,
+  type RootModuleGraph,
+  type LoadedModule,
+  type TypeCheckOptions,
+} from "@rank-lang/compiler";
+
+interface CachedGraph {
+  graph: RootModuleGraph;
+  invalidated: boolean;
+}
+
+// Manages a per-project-root module graph cache. The cache is invalidated on
+// textDocument/didChange and textDocument/didSave for any file in the project.
+export class ProjectSession {
+  private readonly cache = new Map<string, CachedGraph>();
+
+  async getModuleGraph(filePath: string): Promise<RootModuleGraph | null> {
+    const resolvedFilePath = path.resolve(filePath);
+    const cacheKey = this.cacheKeyForFile(resolvedFilePath);
+
+    const cached = this.cache.get(cacheKey);
+
+    if (cached && !cached.invalidated && this.getLoadedModule(cached.graph, resolvedFilePath)) {
+      return cached.graph;
+    }
+
+    try {
+      const graph = await this.loadGraphForFile(resolvedFilePath);
+      this.cache.set(cacheKey, { graph, invalidated: false });
+      return graph;
+    } catch {
+      return null;
+    }
+  }
+
+  getLoadedModule(graph: RootModuleGraph, filePath: string): LoadedModule | null {
+    const resolved = path.resolve(filePath);
+
+    for (const mod of Object.values(graph.modules)) {
+      if (path.resolve(mod.filePath) === resolved) {
+        return mod;
+      }
+    }
+
+    return null;
+  }
+
+  async getTypeCheckOptions(filePath: string, graph?: RootModuleGraph): Promise<TypeCheckOptions | undefined> {
+    const resolvedFilePath = path.resolve(filePath);
+    const securityOptions = resolveSecurityOptions(loadNearestRankManifestIfValid(resolvedFilePath)?.security);
+    const testManifestPath = this.nearestTestManifestPathForFile(resolvedFilePath);
+
+    const providerCapabilities = new Set(securityOptions.compileTime.providerCapabilities);
+
+    if (testManifestPath && this.testManifestUsesProviderStubs(testManifestPath)) {
+      const loadedGraph = graph ?? await this.getModuleGraph(resolvedFilePath);
+
+      if (loadedGraph) {
+        for (const providerExport of Object.values(loadedGraph.providerExports)) {
+          if (providerExport.kind !== "backend") {
+            continue;
+          }
+
+          for (const capability of providerExport.capabilities) {
+            providerCapabilities.add(capability);
+          }
+        }
+      }
+    }
+
+    if (providerCapabilities.size === 0) {
+      if (securityOptions.compileTime.providerMutationExports.length > 0 || securityOptions.compileTime.allowedHttpHosts) {
+        return {
+          ...(securityOptions.compileTime.providerMutationExports.length > 0
+            ? { providerMutationExports: securityOptions.compileTime.providerMutationExports }
+            : {}),
+          ...(securityOptions.compileTime.allowedHttpHosts ? { allowedHttpHosts: securityOptions.compileTime.allowedHttpHosts } : {}),
+        };
+      }
+
+      return undefined;
+    }
+
+    return {
+      providerCapabilities: [...providerCapabilities].sort((left, right) => left.localeCompare(right)),
+      ...(securityOptions.compileTime.providerMutationExports.length > 0
+        ? { providerMutationExports: securityOptions.compileTime.providerMutationExports }
+        : {}),
+      ...(securityOptions.compileTime.allowedHttpHosts ? { allowedHttpHosts: securityOptions.compileTime.allowedHttpHosts } : {}),
+    };
+  }
+
+  invalidate(filePath: string): void {
+    const cacheKey = this.cacheKeyForFile(filePath);
+    const cached = this.cache.get(cacheKey);
+    if (cached) cached.invalidated = true;
+  }
+
+  private async loadGraphForFile(filePath: string): Promise<RootModuleGraph> {
+    const preferredEntryPath = this.preferredEntryPathForFile(filePath);
+    const securityOptions = resolveSecurityOptions(loadNearestRankManifestIfValid(filePath)?.security);
+    const graphOptions = securityOptions.compileTime.offline
+      ? { offline: true as const }
+      : undefined;
+
+    if (preferredEntryPath && preferredEntryPath !== filePath) {
+      const graph = await loadProjectModuleGraphAsync(preferredEntryPath, graphOptions);
+
+      if (this.getLoadedModule(graph, filePath)) {
+        return graph;
+      }
+    }
+
+    return loadProjectModuleGraphAsync(filePath, graphOptions);
+  }
+
+  private cacheKeyForFile(filePath: string): string {
+    return this.findProjectRoot(filePath) ?? path.resolve(filePath);
+  }
+
+  private preferredEntryPathForFile(filePath: string): string | null {
+    const resolvedFilePath = path.resolve(filePath);
+
+    if (path.basename(resolvedFilePath) === "main.rank") {
+      return resolvedFilePath;
+    }
+
+    let dir = path.dirname(resolvedFilePath);
+    const projectRoot = this.findProjectRoot(resolvedFilePath);
+    const stopDir = projectRoot ? path.resolve(projectRoot) : null;
+
+    for (let i = 0; i < 20; i++) {
+      const candidatePath = path.join(dir, "main.rank");
+
+      if (fs.existsSync(candidatePath)) {
+        return candidatePath;
+      }
+
+      if (stopDir && dir === stopDir) {
+        break;
+      }
+
+      const parent = path.dirname(dir);
+
+      if (parent === dir) {
+        break;
+      }
+
+      dir = parent;
+    }
+
+    return null;
+  }
+
+  private nearestTestManifestPathForFile(filePath: string): string | null {
+    let dir = path.dirname(path.resolve(filePath));
+    const projectRoot = this.findProjectRoot(filePath);
+    const stopDir = projectRoot ? path.resolve(projectRoot) : null;
+
+    for (let i = 0; i < 20; i++) {
+      const candidatePath = path.join(dir, "rank-test.json");
+
+      if (fs.existsSync(candidatePath)) {
+        return candidatePath;
+      }
+
+      if (stopDir && dir === stopDir) {
+        break;
+      }
+
+      const parent = path.dirname(dir);
+
+      if (parent === dir) {
+        break;
+      }
+
+      dir = parent;
+    }
+
+    return null;
+  }
+
+  private testManifestUsesProviderStubs(manifestPath: string): boolean {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8")) as unknown;
+
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return false;
+      }
+
+      const manifest = parsed as Record<string, unknown>;
+      const providerStubs = manifest.providerStubs;
+
+      if (manifest.kind !== "rank/test-case" || manifest.version !== 1 || typeof providerStubs !== "string" || providerStubs.length === 0) {
+        return false;
+      }
+
+      return fs.existsSync(path.resolve(path.dirname(manifestPath), providerStubs));
+    } catch {
+      return false;
+    }
+  }
+
+  private findProjectRoot(filePath: string): string | null {
+    let dir = path.dirname(path.resolve(filePath));
+
+    for (let i = 0; i < 20; i++) {
+      if (fs.existsSync(path.join(dir, "rank.toml"))) {
+        return dir;
+      }
+
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+
+    return null;
+  }
+}

package/src/util/convert.ts

@@ -0,0 +1,54 @@
+import { pathToFileURL } from "node:url";
+
+import type { SourcePosition, SourceSpan, Diagnostic as CompilerDiagnostic } from "@rank-lang/compiler";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import {
+  type DiagnosticRelatedInformation,
+  type Position as LspPosition,
+  type Range as LspRange,
+  type Diagnostic as LspDiagnostic,
+  DiagnosticSeverity,
+} from "vscode-languageserver/node.js";
+
+// Compiler uses 1-indexed lines/columns; LSP uses 0-indexed.
+export function toSourcePosition(pos: LspPosition, document?: TextDocument): SourcePosition {
+  return {
+    offset: document?.offsetAt(pos) ?? 0,
+    line: pos.line + 1,
+    column: pos.character + 1,
+  };
+}
+
+export function toLspRange(span: SourceSpan): LspRange {
+  return {
+    start: { line: span.start.line - 1, character: span.start.column - 1 },
+    end:   { line: span.end.line - 1,   character: span.end.column - 1 },
+  };
+}
+
+export function toLspDiagnostic(d: CompilerDiagnostic): LspDiagnostic {
+  const range: LspRange = d.span
+    ? toLspRange(d.span)
+    : { start: { line: 0, character: 0 }, end: { line: 0, character: Number.MAX_SAFE_INTEGER } };
+
+  const diagnostic: LspDiagnostic = {
+    range,
+    severity: d.severity === "error" ? DiagnosticSeverity.Error : DiagnosticSeverity.Warning,
+    message: d.message,
+    source: "rank",
+    code: d.code,
+    ...(d.labels && d.labels.length > 0
+      ? {
+        relatedInformation: d.labels.map<DiagnosticRelatedInformation>((label) => ({
+          location: {
+            uri: pathToFileURL(label.sourcePath).href,
+            range: toLspRange(label.span),
+          },
+          message: label.message,
+        })),
+      }
+      : {}),
+  };
+
+  return diagnostic;
+}

package/src/util/stdlib-hover.ts

@@ -0,0 +1,178 @@
+import {
+  formatStdlibHoverMarkdown,
+  lookupStdlibBuiltinHoverInfo,
+  lookupStdlibBuiltinValue,
+  lookupStdlibBuiltinValueByQualifiedName,
+  lookupStdlibModuleHoverInfo,
+  lookupStdlibModuleValue,
+  lookupStdlibTypeExportHoverInfo,
+  stdModuleNamespacePath,
+  type LoadedModule,
+} from "@rank-lang/compiler";
+import type { Position as LspPosition } from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+
+import { identifierAtPosition } from "./type-symbols.js";
+
+function importedStdNamespaceModulePath(
+  loadedModule: LoadedModule,
+  name: string,
+): string | null {
+  for (const importNode of loadedModule.program.imports) {
+    if (importNode.modulePath !== "std" || importNode.clause.kind !== "NamedImportClause") {
+      continue;
+    }
+
+    if (!importNode.clause.names.includes(name)) {
+      continue;
+    }
+
+    return stdModuleNamespacePath(name) ?? null;
+  }
+
+  return null;
+}
+
+function importedStdMemberModulePath(
+  loadedModule: LoadedModule,
+  name: string,
+): string | null {
+  for (const importNode of loadedModule.program.imports) {
+    if (!importNode.modulePath.startsWith("std::") || importNode.clause.kind !== "NamedImportClause") {
+      continue;
+    }
+
+    if (!importNode.clause.names.includes(name)) {
+      continue;
+    }
+
+    return importNode.modulePath;
+  }
+
+  return null;
+}
+
+function directStdlibHover(identifier: string): string | null {
+  const builtinId = lookupStdlibBuiltinValueByQualifiedName(identifier);
+
+  if (builtinId) {
+    const hover = lookupStdlibBuiltinHoverInfo(builtinId);
+    return hover ? formatStdlibHoverMarkdown(hover) : null;
+  }
+
+  const segments = identifier.split("::");
+
+  if (segments.length >= 3) {
+    const exportName = segments[segments.length - 1];
+    const modulePath = segments.slice(0, -1).join("::");
+
+    if (exportName) {
+      const typeHover = lookupStdlibTypeExportHoverInfo(modulePath, exportName);
+
+      if (typeHover) {
+        return formatStdlibHoverMarkdown(typeHover);
+      }
+    }
+  }
+
+  const moduleValue = lookupStdlibModuleValue(identifier);
+
+  if (moduleValue) {
+    const hover = lookupStdlibBuiltinHoverInfo(moduleValue);
+    return hover ? formatStdlibHoverMarkdown(hover) : null;
+  }
+
+  const moduleHover = lookupStdlibModuleHoverInfo(identifier);
+  return moduleHover ? formatStdlibHoverMarkdown(moduleHover) : null;
+}
+
+function importedQualifiedStdlibHover(
+  loadedModule: LoadedModule,
+  identifier: string,
+): string | null {
+  const segments = identifier.split("::");
+
+  if (segments.length !== 2) {
+    return null;
+  }
+
+  const qualifier = segments[0];
+  const exportName = segments[1];
+
+  if (!qualifier || !exportName) {
+    return null;
+  }
+
+  const modulePath = importedStdNamespaceModulePath(loadedModule, qualifier);
+
+  if (!modulePath) {
+    return null;
+  }
+
+  const builtinId = lookupStdlibBuiltinValue(modulePath, exportName);
+
+  if (builtinId) {
+    const hover = lookupStdlibBuiltinHoverInfo(builtinId);
+    return hover ? formatStdlibHoverMarkdown(hover) : null;
+  }
+
+  const typeHover = lookupStdlibTypeExportHoverInfo(modulePath, exportName);
+  return typeHover ? formatStdlibHoverMarkdown(typeHover) : null;
+}
+
+function importedBareStdlibHover(
+  loadedModule: LoadedModule,
+  identifier: string,
+): string | null {
+  const namespaceModulePath = importedStdNamespaceModulePath(loadedModule, identifier);
+
+  if (namespaceModulePath) {
+    const moduleValue = lookupStdlibModuleValue(namespaceModulePath);
+
+    if (moduleValue) {
+      const hover = lookupStdlibBuiltinHoverInfo(moduleValue);
+      return hover ? formatStdlibHoverMarkdown(hover) : null;
+    }
+
+    const moduleHover = lookupStdlibModuleHoverInfo(namespaceModulePath);
+    return moduleHover ? formatStdlibHoverMarkdown(moduleHover) : null;
+  }
+
+  const memberModulePath = importedStdMemberModulePath(loadedModule, identifier);
+
+  if (!memberModulePath) {
+    return null;
+  }
+
+  const builtinId = lookupStdlibBuiltinValue(memberModulePath, identifier);
+
+  if (builtinId) {
+    const hover = lookupStdlibBuiltinHoverInfo(builtinId);
+    return hover ? formatStdlibHoverMarkdown(hover) : null;
+  }
+
+  const typeHover = lookupStdlibTypeExportHoverInfo(memberModulePath, identifier);
+  return typeHover ? formatStdlibHoverMarkdown(typeHover) : null;
+}
+
+export function findStdlibHoverAtPosition(
+  document: TextDocument,
+  position: LspPosition,
+  loadedModule: LoadedModule,
+): string | null {
+  const identifier = identifierAtPosition(document, position);
+
+  if (!identifier) {
+    return null;
+  }
+
+  if (identifier.startsWith("std::")) {
+    return directStdlibHover(identifier);
+  }
+
+  if (identifier.includes("::")) {
+    return importedQualifiedStdlibHover(loadedModule, identifier);
+  }
+
+  return importedBareStdlibHover(loadedModule, identifier);
+}

package/src/util/type-symbols.ts

@@ -0,0 +1,165 @@
+import type {
+  LoadedModule,
+  RootModuleGraph,
+  SourceSpan,
+  TypeAliasDeclarationNode,
+  TypeNode,
+} from "@rank-lang/compiler";
+import type { Position as LspPosition } from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+
+interface TypeSymbolTarget {
+  filePath: string;
+  name: string;
+  span: SourceSpan;
+  type: TypeNode;
+}
+
+function isIdentifierCharacter(char: string | undefined): boolean {
+  return char !== undefined && /[A-Za-z0-9_:]/.test(char);
+}
+
+export function identifierAtPosition(document: TextDocument, position: LspPosition): string | null {
+  const text = document.getText();
+  const offset = document.offsetAt(position);
+  let start = offset;
+  let end = offset;
+
+  if (isIdentifierCharacter(text[offset])) {
+    end += 1;
+  } else if (isIdentifierCharacter(text[offset - 1])) {
+    start -= 1;
+  } else {
+    return null;
+  }
+
+  while (start > 0 && isIdentifierCharacter(text[start - 1])) {
+    start -= 1;
+  }
+
+  while (end < text.length && isIdentifierCharacter(text[end])) {
+    end += 1;
+  }
+
+  return text.slice(start, end);
+}
+
+function typeAliasDeclarationInModule(
+  loadedModule: LoadedModule,
+  name: string,
+): TypeAliasDeclarationNode | undefined {
+  return loadedModule.program.declarations.find(
+    (declaration): declaration is TypeAliasDeclarationNode =>
+      declaration.kind === "TypeAliasDeclaration" && declaration.name === name,
+  );
+}
+
+function localTypeSymbolTarget(
+  loadedModule: LoadedModule,
+  name: string,
+): TypeSymbolTarget | null {
+  const declaration = typeAliasDeclarationInModule(loadedModule, name);
+
+  if (!declaration?.nameSpan) {
+    return null;
+  }
+
+  return {
+    filePath: loadedModule.filePath,
+    name,
+    span: declaration.nameSpan,
+    type: declaration.type,
+  };
+}
+
+export function findTypeSymbolAtPosition(
+  document: TextDocument,
+  position: LspPosition,
+  moduleGraph: RootModuleGraph,
+  loadedModule: LoadedModule,
+): TypeSymbolTarget | null {
+  const name = identifierAtPosition(document, position);
+
+  if (!name || name.includes("::")) {
+    return null;
+  }
+
+  const local = localTypeSymbolTarget(loadedModule, name);
+  if (local) {
+    return local;
+  }
+
+  for (const importNode of loadedModule.program.imports) {
+    if (importNode.clause.kind !== "NamedImportClause") {
+      continue;
+    }
+
+    if (!importNode.clause.names.includes(name)) {
+      continue;
+    }
+
+    for (const mod of Object.values(moduleGraph.modules)) {
+      if (mod === loadedModule || !mod.exportedTypeNames.includes(name)) {
+        continue;
+      }
+
+      const imported = localTypeSymbolTarget(mod, name);
+      if (imported) {
+        return imported;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function formatTypeNode(typeNode: TypeNode): string {
+  switch (typeNode.kind) {
+    case "NamedType":
+      return typeNode.name;
+    case "NeverType":
+      return "never";
+    case "ListType":
+      return `[${formatTypeNode(typeNode.itemType)}]`;
+    case "LiteralType":
+      return typeNode.lexeme;
+    case "ParseTemplateType":
+      return `parse${typeNode.raw}`;
+    case "RoutePathType":
+      return `match\`${typeNode.raw}\``;
+    case "GenericType":
+      return `${typeNode.name}<${typeNode.arguments.map((argument) => formatTypeNode(argument)).join(", ")}>`;
+    case "ConfiguredType":
+      return `${formatTypeNode(typeNode.base)} { ... }`;
+    case "MappedType": {
+      const optionalSuffix = typeNode.optional === "add" ? "?" : typeNode.optional === "remove" ? "-?" : "";
+      return `Object { [${typeNode.keyName} in ${formatTypeNode(typeNode.domainType)}]${optionalSuffix}: ${formatTypeNode(typeNode.valueType)} }`;
+    }
+    case "IndexedAccessType":
+      return `${formatTypeNode(typeNode.objectType)}[${formatTypeNode(typeNode.indexType)}]`;
+    case "KeyofType":
+      return `keyof ${formatTypeNode(typeNode.operand)}`;
+    case "ConditionalType":
+      return `${formatTypeNode(typeNode.checkType)} extends ${formatTypeNode(typeNode.extendsType)} ? ${formatTypeNode(typeNode.trueType)} : ${formatTypeNode(typeNode.falseType)}`;
+    case "ObjectType": {
+      const fields = typeNode.fields.map((field) => `${field.name}${field.optional ? "?" : ""}: ${formatTypeNode(field.valueType)}`);
+      if (typeNode.restField) {
+        fields.push(`...: ${formatTypeNode(typeNode.restField.valueType)}`);
+      }
+      return `Object { ${fields.join(", ")} }`;
+    }
+    case "RefinementType": {
+      const fields = typeNode.fields.map((field) => `${field.name}${field.optional ? "?" : ""}: ${formatTypeNode(field.valueType)}`);
+      if (typeNode.restField) {
+        fields.push(`...: ${formatTypeNode(typeNode.restField.valueType)}`);
+      }
+      return `${formatTypeNode(typeNode.base)} { ${fields.join(", ")} }`;
+    }
+    case "FunctionType":
+      return `(${typeNode.parameterTypes.map((parameterType) => formatTypeNode(parameterType)).join(", ")}) => ${formatTypeNode(typeNode.returnType)}`;
+    case "UnionType":
+      return typeNode.members.map((member) => formatTypeNode(member)).join(" | ");
+    case "IntersectionType":
+      return typeNode.members.map((member) => formatTypeNode(member)).join(" & ");
+  }
+}