@rank-lang/lsp 0.3.0

package/dist/util/stdlib-hover.js

@@ -0,0 +1,109 @@
+import { formatStdlibHoverMarkdown, lookupStdlibBuiltinHoverInfo, lookupStdlibBuiltinValue, lookupStdlibBuiltinValueByQualifiedName, lookupStdlibModuleHoverInfo, lookupStdlibModuleValue, lookupStdlibTypeExportHoverInfo, stdModuleNamespacePath, } from "@rank-lang/compiler";
+import { identifierAtPosition } from "./type-symbols.js";
+function importedStdNamespaceModulePath(loadedModule, name) {
+    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, name) {
+    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) {
+    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, identifier) {
+    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, identifier) {
+    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, position, loadedModule) {
+    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/dist/util/type-symbols.d.ts

@@ -0,0 +1,13 @@
+import type { LoadedModule, RootModuleGraph, SourceSpan, 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;
+}
+export declare function identifierAtPosition(document: TextDocument, position: LspPosition): string | null;
+export declare function findTypeSymbolAtPosition(document: TextDocument, position: LspPosition, moduleGraph: RootModuleGraph, loadedModule: LoadedModule): TypeSymbolTarget | null;
+export declare function formatTypeNode(typeNode: TypeNode): string;
+export {};

package/dist/util/type-symbols.js

@@ -0,0 +1,118 @@
+function isIdentifierCharacter(char) {
+    return char !== undefined && /[A-Za-z0-9_:]/.test(char);
+}
+export function identifierAtPosition(document, position) {
+    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, name) {
+    return loadedModule.program.declarations.find((declaration) => declaration.kind === "TypeAliasDeclaration" && declaration.name === name);
+}
+function localTypeSymbolTarget(loadedModule, name) {
+    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, position, moduleGraph, loadedModule) {
+    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) {
+    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(" & ");
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@rank-lang/lsp",
+  "version": "0.3.0",
+  "description": "Rank Language Server Protocol server",
+  "author": "Benjamin Goodman <b@ben.website>",
+  "homepage": "https://rank-lang.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/ben_goodman/rank.git",
+    "directory": "packages/lsp"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/ben_goodman/rank/-/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/server.ts",
+      "development": "./src/server.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "bin": {
+    "rank-lsp": "dist/server.js"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "NODE_OPTIONS='--conditions=development' vitest run --passWithNoTests"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@rank-lang/compiler": "0.3.0",
+    "@rank-lang/server-runtime": "0.3.0",
+    "vscode-languageserver": "^9.0.1",
+    "vscode-languageserver-textdocument": "^1.0.12"
+  }
+}

package/src/features/completion.ts

@@ -0,0 +1,37 @@
+import { completionItemsAtPosition } from "@rank-lang/compiler";
+import type {
+  CompletionItem as LspCompletionItem,
+  TextDocumentPositionParams,
+} from "vscode-languageserver/node.js";
+import { CompletionItemKind } from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { fileURLToPath } from "node:url";
+import type { ProjectSession } from "../session.js";
+import { toSourcePosition } from "../util/convert.js";
+
+export async function handleCompletion(
+  params: TextDocumentPositionParams,
+  session: ProjectSession,
+  document?: TextDocument,
+): Promise<LspCompletionItem[]> {
+  const filePath = fileURLToPath(params.textDocument.uri);
+  const graph = await session.getModuleGraph(filePath);
+
+  if (!graph) return [];
+
+  const mod = session.getLoadedModule(graph, filePath);
+  if (!mod) return [];
+
+  const position = toSourcePosition(params.position, document);
+  const items = completionItemsAtPosition(graph, mod, position);
+
+  return items.map((item) => ({
+    label: item.label,
+    kind:
+      item.kind === "type"
+        ? CompletionItemKind.Class
+        : item.kind === "keyword"
+          ? CompletionItemKind.Keyword
+          : CompletionItemKind.Variable,
+  }));
+}

package/src/features/definition.ts

