@rank-lang/lsp 0.3.0

package/test/editor-features.test.ts

@@ -0,0 +1,1167 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { findDefinitionAtPosition, hoverInfoAtPosition } from "@rank-lang/compiler";
+import { collectRankServerAppSurfaceDiagnostics } from "@rank-lang/server-runtime";
+import { describe, expect, test } from "vitest";
+import type { Connection, TextDocumentPositionParams } from "vscode-languageserver/node.js";
+import { TextDocument } from "vscode-languageserver-textdocument";
+
+import { publishDiagnostics } from "../src/features/diagnostics.ts";
+import { handleDefinition } from "../src/features/definition.ts";
+import { handleHover } from "../src/features/hover.ts";
+import { ProjectSession } from "../src/session.ts";
+import { toLspDiagnostic, toSourcePosition } from "../src/util/convert.ts";
+
+function examplePath(...segments: string[]): string {
+  return fileURLToPath(new URL(`../../../examples/${segments.join("/")}`, import.meta.url));
+}
+
+function providerFixturePath(...segments: string[]): string {
+  return fileURLToPath(new URL(`../../../testdata/modules/${segments.join("/")}`, import.meta.url));
+}
+
+const workspaceAwsPackageDirectory = fileURLToPath(new URL("../../plugins/aws", import.meta.url));
+
+function serverRuntimeFixturePath(...segments: string[]): string {
+  return fileURLToPath(new URL(`../../server-runtime/testdata/${segments.join("/")}`, import.meta.url));
+}
+
+async function withTempRankProject(
+  files: Record<string, string>,
+  run: (entryPath: string) => Promise<void>,
+  entryFile = "main.rank",
+): Promise<void> {
+  const directory = await mkdtemp(path.join(os.tmpdir(), "rank-lsp-"));
+
+  try {
+    for (const [relativePath, source] of Object.entries(files)) {
+      const absolutePath = path.join(directory, relativePath);
+      await mkdir(path.dirname(absolutePath), { recursive: true });
+      await writeFile(absolutePath, source, "utf8");
+    }
+
+    await run(path.join(directory, entryFile));
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function collectLspDiagnostics(entryPath: string) {
+  const compiler = await import("../../compiler/dist/index.js");
+  const graph = await compiler.loadProjectModuleGraphAsync(entryPath);
+
+  return [
+    ...compiler.resolveModuleImports(graph),
+    ...compiler.resolveModuleReferences(graph),
+    ...compiler.resolveModuleTypeNames(graph),
+    ...compiler.checkModuleTypes(graph),
+  ].map(toLspDiagnostic);
+}
+
+async function collectRawEditorDiagnostics(entryPath: string) {
+  const compiler = await import("../../compiler/dist/index.js");
+  const graph = await compiler.loadProjectModuleGraphAsync(entryPath);
+  const entryModule = graph.modules[graph.entryModulePath];
+  const serveDiagnostics = entryModule
+    ? collectRankServerAppSurfaceDiagnostics(graph, entryModule.filePath)
+    : [];
+
+  return [
+    ...graph.diagnostics,
+    ...compiler.resolveModuleImports(graph),
+    ...compiler.resolveModuleReferences(graph),
+    ...compiler.resolveModuleTypeNames(graph),
+    ...compiler.checkModuleTypes(graph),
+    ...serveDiagnostics,
+  ].map(toLspDiagnostic);
+}
+
+async function collectPublishedDiagnostics(entryPath: string) {
+  const session = new ProjectSession();
+  const published = new Map<string, ReturnType<typeof toLspDiagnostic>[]>();
+  const connection = {
+    sendDiagnostics(params: { uri: string; diagnostics: ReturnType<typeof toLspDiagnostic>[] }) {
+      published.set(params.uri, params.diagnostics);
+    },
+  } as Pick<Connection, "sendDiagnostics"> as Connection;
+
+  await publishDiagnostics(connection, session, entryPath);
+
+  return published.get(pathToFileURL(path.resolve(entryPath)).href) ?? [];
+}
+
+async function collectHover(
+  entryPath: string,
+  needle: string,
+  offset = 0,
+) {
+  const source = await readFile(entryPath, "utf8");
+  const index = source.indexOf(needle);
+
+  if (index < 0) {
+    throw new Error(`Missing hover needle: ${needle}`);
+  }
+
+  const document = TextDocument.create(pathToFileURL(entryPath).href, "rank", 1, source);
+  const session = new ProjectSession();
+
+  return handleHover(
+    {
+      textDocument: { uri: document.uri },
+      position: document.positionAt(index + offset),
+    },
+    session,
+    document,
+  );
+}
+
+describe("editor features", () => {
+  test("publish no diagnostics for README-style AWS module qualifiers", async () => {
+    await withTempRankProject(
+      {
+        "rank.toml": [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "lsp-aws-provider-import"',
+          'version = "0.1.0"',
+          'source = "src"',
+          "",
+          "[providers]",
+          `aws = { path = "${workspaceAwsPackageDirectory}" }`,
+          "",
+        ].join("\n"),
+        "src/main.rank": [
+          "use std::HTTP",
+          "use std::Runtime",
+          "use aws::{ DynamoDB, S3, SecretsManager }",
+          "",
+          "HealthRoute = HTTP::Route {",
+          "  method: `GET`,",
+          "  path: `/health`",
+          "}",
+          "",
+          "Routes = HealthRoute",
+          "",
+          "User = Object {",
+          "  userId: string,",
+          "  status: `active` | `inactive`,",
+          "}",
+          "",
+          "UsersTable = DynamoDB::Table<User, `userId`>",
+          "",
+          "dynamoClient: aws::DynamoDB::ClientConfig = DynamoDB::createClient({ region: `us-east-1` })",
+          "s3Client: aws::S3::ClientConfig = S3::createClient({ region: `us-east-1` })",
+          "secretsClient: aws::SecretsManager::ClientConfig = SecretsManager::createClient({ region: `us-east-1` })",
+          "getter = DynamoDB::Item<UsersTable>",
+          "",
+          "pub main = |req: Runtime::ExecutionContext<Routes>| {",
+          "  status: 200,",
+          "  body: {",
+          "    dynamoRegion: dynamoClient.region,",
+          "    s3Region: s3Client.region,",
+          "    secretsRegion: secretsClient.region,",
+          "    getter: getter,",
+          "  },",
+          "}",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const diagnostics = await collectRawEditorDiagnostics(entryPath);
+
+        expect(diagnostics).toEqual([]);
+      },
+      "src/main.rank",
+    );
+  });
+
+  test("resolve hover and definition from LSP document coordinates", async () => {
+    const filePath = examplePath("env-inputs", "main.rank");
+    const source = await readFile(filePath, "utf8");
+    const document = TextDocument.create(pathToFileURL(filePath).href, "rank", 1, source);
+    const session = new ProjectSession();
+    const graph = await session.getModuleGraph(filePath);
+
+    expect(graph).not.toBeNull();
+
+    if (!graph) {
+      return;
+    }
+
+    const mod = session.getLoadedModule(graph, filePath);
+
+    expect(mod).not.toBeNull();
+
+    if (!mod) {
+      return;
+    }
+
+    const referenceOffset = source.lastIndexOf("config");
+    const definitionOffset = source.lastIndexOf("config: AppConfig =");
+
+    expect(referenceOffset).toBeGreaterThanOrEqual(0);
+    expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+    const position = toSourcePosition(document.positionAt(referenceOffset), document);
+    const hover = hoverInfoAtPosition(graph, mod, position);
+    const definition = findDefinitionAtPosition(graph, mod, position);
+    const definitionStart = document.positionAt(definitionOffset);
+    const definitionEnd = document.positionAt(definitionOffset + "config".length);
+
+    expect(hover).toContain("config: Object");
+    expect(definition).toEqual({
+      filePath: path.resolve(filePath),
+      span: {
+        start: {
+          offset: definitionOffset,
+          line: definitionStart.line + 1,
+          column: definitionStart.character + 1,
+        },
+        end: {
+          offset: definitionOffset + "config".length,
+          line: definitionEnd.line + 1,
+          column: definitionEnd.character + 1,
+        },
+      },
+    });
+  });
+
+  test("resolve hover and definition for type alias references", async () => {
+    const filePath = examplePath("env-inputs", "main.rank");
+    const source = await readFile(filePath, "utf8");
+    const document = TextDocument.create(pathToFileURL(filePath).href, "rank", 1, source);
+    const session = new ProjectSession();
+    const referenceOffset = source.indexOf("Env<SysEnv>") + "Env<".length;
+    const definitionOffset = source.indexOf("SysEnv = Object {");
+
+    expect(referenceOffset).toBeGreaterThanOrEqual(0);
+    expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+    const params: TextDocumentPositionParams = {
+      textDocument: { uri: document.uri },
+      position: document.positionAt(referenceOffset),
+    };
+
+    const hover = await handleHover(params, session, document);
+    const definition = await handleDefinition(params, session, document);
+    const definitionStart = document.positionAt(definitionOffset);
+    const definitionEnd = document.positionAt(definitionOffset + "SysEnv".length);
+
+    expect(hover).toEqual({
+      contents: {
+        kind: "markdown",
+        value: "```rank\nSysEnv: Object { APP_ENV: AppEnv, PORT?: Decode<Port>, LOG_LEVEL?: LogLevel, SECRET_KEY: string, ...: string }\n```",
+      },
+    });
+    expect(definition).toEqual({
+      uri: pathToFileURL(path.resolve(filePath)).href,
+      range: {
+        start: definitionStart,
+        end: definitionEnd,
+      },
+    });
+  });
+
+  test("show stdlib hover for imported values", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::collections::{ map }\nitems = [1, 2]\npub main = || map(items, |item| item + 1)\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "map(items", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\ncollections::map: ([A], (A) -> B) -> [B]\n```\n\nTransforms each item with a callback and returns the collected results.\n\n- Callbacks may declare a trailing `IterativeContext` parameter.",
+          },
+        });
+      },
+    );
+  });
+
+  test("resolve hover and definition for values imported through facades", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use root::billing::{ quote }\npub main = || quote()\n",
+        "billing.rank": "pub use self::pricing::{ quote }\n",
+        "billing/pricing.rank": "pub quote = || `ready`\n",
+      },
+      async (entryPath) => {
+        const source = await readFile(entryPath, "utf8");
+        const document = TextDocument.create(pathToFileURL(entryPath).href, "rank", 1, source);
+        const session = new ProjectSession();
+        const referenceOffset = source.indexOf("quote }");
+        const pricingPath = path.join(path.dirname(entryPath), "billing", "pricing.rank");
+        const pricingSource = await readFile(pricingPath, "utf8");
+        const definitionOffset = pricingSource.indexOf("quote = ||");
+
+        expect(referenceOffset).toBeGreaterThanOrEqual(0);
+        expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+        const params: TextDocumentPositionParams = {
+          textDocument: { uri: document.uri },
+          position: document.positionAt(referenceOffset),
+        };
+        const hover = await handleHover(params, session, document);
+        const definition = await handleDefinition(params, session, document);
+        const definitionDocument = TextDocument.create(pathToFileURL(pricingPath).href, "rank", 1, pricingSource);
+        const definitionStart = definitionDocument.positionAt(definitionOffset);
+        const definitionEnd = definitionDocument.positionAt(definitionOffset + "quote".length);
+
+        expect(hover).toMatchObject({
+          contents: {
+            kind: "markdown",
+            value: expect.stringContaining("quote: () -> string"),
+          },
+        });
+        expect(definition).toEqual({
+          uri: pathToFileURL(pricingPath).href,
+          range: {
+            start: definitionStart,
+            end: definitionEnd,
+          },
+        });
+      },
+    );
+  });
+
+  test("resolve hover and definition for facade re-export clauses", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use root::billing::{ quote }\npub main = || quote()\n",
+        "billing.rank": "pub use self::pricing::{ quote }\n",
+        "billing/pricing.rank": "pub quote = || `ready`\n",
+      },
+      async (entryPath) => {
+        const facadePath = path.join(path.dirname(entryPath), "billing.rank");
+        const facadeSource = await readFile(facadePath, "utf8");
+        const document = TextDocument.create(pathToFileURL(facadePath).href, "rank", 1, facadeSource);
+        const session = new ProjectSession();
+        const referenceOffset = facadeSource.indexOf("quote }");
+        const pricingPath = path.join(path.dirname(entryPath), "billing", "pricing.rank");
+        const pricingSource = await readFile(pricingPath, "utf8");
+        const definitionOffset = pricingSource.indexOf("quote = ||");
+
+        expect(referenceOffset).toBeGreaterThanOrEqual(0);
+        expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+        const params: TextDocumentPositionParams = {
+          textDocument: { uri: document.uri },
+          position: document.positionAt(referenceOffset),
+        };
+        const hover = await handleHover(params, session, document);
+        const definition = await handleDefinition(params, session, document);
+        const definitionDocument = TextDocument.create(pathToFileURL(pricingPath).href, "rank", 1, pricingSource);
+        const definitionStart = definitionDocument.positionAt(definitionOffset);
+        const definitionEnd = definitionDocument.positionAt(definitionOffset + "quote".length);
+
+        expect(hover).toMatchObject({
+          contents: {
+            kind: "markdown",
+            value: expect.stringContaining("quote: () -> string"),
+          },
+        });
+        expect(definition).toEqual({
+          uri: pathToFileURL(pricingPath).href,
+          range: {
+            start: definitionStart,
+            end: definitionEnd,
+          },
+        });
+      },
+    );
+  });
+
+  test("show stdlib hover for qualified values", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::Path\npub main = || Path::join([`k8s`, `deployment.yaml`])\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "Path::join", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nPath::join: ([string]) -> Path::RelativePath\n```\n\nBuilds one relative path from a list of single path segments.\n\n- Each segment must be non-empty and must not contain `/`.",
+          },
+        });
+      },
+    );
+  });
+
+  test("show stdlib hover for imported type exports", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::Path\ndeployment: Path::RelativePath = Path::join([`README.md`])\npub main = || deployment\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "Path::RelativePath", 7);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nPath::RelativePath\n```\n\nOpaque pure relative path value used by path-aware stdlib APIs.",
+          },
+        });
+      },
+    );
+  });
+
+  test("show stdlib hover for module imports", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::Path\npub main = || Path::join([`k8s`, `service.yaml`])\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "std::Path", 5);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nstd::Path\n```\n\nPure relative-path construction and formatting helpers.\n\n- Value exports: from, join, toString\n- Type exports: RelativePath",
+          },
+        });
+      },
+    );
+  });
+
+  test("show hover for value binding declarations", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "services = {\n  api: { port: 8080 },\n  worker: { port: 9090 },\n  admin: { port: 7070 },\n}\n\npub main = || services\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "services =", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nservices: Object { api: Object { port: number }, worker: Object { port: number }, admin: Object { port: number } }\n```",
+          },
+        });
+      },
+    );
+  });
+
+  test("show hover for object field keys in value bindings", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "services = {\n  api: { port: 8080 },\n  worker: { port: 9090 },\n  admin: { port: 7070 },\n}\n\npub main = || services\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "api:", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nservices.api: Object { port: number }\n```",
+          },
+        });
+      },
+    );
+  });
+
+  test("resolve hover and definition for local function bindings", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "input = 21\npub main = || {\n  doubled = input * 2\n  return doubled\n}\n",
+      },
+      async (entryPath) => {
+        const source = await readFile(entryPath, "utf8");
+        const document = TextDocument.create(pathToFileURL(entryPath).href, "rank", 1, source);
+        const session = new ProjectSession();
+        const referenceOffset = source.lastIndexOf("doubled\n");
+        const definitionOffset = source.indexOf("doubled = input");
+
+        expect(referenceOffset).toBeGreaterThanOrEqual(0);
+        expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+        const params: TextDocumentPositionParams = {
+          textDocument: { uri: document.uri },
+          position: document.positionAt(referenceOffset),
+        };
+
+        const hover = await handleHover(params, session, document);
+        const definition = await handleDefinition(params, session, document);
+        const definitionStart = document.positionAt(definitionOffset);
+        const definitionEnd = document.positionAt(definitionOffset + "doubled".length);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\ndoubled: number\n```",
+          },
+        });
+        expect(definition).toEqual({
+          uri: pathToFileURL(path.resolve(entryPath)).href,
+          range: {
+            start: definitionStart,
+            end: definitionEnd,
+          },
+        });
+      },
+    );
+  });
+
+  test("resolve hover and definition for function parameters", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "pub main = |input: number| input + 1\n",
+      },
+      async (entryPath) => {
+        const source = await readFile(entryPath, "utf8");
+        const document = TextDocument.create(pathToFileURL(entryPath).href, "rank", 1, source);
+        const session = new ProjectSession();
+        const referenceOffset = source.lastIndexOf("input + 1");
+        const definitionOffset = source.indexOf("input: number");
+
+        expect(referenceOffset).toBeGreaterThanOrEqual(0);
+        expect(definitionOffset).toBeGreaterThanOrEqual(0);
+
+        const params: TextDocumentPositionParams = {
+          textDocument: { uri: document.uri },
+          position: document.positionAt(referenceOffset),
+        };
+
+        const hover = await handleHover(params, session, document);
+        const definition = await handleDefinition(params, session, document);
+        const definitionStart = document.positionAt(definitionOffset);
+        const definitionEnd = document.positionAt(definitionOffset + "input".length);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\ninput: number\n```",
+          },
+        });
+        expect(definition).toEqual({
+          uri: pathToFileURL(path.resolve(entryPath)).href,
+          range: {
+            start: definitionStart,
+            end: definitionEnd,
+          },
+        });
+      },
+    );
+  });
+
+  test("show hover for object field keys inside function-returned object literals", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::collections::{ reverse }\npub main = || {\n  reversed: reverse([1, 2, 3]),\n}\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "reversed:", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nreversed: [number]\n```",
+          },
+        });
+      },
+    );
+  });
+
+  test("show hover for inferred iterative callback context parameters", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::list::{ range }\nuse std::collections::{ map }\nvalues = range(3)\n  |> map(|_, ctx| ctx.index)\npub main = || values\n",
+      },
+      async (entryPath) => {
+        const hover = await collectHover(entryPath, "ctx.index", 1);
+
+        expect(hover).toEqual({
+          contents: {
+            kind: "markdown",
+            value: "```rank\nctx: Object { index: number, size: number, isFirst: bool, isLast: bool }\n```",
+          },
+        });
+      },
+    );
+  });
+
+  test("map unresolved references to their expression span", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "helper = 1\nvalue = missing\npub main = || value\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "NAM002");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(1);
+      },
+    );
+  });
+
+  test("map unknown imports to their clause span", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "/// import repro\nuse std::collections::{ filter, missing }\npub main = || filter\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "NAM001");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(1);
+      },
+    );
+  });
+
+  test("map unresolved type names to their type annotation span", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "helper = 1\nvalue: Missing<string> = helper\npub main = || value\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "NAM005");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(1);
+      },
+    );
+  });
+
+  test("map type mismatches to the annotated binding", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "helper = 1\nvalue: string = 42\npub main = || value\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP001");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(1);
+      },
+    );
+  });
+
+  test("map non-callable errors to the call expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "helper = 0\nvalue = 1\nresult = value(2)\npub main = || result\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP003");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(2);
+      },
+    );
+  });
+
+  test("suppresses matching published diagnostics for declarations with rank-ignore docs", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": [
+          "/// rank-ignore NAM002",
+          "ignored = missing_value",
+          "other = absent_value",
+          "pub main = || { ignored, other }",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const compilerDiagnostics = await collectLspDiagnostics(entryPath);
+        const publishedDiagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(compilerDiagnostics.filter((candidate) => candidate.code === "NAM002")).toHaveLength(2);
+        expect(publishedDiagnostics.filter((candidate) => candidate.code === "NAM002")).toHaveLength(1);
+        expect(publishedDiagnostics.find((candidate) => candidate.code === "NAM002")?.range.start.line).toBe(2);
+      },
+    );
+  });
+
+  test("does not suppress non-matching diagnostic codes for rank-ignore docs", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": [
+          "/// rank-ignore TYP005",
+          "value = missing_value",
+          "pub main = || value",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const publishedDiagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(publishedDiagnostics.some((candidate) => candidate.code === "NAM002")).toBe(true);
+      },
+    );
+  });
+
+  test("publishes loader diagnostics for duplicate pub use collisions", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": [
+          "pub use super::app::{ main }",
+          "",
+          "pub main = || main",
+          "",
+        ].join("\n"),
+        "app.rank": "pub main = || 1\n",
+      },
+      async (entryPath) => {
+        const compilerDiagnostics = await collectRawEditorDiagnostics(entryPath);
+        const publishedDiagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(compilerDiagnostics.find((candidate) => candidate.code === "MOD005")?.message).toContain(
+          "Cannot re-export value main because the current module already exports it.",
+        );
+        expect(publishedDiagnostics.find((candidate) => candidate.code === "MOD005")?.message).toContain(
+          "Cannot re-export value main because the current module already exports it.",
+        );
+      },
+    );
+  });
+
+  test("suppresses entrypoint diagnostics with rank-ignore when the compiler reports a declaration span", async () => {
+    const filePath = serverRuntimeFixturePath("invalid-handler-arity", "main.rank");
+    const compilerDiagnostics = await collectRawEditorDiagnostics(filePath);
+    const publishedDiagnostics = await collectPublishedDiagnostics(filePath);
+
+    expect(compilerDiagnostics.find((candidate) => candidate.code === "TYP030")?.range.start.line).toBe(1);
+    expect(publishedDiagnostics.find((candidate) => candidate.code === "TYP030")).toBeUndefined();
+  });
+
+  test("suppresses missing entrypoint diagnostics with rank-ignore when the compiler anchors them to the first declaration", async () => {
+    const filePath = serverRuntimeFixturePath("missing-handler", "main.rank");
+    const compilerDiagnostics = await collectRawEditorDiagnostics(filePath);
+    const publishedDiagnostics = await collectPublishedDiagnostics(filePath);
+
+    expect(compilerDiagnostics.find((candidate) => candidate.code === "TYP030")?.range.start.line).toBe(1);
+    expect(publishedDiagnostics.find((candidate) => candidate.code === "TYP030")).toBeUndefined();
+  });
+
+  test("suppresses multiple diagnostic codes from a single rank-ignore doc line", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": [
+          "/// rank-ignore NAM002 NAM005",
+          "value: Missing<string> = missing_value",
+          "pub main = || value",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const compilerDiagnostics = await collectLspDiagnostics(entryPath);
+        const publishedDiagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(compilerDiagnostics.some((candidate) => candidate.code === "NAM002")).toBe(true);
+        expect(compilerDiagnostics.some((candidate) => candidate.code === "NAM005")).toBe(true);
+        expect(publishedDiagnostics.some((candidate) => candidate.code === "NAM002")).toBe(false);
+        expect(publishedDiagnostics.some((candidate) => candidate.code === "NAM005")).toBe(false);
+      },
+    );
+  });
+
+  test("reports serve-surface config diagnostics to the compiler and suppresses them from published output when ignored", async () => {
+    const filePath = serverRuntimeFixturePath("invalid-config-value", "main.rank");
+    const compilerDiagnostics = await collectRawEditorDiagnostics(filePath);
+    const publishedDiagnostics = await collectPublishedDiagnostics(filePath);
+    const diagnostic = compilerDiagnostics.find((candidate) => candidate.code === "SRV004");
+
+    expect(diagnostic).toBeDefined();
+    expect(diagnostic?.message).toContain("Server app pub config must be an object literal or zero-argument function when exported.");
+    expect(publishedDiagnostics.find((candidate) => candidate.code === "SRV004")).toBeUndefined();
+  });
+
+  test("reports serve-surface config-arity diagnostics to the compiler and suppresses them from published output when ignored", async () => {
+    const filePath = serverRuntimeFixturePath("invalid-config-arity", "main.rank");
+    const compilerDiagnostics = await collectRawEditorDiagnostics(filePath);
+    const publishedDiagnostics = await collectPublishedDiagnostics(filePath);
+    const diagnostic = compilerDiagnostics.find((candidate) => candidate.code === "SRV004");
+
+    expect(diagnostic).toBeDefined();
+    expect(diagnostic?.message).toContain("Server app pub config must be an object literal or zero-argument function when exported.");
+    expect(publishedDiagnostics.find((candidate) => candidate.code === "SRV004")).toBeUndefined();
+  });
+
+  test("shows contextual hover for invalid serve config functions", async () => {
+    const filePath = serverRuntimeFixturePath("invalid-config-arity", "main.rank");
+    const hover = await collectHover(filePath, "config =", 1);
+
+    expect(hover).toEqual({
+      contents: {
+        kind: "markdown",
+        value: [
+          "```rank",
+          'config: (unknown) -> Object { defaultResponseFormat: "json", env: unknown }',
+          "```",
+          "",
+          "Serve config expects `HTTP::AppConfig` or `() -> HTTP::AppConfig`.",
+          "",
+          "This binding is invalid for serve-time `pub config`: it must be an object literal or zero-argument function.",
+        ].join("\n"),
+      },
+    });
+  });
+
+  test("map call arity errors to the call expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "helper = |value: number| {\n  return value\n}\nresult = helper()\npub main = || result\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP004");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(3);
+      },
+    );
+  });
+
+  test("map field access errors to the field access expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "value = {\n  port: 8080,\n}\nresult = value.host\npub main = || result\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP007");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(3);
+      },
+    );
+  });
+
+  test("map operator errors to the operator expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "left = `one`\nright = 1\nresult = left + right\npub main = || result\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP011");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(2);
+      },
+    );
+  });
+
+  test("map argument type errors to the offending argument expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::object::{ mapValues }\n\nmapped = mapValues({\n  https: 443,\n}, |value: number| {\n  return value + 1\n})\n\npub main = || mapped\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP005");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(4);
+      },
+    );
+  });
+
+  test("map imported function parameter labels to related information", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use root::helpers::id\nresult = id(1)\npub main = || result\n",
+        "helpers.rank": "pub id = |value: string| -> string {\n  return value\n}\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP005");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(1);
+        expect(diagnostic?.relatedInformation).toEqual([
+          {
+            location: {
+              uri: pathToFileURL(path.join(path.dirname(entryPath), "helpers.rank")).href,
+              range: {
+                start: { line: 0, character: 17 },
+                end: { line: 0, character: 23 },
+              },
+            },
+            message: "parameter 1 expects string",
+          },
+        ]);
+      },
+    );
+  });
+
+  test("map Env diagnostics to the offending call argument", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::Env\nSchema = Object {\n  PORT: string,\n}\nenv = Env<Schema> {\n  extra: `value`,\n}\npub main = || env\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP024");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(4);
+      },
+    );
+  });
+
+  test("map File::Read diagnostics to the offending field expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::File\nConfig = Object {\n  value: string,\n}\nconfig = File::Read<Config> {\n  path: `config.json`,\n  format: `json`,\n}\npub main = || config\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP025");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(5);
+      },
+    );
+  });
+
+  test("map HTTP::Fetch diagnostics to the offending field expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "use std::HTTP\nBody = Object {\n  value: string,\n}\nresponse = HTTP::Fetch<Body> {\n  url: `https://api.example.com/data`,\n  method: `GET`,\n  headers: { accept: 1 },\n  cacheKey: `response`,\n}\npub main = || response\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP026");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(7);
+      },
+    );
+  });
+
+  test("map string interpolation errors to the interpolated expression", async () => {
+    await withTempRankProject(
+      {
+        "main.rank": "name = `svc`\nport = { value: 8080 }\nvalue = `${name}:${port}`\npub main = || value\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        const diagnostic = diagnostics.find((candidate) => candidate.code === "TYP022");
+
+        expect(diagnostic).toBeDefined();
+        expect(diagnostic?.range.start.line).toBe(2);
+      },
+    );
+  });
+
+  test("provider package modules do not require pub main", async () => {
+    const toml = [
+      "manifestVersion = 1",
+      "[package]",
+      'name = "my-provider"',
+      'version = "0.1.0"',
+      'source = "."',
+      "[provider]",
+      'namespace = "my-provider"',
+      'runtime = "node"',
+      'entry = "./dist/provider.js"',
+    ].join("\n");
+
+    await withTempRankProject(
+      {
+        "rank.toml": toml,
+        "types.rank": "pub MyType = Object { value: string }\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectLspDiagnostics(entryPath);
+        expect(diagnostics.find((d) => d.code === "TYP030")).toBeUndefined();
+      },
+      "types.rank",
+    );
+  });
+
+  test("admits stubbed backend provider capabilities for test fixtures", async () => {
+    const filePath = examplePath("tests", "provider-backend-stub", "src", "main.rank");
+    const diagnostics = await collectPublishedDiagnostics(filePath);
+
+    expect(diagnostics.find((candidate) => candidate.code === "TYP027")).toBeUndefined();
+  });
+
+  test("applies manifest provider capability defaults to editor diagnostics", async () => {
+    await withTempRankProject(
+      {
+        "rank.toml": [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "lsp-provider-defaults"',
+          'version = "0.1.0"',
+          'source = "src"',
+          "",
+          "[providers]",
+          'api = { path = "./providers/api" }',
+          "",
+          "[security]",
+          'allow-provider-capabilities = ["network"]',
+          "",
+        ].join("\n"),
+        "src/main.rank": [
+          "use api::users::{ lookup }",
+          "",
+          "pub main = || lookup({ id: `123`, cacheKey: `lookup-123` })",
+          "",
+        ].join("\n"),
+        "providers/api/rank.toml": [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "api-provider"',
+          'version = "0.1.0"',
+          'source = "."',
+          "",
+          "[provider]",
+          'namespace = "api"',
+          'runtime = "node"',
+          'entry = "./dist/provider.js"',
+          "",
+          "[[provider.exports]]",
+          'name = "users::lookup"',
+          'kind = "backend"',
+          'inputSchema = "Object { id: string, cacheKey: string }"',
+          'outputSchema = "Object { name: string }"',
+          'capabilities = ["network"]',
+          'reproducibility = ["cacheKey"]',
+          "",
+        ].join("\n"),
+        "providers/api/dist/provider.js": "export const provider = true;\n",
+      },
+      async (entryPath) => {
+        const diagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(diagnostics.find((candidate) => candidate.code === "TYP027")).toBeUndefined();
+      },
+      "src/main.rank",
+    );
+  });
+
+  test("refreshes published diagnostics after rank.toml security defaults change", async () => {
+    const providerDirectory = providerFixturePath("provider-network-backend", "providers", "api");
+
+    await withTempRankProject(
+      {
+        "rank.toml": [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "lsp-provider-refresh"',
+          'version = "0.1.0"',
+          'source = "src"',
+          "",
+          "[providers]",
+          `api = { path = ${JSON.stringify(providerDirectory)} }`,
+          "",
+        ].join("\n"),
+        "src/main.rank": [
+          "use api::users::{ lookup }",
+          "",
+          "pub main = || lookup({ id: `123`, cacheKey: `lookup-123` })",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const session = new ProjectSession();
+        const published = new Map<string, ReturnType<typeof toLspDiagnostic>[]>();
+        const connection = {
+          sendDiagnostics(params: { uri: string; diagnostics: ReturnType<typeof toLspDiagnostic>[] }) {
+            published.set(params.uri, params.diagnostics);
+          },
+        } as Pick<Connection, "sendDiagnostics"> as Connection;
+        const entryUri = pathToFileURL(path.resolve(entryPath)).href;
+        const manifestPath = path.join(path.dirname(path.dirname(entryPath)), "rank.toml");
+
+        await publishDiagnostics(connection, session, entryPath);
+
+        expect(published.get(entryUri)?.find((candidate) => candidate.code === "TYP027")).toBeDefined();
+
+        await writeFile(manifestPath, [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "lsp-provider-refresh"',
+          'version = "0.1.0"',
+          'source = "src"',
+          "",
+          "[providers]",
+          `api = { path = ${JSON.stringify(providerDirectory)} }`,
+          "",
+          "[security]",
+          'allow-provider-capabilities = ["network"]',
+          "",
+        ].join("\n"), "utf8");
+
+        session.invalidate(manifestPath);
+        await publishDiagnostics(connection, session, entryPath);
+
+        expect(published.get(entryUri)?.find((candidate) => candidate.code === "TYP027")).toBeUndefined();
+      },
+      "src/main.rank",
+    );
+  });
+
+  test("applies manifest HTTP host allowlist defaults to editor diagnostics", async () => {
+    await withTempRankProject(
+      {
+        "rank.toml": [
+          "manifestVersion = 1",
+          "",
+          "[package]",
+          'name = "lsp-http-allowlist"',
+          'version = "0.1.0"',
+          'source = "src"',
+          "",
+          "[security]",
+          'allow-http-hosts = ["api.example.com"]',
+          "",
+        ].join("\n"),
+        "src/main.rank": [
+          "use std::HTTP",
+          "",
+          "Body = Object {",
+          "  value: string,",
+          "}",
+          "",
+          "response = HTTP::Fetch<Body> {",
+          "  url: `https://blocked.example.com/data`,",
+          "  method: `GET`,",
+          "  cacheKey: `response`,",
+          "}",
+          "",
+          "pub main = || response",
+          "",
+        ].join("\n"),
+      },
+      async (entryPath) => {
+        const diagnostics = await collectPublishedDiagnostics(entryPath);
+
+        expect(diagnostics.find((candidate) => candidate.code === "TYP031")).toBeDefined();
+      },
+      "src/main.rank",
+    );
+  });
+
+  test("shows provider schema hover for imported backend exports", async () => {
+    const filePath = examplePath("tests", "provider-backend-stub", "src", "main.rank");
+    const hover = await collectHover(filePath, "lookup({", 1);
+
+    expect(hover).toEqual({
+      contents: {
+        kind: "markdown",
+        value: "```rank\nlookup: (Object { id: string, cacheKey: string }) -> Object { name: string }\n```",
+      },
+    });
+  });
+
+});