@formspec/language-server 0.1.0-alpha.17 → 0.1.0-alpha.20

package/README.md

@@ -1,96 +1,31 @@
 # @formspec/language-server
 
-Language server protocol (LSP) features for FormSpec, providing editor intelligence for JSDoc constraint tags.
+Language-server support for FormSpec TSDoc tags.
 
-## Installation
+## Install
 
 ```bash
-npm install @formspec/language-server
-# or
 pnpm add @formspec/language-server
 ```
 
-## Requirements
+## Features
 
-This package is ESM-only and requires:
+- completion items for FormSpec tags
+- hover documentation for recognized tags
+- go-to-definition support for known tags
 
-```json
-// package.json
-{
-  "type": "module"
-}
-```
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext"
-  }
-}
-```
-
-## Overview
-
-This package provides language server features for FormSpec's JSDoc constraint tags (`@Minimum`, `@Maximum`, `@Pattern`, etc.). It can be integrated into any LSP-compatible editor.
-
-### Features
-
-- **Completion** — Autocomplete for constraint tag names inside JSDoc comments
-- **Hover** — Documentation on hover for constraint tags
-- **Go to Definition** — Navigate to constraint definitions _(placeholder — not yet implemented)_
-
-## API Reference
-
-### Functions
-
-| Function                  | Description                                     |
-| ------------------------- | ----------------------------------------------- |
-| `createServer()`          | Create a full LSP server connection             |
-| `getCompletionItems()`    | Get completion items for constraint tags        |
-| `getDefinition()`         | Get definition location for a constraint tag    |
-| `getHoverForTag(tagName)` | Get hover information for a constraint tag name |
-
-### `createServer()`
-
-Creates a Language Server Protocol connection that handles `initialize`, `textDocument/completion`, `textDocument/hover`, and `textDocument/definition` requests.
+Diagnostics are intentionally handled elsewhere; this package focuses on editor assistance.
 
-```typescript
-import { createServer } from "@formspec/language-server";
+## Usage
 
-const connection = createServer();
-connection.listen();
-```
-
-### `getCompletionItems()`
-
-Returns completion items for all known FormSpec constraint tags.
-
-```typescript
-import { getCompletionItems } from "@formspec/language-server";
-
-const items = getCompletionItems();
-// [{ label: "@Minimum", kind: CompletionItemKind.Keyword, ... }, ...]
-```
+```ts
+import { createServer, getCompletionItems, getHoverForTag } from "@formspec/language-server";
 
-### `getHoverForTag(tagName)`
-
-Returns hover documentation for a given tag name, or `null` if the tag is not recognized.
-
-```typescript
-import { getHoverForTag } from "@formspec/language-server";
-
-const hover = getHoverForTag("Minimum");
-// { contents: { kind: "markdown", value: "..." } }
+const server = createServer();
+const completions = getCompletionItems();
+const hover = getHoverForTag("minimum");
 ```
 
-## Editor Integration
-
-### VS Code
-
-Use with a VS Code extension that connects to the language server. The server communicates over the standard LSP protocol via `vscode-languageserver/node.js`.
-
 ## License
 
 UNLICENSED

package/dist/__tests__/plugin-client.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-client.test.d.ts.map

package/dist/__tests__/plugin-client.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/plugin-client.test.ts"],"names":[],"mappings":""}

package/dist/index.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
@@ -29,246 +39,83 @@ module.exports = __toCommonJS(index_exports);
 
 // src/server.ts
 var import_node2 = require("vscode-languageserver/node.js");
+var import_vscode_languageserver_textdocument = require("vscode-languageserver-textdocument");
 
 // src/providers/completion.ts
-var import_core = require("@formspec/core");
+var import_analysis = require("@formspec/analysis");
 var import_node = require("vscode-languageserver/node.js");