@@ -0,0 +1,49 @@
+import { findDefinitionAtPosition } from "@rank-lang/compiler";
+import type {
+  TextDocumentPositionParams,
+  Location,
+} from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import type { ProjectSession } from "../session.js";
+import { toSourcePosition, toLspRange } from "../util/convert.js";
+import { findTypeSymbolAtPosition } from "../util/type-symbols.js";
+
+export async function handleDefinition(
+  params: TextDocumentPositionParams,
+  session: ProjectSession,
+  document?: TextDocument,
+): Promise<Location | null> {
+  const filePath = fileURLToPath(params.textDocument.uri);
+  const graph = await session.getModuleGraph(filePath);
+
+  if (!graph) return null;
+
+  const mod = session.getLoadedModule(graph, filePath);
+  if (!mod) return null;
+
+  const position = toSourcePosition(params.position, document);
+  const definition = findDefinitionAtPosition(graph, mod, position);
+
+  if (definition) {
+    return {
+      uri: pathToFileURL(definition.filePath).href,
+      range: toLspRange(definition.span),
+    };
+  }
+
+  if (!document) {
+    return null;
+  }
+
+  const typeSymbol = findTypeSymbolAtPosition(document, params.position, graph, mod);
+
+  if (!typeSymbol) {
+    return null;
+  }
+
+  return {
+    uri: pathToFileURL(typeSymbol.filePath).href,
+    range: toLspRange(typeSymbol.span),
+  };
+}

package/src/features/diagnostics.ts

