@formspec/language-server 0.1.0-alpha.21 → 0.1.0-alpha.23

package/dist/language-server.d.ts

@@ -10,7 +10,8 @@
  * LSP process, while TypeScript-project-aware semantics are supplied by
  * `@formspec/ts-plugin` over a local manifest + IPC transport.
  *
- * Diagnostics are intentionally omitted per design decision A7.
+ * The packaged server acts as a reference implementation over the composable
+ * completion, hover, and diagnostics helpers exported from this package.
  *
  * @example
  * ```ts
@@ -25,9 +26,17 @@
 
 import { CompletionItem } from 'vscode-languageserver/node.js';
 import { Connection } from 'vscode-languageserver/node.js';
+import { Diagnostic } from 'vscode-languageserver/node.js';
 import type { ExtensionDefinition } from '@formspec/core';
 import type { Hover } from 'vscode-languageserver/node.js';
 import type { Location } from 'vscode-languageserver/node.js';
+import type { TextDocument } from 'vscode-languageserver-textdocument';
+
+/** @public */
+export declare interface CommentSpan {
+    readonly start: number;
+    readonly end: number;
+}
 
 /**
  * Creates and configures the FormSpec language server connection.
@@ -54,6 +63,51 @@ export declare interface CreateServerOptions {
     readonly usePluginTransport?: boolean;
     /** IPC timeout, in milliseconds, for semantic plugin requests. */
     readonly pluginQueryTimeoutMs?: number;
+    /** Optional diagnostics publishing mode for the packaged reference LSP. */
+    readonly diagnosticsMode?: "off" | "plugin";
+    /** Source label to use when publishing plugin-derived diagnostics. */
+    readonly diagnosticSource?: string;
+}
+
+/**
+ * File-local diagnostic derived from comment parsing or semantic analysis.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnostic {
+    readonly code: string;
+    readonly category: FormSpecAnalysisDiagnosticCategory;
+    readonly message: string;
+    readonly range: CommentSpan;
+    readonly severity: "error" | "warning" | "info";
+    readonly relatedLocations: readonly FormSpecAnalysisDiagnosticLocation[];
+    readonly data: Record<string, FormSpecAnalysisDiagnosticDataValue>;
+}
+
+/**
+ * Machine-readable diagnostic category used by FormSpec tooling surfaces.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticCategory = "tag-recognition" | "value-parsing" | "type-compatibility" | "target-resolution" | "constraint-validation" | "infrastructure";
+
+/**
+ * Primitive structured values carried in diagnostic facts for white-label
+ * downstream rendering.
+ *
+ * @public
+ */
+export declare type FormSpecAnalysisDiagnosticDataValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+
+/**
+ * Additional source location associated with a diagnostic.
+ *
+ * @public
+ */
+export declare interface FormSpecAnalysisDiagnosticLocation {
+    readonly filePath: string;
+    readonly range: CommentSpan;
+    readonly message?: string;
 }
 
 /**
@@ -80,4 +134,33 @@ export declare function getDefinition(): Location | null;
  */
 export declare function getHoverForTag(tagName: string, extensions?: readonly ExtensionDefinition[]): Hover | null;
 
+/**
+ * Retrieves canonical FormSpec diagnostics for the current document revision
+ * from the plugin transport. Returns `null` when the transport is missing,
+ * stale, or invalid.
+ *
+ * @public
+ */
+export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
+
+/**
+ * Converts canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * Downstream consumers that want complete white-label control can ignore this
+ * helper and render their own messages from `code` + `data`.
+ *
+ * @public
+ */
+export declare function toLspDiagnostics(document: TextDocument, diagnostics: readonly FormSpecAnalysisDiagnostic[], options?: ToLspDiagnosticsOptions): Diagnostic[];
+
+/**
+ * Options for converting canonical FormSpec diagnostics into LSP diagnostics.
+ *
+ * @public
+ */
+export declare interface ToLspDiagnosticsOptions {
+    /** Source label shown by LSP clients. Defaults to `formspec`. */
+    readonly source?: string;
+}
+
 export { }

package/dist/plugin-client.d.ts

@@ -1,5 +1,13 @@
-import { type FormSpecSerializedCompletionContext, type FormSpecSerializedHoverInfo } from "@formspec/analysis/protocol";
+import { type FormSpecAnalysisDiagnostic, type FormSpecSerializedCompletionContext, type FormSpecSerializedHoverInfo } from "@formspec/analysis/protocol";
 export declare function fileUriToPathOrNull(uri: string): string | null;
 export declare function getPluginCompletionContextForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedCompletionContext | null>;
 export declare function getPluginHoverForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, offset: number, timeoutMs?: number): Promise<FormSpecSerializedHoverInfo | null>;
+/**
+ * Retrieves canonical FormSpec diagnostics for the current document revision
+ * from the plugin transport. Returns `null` when the transport is missing,
+ * stale, or invalid.
+ *
+ * @public
+ */
+export declare function getPluginDiagnosticsForDocument(workspaceRoots: readonly string[], filePath: string, documentText: string, timeoutMs?: number): Promise<readonly FormSpecAnalysisDiagnostic[] | null>;
 //# sourceMappingURL=plugin-client.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"plugin-client.d.ts","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAOL,KAAK,mCAAmC,EACxC,KAAK,2BAA2B,EAGjC,MAAM,6BAA6B,CAAC;AAwGrC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AAqBD,wBAAsB,qCAAqC,CACzD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,mCAAmC,GAAG,IAAI,CAAC,CAiBrD;AAED,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAiB7C"}
+{"version":3,"file":"plugin-client.d.ts","sourceRoot":"","sources":["../src/plugin-client.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,0BAA0B,EAE/B,KAAK,mCAAmC,EACxC,KAAK,2BAA2B,EAGjC,MAAM,6BAA6B,CAAC;AAyGrC,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM9D;AAqBD,wBAAsB,qCAAqC,CACzD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,mCAAmC,GAAG,IAAI,CAAC,CAiBrD;AAED,wBAAsB,yBAAyB,CAC7C,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,SAAkC,GAC1C,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC,CAiB7C;AAED;;;;;;GAMG;AACH,wBAAsB,+BAA+B,CACnD,cAAc,EAAE,SAAS,MAAM,EAAE,EACjC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAkC,GAC1C,OAAO,CAAC,SAAS,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAkBvD"}

package/dist/server.d.ts

@@ -6,7 +6,8 @@
  * - `textDocument/hover` — Documentation for recognized constraint tags
  * - `textDocument/definition` — Go-to-definition (stub, returns null)
  *
- * Diagnostics are intentionally omitted per design decision A7.
+ * The packaged language server is a reference implementation built on the same
+ * composable helpers that downstream consumers can call directly.
  */
 import { type Connection } from "vscode-languageserver/node.js";
 import type { ExtensionDefinition } from "@formspec/core";
@@ -24,6 +25,10 @@ export interface CreateServerOptions {
     readonly usePluginTransport?: boolean;
     /** IPC timeout, in milliseconds, for semantic plugin requests. */
     readonly pluginQueryTimeoutMs?: number;
+    /** Optional diagnostics publishing mode for the packaged reference LSP. */
+    readonly diagnosticsMode?: "off" | "plugin";
+    /** Source label to use when publishing plugin-derived diagnostics. */
+    readonly diagnosticSource?: string;
 }
 /**
  * Creates and configures the FormSpec language server connection.

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAKL,KAAK,UAAU,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAqD1D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAmF1E"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAML,KAAK,UAAU,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAsD1D;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,yEAAyE;IACzE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC5C,sEAAsE;IACtE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,UAAU,CAoI1E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formspec/language-server",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.23",
   "description": "Language server for FormSpec — completions, hover, and go-to-definition for JSDoc constraint tags",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,8 +20,8 @@
   "dependencies": {
     "vscode-languageserver": "^9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12",
-    "@formspec/analysis": "0.1.0-alpha.21",
-    "@formspec/core": "0.1.0-alpha.21"
+    "@formspec/analysis": "0.1.0-alpha.23",
+    "@formspec/core": "0.1.0-alpha.23"
   },
   "devDependencies": {
     "vitest": "^3.0.0"
@@ -38,12 +38,12 @@
   ],
   "license": "UNLICENSED",
   "scripts": {
-    "build": "tsup && tsc --emitDeclarationOnly && api-extractor run --local",
+    "build": "tsup && tsc --emitDeclarationOnly && pnpm run api-extractor:local",
     "clean": "rm -rf dist temp",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "api-extractor": "api-extractor run",
-    "api-extractor:local": "api-extractor run --local",
-    "api-documenter": "api-documenter markdown -i temp -o docs"
+    "api-extractor": "api-extractor run && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-extractor:local": "api-extractor run --local && node ../../scripts/normalize-generated-markdown.mjs api-report",
+    "api-documenter": "api-documenter markdown -i temp -o docs && node ../../scripts/normalize-generated-markdown.mjs docs"
   }
 }