-var CONSTRAINT_DETAIL = {
-  minimum: "Minimum numeric value (inclusive). Example: `@minimum 0`",
-  maximum: "Maximum numeric value (inclusive). Example: `@maximum 100`",
-  exclusiveMinimum: "Minimum numeric value (exclusive). Example: `@exclusiveMinimum 0`",
-  exclusiveMaximum: "Maximum numeric value (exclusive). Example: `@exclusiveMaximum 100`",
-  multipleOf: "Value must be a multiple of this number. Example: `@multipleOf 0.01`",
-  minLength: "Minimum string length. Example: `@minLength 1`",
-  maxLength: "Maximum string length. Example: `@maxLength 255`",
-  minItems: "Minimum number of array items. Example: `@minItems 1`",
-  maxItems: "Maximum number of array items. Example: `@maxItems 10`",
-  uniqueItems: "Require all array items to be distinct. Example: `@uniqueItems`",
-  pattern: "Regular expression pattern for string validation. Example: `@pattern ^[a-z]+$`",
-  enumOptions: 'Inline JSON array of allowed enum values. Example: `@enumOptions ["a","b","c"]`',
-  const: 'Require a constant JSON value. Example: `@const "USD"`'
-};
 function getCompletionItems(extensions) {
-  const builtins = Object.keys(import_core.BUILTIN_CONSTRAINT_DEFINITIONS).map(
-    (name) => ({
-      label: `@${name}`,
-      kind: import_node.CompletionItemKind.Keyword,
-      detail: CONSTRAINT_DETAIL[name]
-    })
+  return (0, import_analysis.getConstraintTagDefinitions)(extensions).map((tag) => ({
+    label: `@${tag.canonicalName}`,
+    kind: import_node.CompletionItemKind.Keyword,
+    detail: tag.completionDetail
+  }));
+}
+function toCompletionItem(tag) {
+  return {
+    label: `@${tag.canonicalName}`,
+    kind: import_node.CompletionItemKind.Keyword,
+    detail: tag.completionDetail
+  };
+}
+function getCompletionItemsAtOffset(documentText, offset, extensions, semanticContext) {
+  if (semanticContext !== null && semanticContext !== void 0) {
+    if (semanticContext.kind === "target") {
+      return semanticContext.semantic.targetCompletions.map((target) => ({
+        label: target,
+        kind: target === "singular" || target === "plural" ? import_node.CompletionItemKind.EnumMember : import_node.CompletionItemKind.Field,
+        detail: `Target for @${semanticContext.semantic.tagName}`
+      }));
+    }
+    if (semanticContext.kind !== "tag-name") {
+      return [];
+    }
+    const normalizedPrefix2 = semanticContext.prefix.toLowerCase();
+    return semanticContext.availableTags.map(toCompletionItem).filter((item) => item.label.slice(1).toLowerCase().startsWith(normalizedPrefix2));
+  }
+  const resolvedContext = (0, import_analysis.getSemanticCommentCompletionContextAtOffset)(
+    documentText,
+    offset,
+    extensions ? { extensions } : void 0
   );
-  const customItems = extensions?.flatMap(
-    (extension) => (extension.constraintTags ?? []).map((tag) => ({
-      label: `@${tag.tagName}`,
-      kind: import_node.CompletionItemKind.Keyword,
-      detail: `Extension constraint tag from ${extension.extensionId}`
-    }))
-  ) ?? [];
-  return [...builtins, ...customItems];
+  if (resolvedContext.kind === "target") {
+    return resolvedContext.semantic.targetCompletions.map((target) => ({
+      label: target,
+      kind: target === "singular" || target === "plural" ? import_node.CompletionItemKind.EnumMember : import_node.CompletionItemKind.Field,
+      detail: `Target for @${resolvedContext.semantic.tag.normalizedTagName}`
+    }));
+  }
+  if (resolvedContext.kind !== "tag-name") {
+    return [];
+  }
+  const normalizedPrefix = resolvedContext.prefix.toLowerCase();
+  return resolvedContext.availableTags.map(toCompletionItem).filter((item) => item.label.slice(1).toLowerCase().startsWith(normalizedPrefix));
 }
 
 // src/providers/hover.ts
-var import_core2 = require("@formspec/core");
-var CONSTRAINT_HOVER_DOCS = {
-  minimum: [
-    "**@minimum** `<number>`",
-    "",
-    "Sets an inclusive lower bound on a numeric field.",
-    "",
-    "Maps to `minimum` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @minimum 0 */",
-    "amount: number;",
-    "```"
-  ].join("\n"),
-  maximum: [
-    "**@maximum** `<number>`",
-    "",
-    "Sets an inclusive upper bound on a numeric field.",
-    "",
-    "Maps to `maximum` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @maximum 100 */",
-    "percentage: number;",
-    "```"
-  ].join("\n"),
-  exclusiveMinimum: [
-    "**@exclusiveMinimum** `<number>`",
-    "",
-    "Sets an exclusive lower bound on a numeric field.",
-    "",
-    "Maps to `exclusiveMinimum` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @exclusiveMinimum 0 */",
-    "positiveAmount: number;",
-    "```"
-  ].join("\n"),
-  exclusiveMaximum: [
-    "**@exclusiveMaximum** `<number>`",
-    "",
-    "Sets an exclusive upper bound on a numeric field.",
-    "",
-    "Maps to `exclusiveMaximum` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @exclusiveMaximum 1 */",
-    "ratio: number;",
-    "```"
-  ].join("\n"),
-  multipleOf: [
-    "**@multipleOf** `<number>`",
-    "",
-    "Requires the numeric value to be a multiple of the given number.",
-    "",
-    "Maps to `multipleOf` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @multipleOf 0.01 */",
-    "price: number;",
-    "```"
-  ].join("\n"),
-  minLength: [
-    "**@minLength** `<number>`",
-    "",
-    "Sets a minimum character length on a string field.",
-    "",
-    "Maps to `minLength` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @minLength 1 */",
-    "name: string;",
-    "```"
-  ].join("\n"),
-  maxLength: [
-    "**@maxLength** `<number>`",
-    "",
-    "Sets a maximum character length on a string field.",
-    "",
-    "Maps to `maxLength` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @maxLength 255 */",
-    "description: string;",
-    "```"
-  ].join("\n"),
-  minItems: [
-    "**@minItems** `<number>`",
-    "",
-    "Sets a minimum number of items in an array field.",
-    "",
-    "Maps to `minItems` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @minItems 1 */",
-    "tags: string[];",
-    "```"
-  ].join("\n"),
-  maxItems: [
-    "**@maxItems** `<number>`",
-    "",
-    "Sets a maximum number of items in an array field.",
-    "",
-    "Maps to `maxItems` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @maxItems 10 */",
-    "tags: string[];",
-    "```"
-  ].join("\n"),
-  uniqueItems: [
-    "**@uniqueItems**",
-    "",
-    "Requires all items in an array field to be distinct.",
-    "",
-    "Maps to `uniqueItems` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @uniqueItems */",
-    "tags: string[];",
-    "```"
-  ].join("\n"),
-  pattern: [
-    "**@pattern** `<regex>`",
-    "",
-    "Sets a regular expression pattern that a string field must match.",
-    "",
-    "Maps to `pattern` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    "/** @pattern ^[a-z0-9]+$ */",
-    "slug: string;",
-    "```"
-  ].join("\n"),
-  enumOptions: [
-    "**@enumOptions** `<json-array>`",
-    "",
-    "Specifies the allowed values for an enum field as an inline JSON array.",
-    "",
-    "Maps to `enum` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    '/** @enumOptions ["draft","sent","archived"] */',
-    "status: string;",
-    "```"
-  ].join("\n"),
-  const: [
-    "**@const** `<json-literal>`",
-    "",
-    "Requires the field value to equal a single constant JSON value.",
-    "",
-    "Maps to `const` in JSON Schema.",
-    "",
-    "**Example:**",
-    "```typescript",
-    '/** @const "USD" */',
-    "currency: string;",
-    "```"
-  ].join("\n")
-};
+var import_analysis2 = require("@formspec/analysis");
 function getHoverForTag(tagName, extensions) {
   const raw = tagName.startsWith("@") ? tagName.slice(1) : tagName;
-  const name = (0, import_core2.normalizeConstraintTagName)(raw);
-  if (!(0, import_core2.isBuiltinConstraintName)(name)) {
-    const registration = extensions?.flatMap(
-      (extension) => (extension.constraintTags ?? []).map((tag) => ({
-        extensionId: extension.extensionId,
-        tag
-      }))
-    ).find(({ tag }) => tag.tagName === name);
-    if (registration === void 0) {
-      return null;
+  const definition = (0, import_analysis2.getTagDefinition)((0, import_analysis2.normalizeFormSpecTagName)(raw), extensions);
+  if (!definition) {
+    return null;
+  }
+  return {
+    contents: {
+      kind: "markdown",
+      value: definition.hoverMarkdown
     }
-    return {
-      contents: {
-        kind: "markdown",
-        value: [
-          `**@${registration.tag.tagName}** \`<value>\``,
-          "",
-          `Extension-defined constraint tag from \`${registration.extensionId}\`.`,
-          "",
-          "Validated through the registered FormSpec extension surface."
-        ].join("\n")
-      }
-    };
+  };
+}
+function getHoverAtOffset(documentText, offset, extensions, semanticHover) {
+  const hoverInfo = semanticHover ?? (0, import_analysis2.getCommentHoverInfoAtOffset)(documentText, offset, extensions ? { extensions } : void 0);
+  if (hoverInfo === null) {
+    return null;
   }
   return {
     contents: {
       kind: "markdown",
-      value: CONSTRAINT_HOVER_DOCS[name]
+      value: hoverInfo.markdown
     }
   };
 }
@@ -278,16 +125,172 @@ function getDefinition() {
   return null;
 }
 
+// src/plugin-client.ts
+var import_promises = __toESM(require("fs/promises"), 1);
+var import_node_net = __toESM(require("net"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_analysis3 = require("@formspec/analysis");
+var DEFAULT_PLUGIN_QUERY_TIMEOUT_MS = 2e3;
+function getManifestPath(workspaceRoot) {
+  return (0, import_analysis3.getFormSpecManifestPath)(workspaceRoot);
+}
+function normalizeWorkspaceRoot(root) {
+  const resolved = import_node_path.default.resolve(root);
+  const parsed = import_node_path.default.parse(resolved);
+  let normalized = resolved;
+  while (normalized.length > parsed.root.length && normalized.endsWith(import_node_path.default.sep)) {
+    normalized = normalized.slice(0, -import_node_path.default.sep.length);
+  }
+  return normalized;
+}
+function getMatchingWorkspaceRoot(workspaceRoots, filePath) {
+  const normalizedFilePath = import_node_path.default.resolve(filePath);
+  const normalizedRoots = [...workspaceRoots].map(normalizeWorkspaceRoot).sort((left, right) => right.length - left.length);
+  return normalizedRoots.find(
+    (workspaceRoot) => normalizedFilePath === workspaceRoot || normalizedFilePath.startsWith(`${workspaceRoot}${import_node_path.default.sep}`)
+  ) ?? null;
+}
+async function readManifest(workspaceRoot) {
+  try {
+    const manifestText = await import_promises.default.readFile(getManifestPath(workspaceRoot), "utf8");
+    const manifest = JSON.parse(manifestText);
+    if (!(0, import_analysis3.isFormSpecAnalysisManifest)(manifest)) {
+      return null;
+    }
+    return manifest;
+  } catch {
+    return null;
+  }
+}
+async function sendSemanticQuery(manifest, query, timeoutMs = DEFAULT_PLUGIN_QUERY_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    const socket = import_node_net.default.createConnection(manifest.endpoint.address);
+    let buffer = "";
+    let settled = false;
+    const finish = (response) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      socket.removeAllListeners("data");
+      socket.destroy();
+      resolve(response);
+    };
+    socket.setTimeout(timeoutMs, () => {
+      finish(null);
+    });
+    socket.setEncoding("utf8");
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify(query)}
+`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += String(chunk);
+      const newlineIndex = buffer.indexOf("\n");
+      if (newlineIndex < 0) {
+        return;
+      }
+      const payload = buffer.slice(0, newlineIndex);
+      buffer = buffer.slice(newlineIndex + 1);
+      try {
+        const response = JSON.parse(payload);
+        finish((0, import_analysis3.isFormSpecSemanticResponse)(response) ? response : null);
+      } catch {
+        finish(null);
+      }
+    });
+    socket.on("error", () => {
+      finish(null);
+    });
+    socket.on("close", () => {
+      finish(null);
+    });
+  });
+}
+function fileUriToPathOrNull(uri) {
+  try {
+    return (0, import_node_url.fileURLToPath)(uri);
+  } catch {
+    return null;
+  }
+}
+async function sendFileQuery(workspaceRoots, filePath, query, timeoutMs = DEFAULT_PLUGIN_QUERY_TIMEOUT_MS) {
+  const workspaceRoot = getMatchingWorkspaceRoot(workspaceRoots, filePath);
+  if (workspaceRoot === null) {
+    return null;
+  }
+  const manifest = await readManifest(workspaceRoot);
+  if (manifest === null) {
+    return null;
+  }
+  return sendSemanticQuery(manifest, query, timeoutMs);
+}
+async function getPluginCompletionContextForDocument(workspaceRoots, filePath, documentText, offset, timeoutMs = DEFAULT_PLUGIN_QUERY_TIMEOUT_MS) {
+  const response = await sendFileQuery(
+    workspaceRoots,
+    filePath,
+    {
+      protocolVersion: import_analysis3.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+      kind: "completion",
+      filePath,
+      offset
+    },
+    timeoutMs
+  );
+  if (response?.kind !== "completion") {
+    return null;
+  }
+  return response.sourceHash === (0, import_analysis3.computeFormSpecTextHash)(documentText) ? response.context : null;
+}
+async function getPluginHoverForDocument(workspaceRoots, filePath, documentText, offset, timeoutMs = DEFAULT_PLUGIN_QUERY_TIMEOUT_MS) {
+  const response = await sendFileQuery(
+    workspaceRoots,
+    filePath,
+    {
+      protocolVersion: import_analysis3.FORMSPEC_ANALYSIS_PROTOCOL_VERSION,
+      kind: "hover",
+      filePath,
+      offset
+    },
+    timeoutMs
+  );
+  if (response?.kind !== "hover") {
+    return null;
+  }
+  return response.sourceHash === (0, import_analysis3.computeFormSpecTextHash)(documentText) ? response.hover : null;
+}
+
 // src/server.ts
+function dedupeWorkspaceRoots(workspaceRoots) {
+  return [...new Set(workspaceRoots)];
+}
+function getWorkspaceRootsFromInitializeParams(params) {
+  const workspaceFolders = params.workspaceFolders?.map((workspaceFolder) => fileUriToPathOrNull(workspaceFolder.uri)).filter((workspaceRoot) => workspaceRoot !== null) ?? [];
+  const rootUri = params.rootUri === null || params.rootUri === void 0 ? null : fileUriToPathOrNull(params.rootUri);
+  const rootPath = params.rootPath ?? null;
+  return dedupeWorkspaceRoots([
+    ...workspaceFolders,
+    ...rootUri === null ? [] : [rootUri],
+    ...rootPath === null ? [] : [rootPath]
+  ]);
+}
 function createServer(options = {}) {
   const connection = (0, import_node2.createConnection)(import_node2.ProposedFeatures.all);
-  connection.onInitialize(() => {
+  const documents = new import_node2.TextDocuments(import_vscode_languageserver_textdocument.TextDocument);
+  let workspaceRoots = [...options.workspaceRoots ?? []];
+  documents.listen(connection);
+  connection.onInitialize((params) => {
+    workspaceRoots = dedupeWorkspaceRoots([
+      ...getWorkspaceRootsFromInitializeParams(params),
+      ...workspaceRoots
+    ]);
     return {
       capabilities: {
         textDocumentSync: import_node2.TextDocumentSyncKind.Incremental,
         completionProvider: {
-          // Trigger completions inside JSDoc comments when `@` is typed
-          triggerCharacters: ["@"]
+          // Trigger completions inside JSDoc comments for tags and target specifiers
+          triggerCharacters: ["@", ":"]
         },
         hoverProvider: true,
         definitionProvider: true
@@ -298,11 +301,39 @@ function createServer(options = {}) {
       }
     };
   });
-  connection.onCompletion(() => {
-    return getCompletionItems(options.extensions);
+  connection.onCompletion(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return [];
+    }
+    const offset = document.offsetAt(params.position);
+    const documentText = document.getText();
+    const filePath = fileUriToPathOrNull(params.textDocument.uri);
+    const semanticContext = options.usePluginTransport === false || filePath === null ? null : await getPluginCompletionContextForDocument(
+      workspaceRoots,
+      filePath,
+      documentText,
+      offset,
+      options.pluginQueryTimeoutMs
+    );
+    return getCompletionItemsAtOffset(documentText, offset, options.extensions, semanticContext);
   });
-  connection.onHover((_params) => {
-    return getHoverForTag("", options.extensions);
+  connection.onHover(async (params) => {
+    const document = documents.get(params.textDocument.uri);
+    if (!document) {
+      return null;
+    }
+    const offset = document.offsetAt(params.position);
+    const documentText = document.getText();
+    const filePath = fileUriToPathOrNull(params.textDocument.uri);
+    const semanticHover = options.usePluginTransport === false || filePath === null ? null : await getPluginHoverForDocument(
+      workspaceRoots,
+      filePath,
+      documentText,
+      offset,
+      options.pluginQueryTimeoutMs
+    );
+    return getHoverAtOffset(documentText, offset, options.extensions, semanticHover);
   });
   connection.onDefinition((_params) => {
     return getDefinition();