@@ -0,0 +1,195 @@
+import {
+  resolveModuleImports,
+  resolveModuleReferences,
+  resolveModuleTypeNames,
+  checkModuleTypes,
+  type Diagnostic as CompilerDiagnostic,
+  type DeclarationNode,
+  type LoadedModule,
+  type TypeNode,
+  type ValueBindingDeclarationNode,
+} from "@rank-lang/compiler";
+import { collectRankServerAppSurfaceDiagnostics } from "@rank-lang/server-runtime";
+import type { Connection } from "vscode-languageserver/node.js";
+import { pathToFileURL } from "node:url";
+import type { ProjectSession } from "../session.js";
+import { toLspDiagnostic } from "../util/convert.js";
+
+interface DiagnosticSuppression {
+  startOffset: number;
+  endOffset: number;
+  codes: Set<string>;
+}
+
+function parseIgnoredDiagnosticCodes(documentation: readonly string[]): Set<string> {
+  const codes = new Set<string>();
+
+  for (const line of documentation) {
+    const match = /^rank-ignore\b(.*)$/u.exec(line.trim());
+
+    if (!match) {
+      continue;
+    }
+
+    for (const code of (match[1] ?? "").split(/[\s,]+/u).map((value) => value.trim()).filter((value) => value.length > 0)) {
+      codes.add(code);
+    }
+  }
+
+  return codes;
+}
+
+function declarationStartOffset(declaration: DeclarationNode): number | undefined {
+  switch (declaration.kind) {
+    case "ValueBindingDeclaration":
+    case "TypeAliasDeclaration":
+      return declaration.nameSpan?.start.offset;
+    case "DestructuringBindingDeclaration":
+      return declaration.fieldSpans
+        ? Math.min(...Object.values(declaration.fieldSpans).map((span) => span.start.offset))
+        : undefined;
+  }
+}
+
+function collectDiagnosticSuppressions(loadedModule: LoadedModule): DiagnosticSuppression[] {
+  const declarationsWithStarts = loadedModule.program.declarations.map((declaration) => ({
+    declaration,
+    startOffset: declarationStartOffset(declaration),
+  }));
+  const suppressions: DiagnosticSuppression[] = [];
+
+  for (let index = 0; index < declarationsWithStarts.length; index += 1) {
+    const current = declarationsWithStarts[index];
+
+    if (!current) {
+      continue;
+    }
+
+    const startOffset = current.startOffset;
+
+    if (startOffset === undefined) {
+      continue;
+    }
+
+    const codes = parseIgnoredDiagnosticCodes(current.declaration.documentation);
+
+    if (codes.size === 0) {
+      continue;
+    }
+
+    const nextStartOffset = declarationsWithStarts
+      .slice(index + 1)
+      .map((candidate) => candidate.startOffset)
+      .find((candidate): candidate is number => candidate !== undefined);
+
+    suppressions.push({
+      startOffset,
+      endOffset: nextStartOffset ?? Number.POSITIVE_INFINITY,
+      codes,
+    });
+  }
+
+  return suppressions;
+}
+
+function isSuppressedDiagnostic(diagnostic: CompilerDiagnostic, suppressions: readonly DiagnosticSuppression[]): boolean {
+  if (!diagnostic.span) {
+    return false;
+  }
+
+  return suppressions.some((suppression) => (
+    diagnostic.span!.start.offset >= suppression.startOffset
+    && diagnostic.span!.start.offset < suppression.endOffset
+    && suppression.codes.has(diagnostic.code)
+  ));
+}
+
+function exportedValueDeclaration(loadedModule: LoadedModule, name: string): ValueBindingDeclarationNode | undefined {
+  return loadedModule.program.declarations.find(
+    (declaration): declaration is ValueBindingDeclarationNode =>
+      declaration.kind === "ValueBindingDeclaration"
+      && declaration.visibility === "pub"
+      && declaration.name === name,
+  );
+}
+
+function isExecutionContextTypeName(name: string): boolean {
+  return name === "ExecutionContext"
+    || name === "Runtime::ExecutionContext"
+    || name === "std::Runtime::ExecutionContext";
+}
+
+function isServeExecutionContextTypeAnnotation(typeNode: TypeNode | undefined): boolean {
+  return !!typeNode
+    && typeNode.kind === "GenericType"
+    && typeNode.arguments.length === 1
+    && isExecutionContextTypeName(typeNode.name);
+}
+
+function shouldPublishServeDiagnostics(loadedModule: LoadedModule): boolean {
+  if (exportedValueDeclaration(loadedModule, "config")) {
+    return true;
+  }
+
+  const mainDeclaration = exportedValueDeclaration(loadedModule, "main");
+
+  return !!mainDeclaration
+    && mainDeclaration.value.kind === "FunctionExpression"
+    && (
+      mainDeclaration.value.parameters.length === 0
+      || (
+        mainDeclaration.value.parameters.length === 1
+        && isServeExecutionContextTypeAnnotation(mainDeclaration.value.parameters[0]?.typeAnnotation)
+      )
+    );
+}
+
+export async function publishDiagnostics(
+  connection: Connection,
+  session: ProjectSession,
+  filePath: string,
+): Promise<void> {
+  const graph = await session.getModuleGraph(filePath);
+
+  if (!graph) {
+    return;
+  }
+
+  const importDiagnostics = resolveModuleImports(graph);
+  const refDiagnostics = resolveModuleReferences(graph);
+  const typeDiagnostics = resolveModuleTypeNames(graph);
+  const checkDiagnostics = checkModuleTypes(graph, await session.getTypeCheckOptions(filePath, graph));
+  const entryModule = graph.modules[graph.entryModulePath];
+  const serveDiagnostics = entryModule && shouldPublishServeDiagnostics(entryModule)
+    ? collectRankServerAppSurfaceDiagnostics(graph, entryModule.filePath)
+    : [];
+
+  const allDiagnostics = [
+    ...graph.diagnostics,
+    ...importDiagnostics,
+    ...refDiagnostics,
+    ...typeDiagnostics,
+    ...checkDiagnostics,
+    ...serveDiagnostics,
+  ];
+
+  // Group diagnostics by source file and publish per-file.
+  const byFile = new Map<string, typeof allDiagnostics>();
+
+  for (const d of allDiagnostics) {
+    let list = byFile.get(d.sourcePath);
+    if (!list) {
+      list = [];
+      byFile.set(d.sourcePath, list);
+    }
+    list.push(d);
+  }
+
+  // Publish for the affected file and clear any files with no diagnostics.
+  for (const mod of Object.values(graph.modules)) {
+    const uri = pathToFileURL(mod.filePath).href;
+    const suppressions = collectDiagnosticSuppressions(mod);
+    const diags = (byFile.get(mod.filePath) ?? []).filter((diagnostic) => !isSuppressedDiagnostic(diagnostic, suppressions));
+    connection.sendDiagnostics({ uri, diagnostics: diags.map(toLspDiagnostic) });
+  }
+}

package/src/features/hover.ts

@@ -0,0 +1,127 @@
+import {
+  hoverInfoAtPosition,
+  queryModuleBindingType,
+  type LoadedModule,
+  type RootModuleGraph,
+  type SourcePosition,
+  type ValueBindingDeclarationNode,
+} from "@rank-lang/compiler";
+import { collectRankServerAppSurfaceDiagnostics } from "@rank-lang/server-runtime";
+import type {
+  TextDocumentPositionParams,
+  Hover,
+} from "vscode-languageserver/node.js";
+import type { TextDocument } from "vscode-languageserver-textdocument";
+import { fileURLToPath } from "node:url";
+import type { ProjectSession } from "../session.js";
+import { toSourcePosition } from "../util/convert.js";
+import { findStdlibHoverAtPosition } from "../util/stdlib-hover.js";
+import { findTypeSymbolAtPosition, formatTypeNode } from "../util/type-symbols.js";
+
+function containsPosition(
+  span: { start: SourcePosition; end: SourcePosition } | undefined,
+  position: SourcePosition,
+): boolean {
+  return !!span && span.start.offset <= position.offset && position.offset < span.end.offset;
+}
+
+function exportedValueDeclaration(loadedModule: LoadedModule, name: string): ValueBindingDeclarationNode | undefined {
+  return loadedModule.program.declarations.find(
+    (declaration): declaration is ValueBindingDeclarationNode =>
+      declaration.kind === "ValueBindingDeclaration"
+      && declaration.visibility === "pub"
+      && declaration.name === name,
+  );
+}
+
+function serveConfigHoverAtPosition(
+  moduleGraph: RootModuleGraph,
+  loadedModule: LoadedModule,
+  position: SourcePosition,
+): string | null {
+  const entryModule = moduleGraph.modules[moduleGraph.entryModulePath];
+
+  if (!entryModule || entryModule.filePath !== loadedModule.filePath) {
+    return null;
+  }
+
+  const configDeclaration = exportedValueDeclaration(loadedModule, "config");
+
+  if (!configDeclaration || !containsPosition(configDeclaration.nameSpan, position)) {
+    return null;
+  }
+
+  const actualType = queryModuleBindingType(moduleGraph, loadedModule, "config", false);
+
+  if (!actualType) {
+    return null;
+  }
+
+  const serveDiagnostics = collectRankServerAppSurfaceDiagnostics(moduleGraph, loadedModule.filePath);
+  const lines = [
+    "```rank",
+    `config: ${actualType}`,
+    "```",
+    "",
+    "Serve config expects `HTTP::AppConfig` or `() -> HTTP::AppConfig`.",
+  ];
+
+  if (serveDiagnostics.some((diagnostic) => diagnostic.code === "SRV004")) {
+    lines.push(
+      "",
+      "This binding is invalid for serve-time `pub config`: it must be an object literal or zero-argument function.",
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export async function handleHover(
+  params: TextDocumentPositionParams,
+  session: ProjectSession,
+  document?: TextDocument,
+): Promise<Hover | null> {
+  const filePath = fileURLToPath(params.textDocument.uri);
+  const graph = await session.getModuleGraph(filePath);
+
+  if (!graph) return null;
+
+  const mod = session.getLoadedModule(graph, filePath);
+  if (!mod) return null;
+
+  const position = toSourcePosition(params.position, document);
+  const serveConfigMarkdown = serveConfigHoverAtPosition(graph, mod, position);
+
+  if (serveConfigMarkdown) {
+    return { contents: { kind: "markdown", value: serveConfigMarkdown } };
+  }
+
+  const markdown = hoverInfoAtPosition(graph, mod, position);
+
+  if (markdown) {
+    return { contents: { kind: "markdown", value: markdown } };
+  }
+
+  if (!document) {
+    return null;
+  }
+
+  const stdlibMarkdown = findStdlibHoverAtPosition(document, params.position, mod);
+
+  if (stdlibMarkdown) {
+    return { contents: { kind: "markdown", value: stdlibMarkdown } };
+  }
+
+  const typeSymbol = findTypeSymbolAtPosition(document, params.position, graph, mod);
+
+  if (!typeSymbol) {
+    return null;
+  }
+
+  return {
+    contents: {
+      kind: "markdown",
+      value: `\`\`\`rank\n${typeSymbol.name}: ${formatTypeNode(typeSymbol.type)}\n\`\`\``,
+    },
+  };
+}