@hydranium/conformance 1.0.0-next.11 → 1.0.0-next.112

package/src/lsp/index.ts

@@ -11,10 +11,11 @@
  * The `@hydranium/conformance/lsp` slice — protocol conformance for the LSP
  * head. The driver port is a STRUCTURAL minimum (`LspConformanceDriver`) that
  * `@hydranium/core/testing/node`'s `LspHarness` satisfies with NO adapter: the kit
- * names only `string`, plain coordinates, and tiny structural minima
+ * names only strings, plain coordinates, and tiny structural minima
  * (`{ message }`, `{ items }`, `{ capabilities }`), never
  * `vscode-languageserver-protocol` wire types, so the harness's richer return
- * types are assignable to the narrower port.
+ * types are assignable to the narrower port. An alias of `string` is still a
+ * string for that purpose and stays inside the rule; a wire type does not.
  *
  * **This slice does not read `LanguageFixture.edit` at all.** The didChange
  * check drives `valid → invalid` using `invalid.text`, so there is no
@@ -23,9 +24,21 @@
  */
 
 import assert from 'node:assert/strict';
+import type { Locale } from '@hydranium/protocol';
 import type { Harness } from '@hydranium/protocol/testing';
 import type { ConformanceCheck } from '../conformance-suite.js';
-import { type LanguageFixture, resolveDeferred, resolveModel } from '../model.js';
+import { type ConformanceModel, type LanguageFixture, resolveDeferred, resolveModel } from '../model.js';
+
+/**
+ * Structural minimum of the `initialize` params the kit sends — only `locale`,
+ * which is the one field a check needs to vary.
+ *
+ * A real `InitializeParams` is assignable to this, so a driver typed against
+ * upstream's shape satisfies the port with no adapter.
+ */
+export interface LspConformanceInitializeParams {
+   readonly locale?: Locale;
+}
 
 /** Structural minimum of an LSP `InitializeResult` — only the baseline capabilities the kit asserts. */
 export interface LspConformanceInitializeResult {
@@ -51,10 +64,20 @@ export interface LspConformanceDiagnostic {
    readonly message: string | { readonly value: string };
 }
 
-/** True when `diagnostic` carries a message in either LSP shape (plain string or markup). */
+/**
+ * True when `diagnostic` carries a NON-EMPTY message in either LSP shape
+ * (plain string or markup).
+ *
+ * Emptiness is part of the claim, not a refinement of it: `message: ''` is a
+ * diagnostic a user cannot act on, and a type-only test admits it — which
+ * makes "every diagnostic carries a message" pass for a head that publishes
+ * none. LSP declares the field required without forbidding the empty string,
+ * so nothing upstream rules it out either.
+ */
 function hasTextMessage(diagnostic: LspConformanceDiagnostic): boolean {
    const { message } = diagnostic;
-   return typeof message === 'string' || typeof message?.value === 'string';
+   const text = typeof message === 'string' ? message : message?.value;
+   return typeof text === 'string' && text.length > 0;
 }
 
 /**
@@ -66,8 +89,17 @@ function hasTextMessage(diagnostic: LspConformanceDiagnostic): boolean {
  * gives the kit the universal `dispose()` teardown.
  */
 export interface LspConformanceDriver extends Harness {
-   /** Drive the `initialize` → `initialized` handshake; resolve with the (structurally-minimal) result. */
-   initialize(): Promise<LspConformanceInitializeResult>;
+   /**
+    * Drive the `initialize` → `initialized` handshake; resolve with the
+    * (structurally-minimal) result.
+    *
+    * `params` is optional and every field in it is too, so a driver that ignores
+    * the argument entirely still satisfies this port — which is what keeps
+    * adding a field here from being a breaking change. `locale` is the reading
+    * user's language, declared by the client because only the client knows it;
+    * the render check below is the only caller that passes anything.
+    */
+   initialize(params?: LspConformanceInitializeParams): Promise<LspConformanceInitializeResult>;
    /** Send `didOpen` for `uri` with full `text` under `languageId`. */
    openDocument(uri: string, text: string, languageId: string, version?: number): void;
    /** Send `didChange` for `uri` as a single full-text replacement at `version`. */
@@ -167,7 +199,7 @@ export function buildLspChecks(options: LspConformanceOptions): ConformanceCheck
    });
 
    for (const language of options.languages) {
-      const { valid, invalid, completionPosition } = language;
+      const { valid, invalid, completionPosition, renderedDiagnostic } = language;
       const tag = `[${valid.languageId}]`;
 
       checks.push({
@@ -199,7 +231,7 @@ export function buildLspChecks(options: LspConformanceOptions): ConformanceCheck
                driver.openDocument(model.uri, model.text, model.languageId);
                const published = await diagnostics;
                assert.ok(published.length >= 1, 'didOpen(invalid) published no diagnostics');
-               assert.ok(published.every(hasTextMessage), 'a published diagnostic was missing a message');
+               assert.ok(published.every(hasTextMessage), 'a published diagnostic was missing a non-empty message');
             } finally {
                driver.dispose();
             }
@@ -263,7 +295,88 @@ export function buildLspChecks(options: LspConformanceOptions): ConformanceCheck
             skipReason: 'fixture supplied no completionPosition'
          });
       }
+
+      // Opt-in: server-side rendering runs only when the fixture names a locale
+      // and the sentence it expects in it. The framework ships no catalogue, so
+      // a server that renders nothing is CORRECT and must not be failed.
+      const renderTitle = `a diagnostic is published rendered in the locale initialize declared ${tag}`;
+      const renderControlTitle = `the same diagnostic is NOT rendered when no locale is declared ${tag}`;
+      if (renderedDiagnostic) {
+         checks.push({
+            title: renderTitle,
+            body: async () => {
+               const published = await publishedMessagesFor(connect, invalid, { locale: renderedDiagnostic.locale });
+               assert.ok(
+                  published.some(message => message.includes(renderedDiagnostic.expected)),
+                  `no published diagnostic contained ${JSON.stringify(renderedDiagnostic.expected)}: ${JSON.stringify(published)}`
+               );
+            }
+         });
+
+         // The second half of the pair. "Contains X" also passes for a server
+         // whose English contains X, and for one that renders whatever the
+         // locale — so the discriminating read is the fragment that must
+         // disappear. Reported as skipped rather than silently dropped when the
+         // fixture omits it, because a lone containment check IS weaker and a
+         // reader has to be able to see that from the report.
+         if (renderedDiagnostic.absentWithLocale) {
+            const { absentWithLocale } = renderedDiagnostic;
+            checks.push({
+               title: renderControlTitle,
+               body: async () => {
+                  const withLocale = await publishedMessagesFor(connect, invalid, { locale: renderedDiagnostic.locale });
+                  assert.ok(
+                     !withLocale.some(message => message.includes(absentWithLocale)),
+                     `a diagnostic still contained ${JSON.stringify(absentWithLocale)} with the locale declared: ${JSON.stringify(withLocale)}`
+                  );
+
+                  // And present without it, which is what rules out a fragment
+                  // that never appears in either state — a typo in the fixture
+                  // would otherwise make the assertion above pass for free.
+                  const withoutLocale = await publishedMessagesFor(connect, invalid);
+                  assert.ok(
+                     withoutLocale.some(message => message.includes(absentWithLocale)),
+                     `no diagnostic contained ${JSON.stringify(absentWithLocale)} with no locale declared, so it cannot witness the render: ${JSON.stringify(withoutLocale)}`
+                  );
+               }
+            });
+         } else {
+            checks.push({
+               title: renderControlTitle,
+               skipReason: 'fixture supplied no absentWithLocale, so the render check is a containment test only'
+            });
+         }
+      } else {
+         checks.push({ title: renderTitle, skipReason: 'fixture supplied no renderedDiagnostic (server-side rendering is opt-in)' });
+         checks.push({ title: renderControlTitle, skipReason: 'fixture supplied no renderedDiagnostic (server-side rendering is opt-in)' });
+      }
    }
 
    return checks;
 }
+
+/**
+ * Open `model` on a fresh driver and return the messages of the diagnostics
+ * published for it, as plain strings.
+ *
+ * A fresh driver per call because `initialize` is once-only per connection and
+ * the locale rides it — so the two states this compares cannot share one.
+ */
+async function publishedMessagesFor(
+   connect: LspConformanceOptions['connect'],
+   model: ConformanceModel,
+   params?: LspConformanceInitializeParams
+): Promise<string[]> {
+   const driver = await connect();
+   try {
+      await driver.initialize(params);
+      const resolved = resolveModel(model);
+      const diagnostics = driver.nextDiagnostics(resolved.uri);
+      driver.openDocument(resolved.uri, resolved.text, resolved.languageId);
+      return (await diagnostics).map(diagnostic =>
+         typeof diagnostic.message === 'string' ? diagnostic.message : (diagnostic.message?.value ?? '')
+      );
+   } finally {
+      driver.dispose();
+   }
+}

package/src/model.ts

@@ -7,6 +7,8 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import type { Locale } from '@hydranium/protocol';
+
 /**
  * A fixture value that may be given directly or DEFERRED to check time.
  *
@@ -82,6 +84,46 @@ export interface EditSpec {
    readonly expect: (root: unknown) => boolean;
 }
 
+/**
+ * A reference-picker query for an element that does not exist yet, plus the
+ * candidate the adopter expects it to offer.
+ *
+ * **The URI a create-element flow holds is a FOLDER**, because the file is not
+ * written until the dialog is confirmed. A folder URI names no file and so
+ * carries no extension, which is the one shape a head cannot route to a grammar
+ * by URI alone — it has to resolve the language some other way. That makes this
+ * the create dialog's load-bearing precondition and the reason the query is
+ * worth a conformance check of its own: a head that gets it wrong answers no
+ * candidates or throws, and the dialog never opens.
+ */
+export interface ReferenceQuerySpec {
+   /** AST type of the element being created — the synthetic source's own type. */
+   readonly type: string;
+   /** The reference property on the source (or on `syntheticPath`'s leaf) whose candidates the picker fills. */
+   readonly property: string;
+   /**
+    * Steps from the synthetic source down to the node holding `property`, when
+    * the reference is not on the source itself. Each step is
+    * `[containerProperty, type]` — the kit builds the `SyntheticStep`s, so the
+    * fixture names no protocol type.
+    */
+   readonly path?: ReadonlyArray<readonly [containerProperty: string, type: string]>;
+   /**
+    * Folder the create flow asks at. {@link Deferred} because a fixture may name
+    * a workspace the driver's `connect` only just created. Defaults to the parent
+    * of `valid.uri`, which is the folder a sibling of the valid model would go
+    * into — the common case, so most fixtures supply only `type` + `property`.
+    */
+   readonly folderUri?: Deferred<string>;
+   /**
+    * A candidate label the query MUST offer. Without it an empty result passes,
+    * and empty is exactly what the defect this check exists for produces — so
+    * the expectation is what makes the check discriminating rather than a
+    * smoke test.
+    */
+   readonly expectCandidate: string;
+}
+
 /**
  * The per-language fixture. `valid` and `invalid` are defined once and reused
  * across heads; the two extras are per-head opt-ins.
@@ -98,6 +140,9 @@ export interface EditSpec {
  *   uses `invalid.text` and never calls `edit.expect`, so an LSP-only adopter
  *   has nothing to supply here.
  * - `completionPosition` — read by the **LSP slice only**.
+ * - `referenceQuery` — read by the **data slice only**, and only when the
+ *   driver supplies `references` (the reference surface is opt-in on the head
+ *   too, so both halves have to be present for the check to run).
  *
  * Both extras are optional and their checks report *skipped* when absent,
  * rather than silently not running. Making either mandatory would defeat the
@@ -119,4 +164,67 @@ export interface LanguageFixture {
    readonly edit?: EditSpec;
    /** Optional: a position at which the LSP completion check requests completion. */
    readonly completionPosition?: { readonly line: number; readonly character: number };
+   /**
+    * Optional: the create-dialog reference query. Read by the **data slice
+    * only**, and only when the driver exposes the opt-in reference surface.
+    */
+   readonly referenceQuery?: ReferenceQuerySpec;
+   /**
+    * Optional: a second document that REFERENCES {@link valid}, so the data
+    * slice can provoke a CASCADE — a rebuild of this document caused by
+    * editing the one it points at, with its own text never touched.
+    *
+    * Opt-in because a grammar need not have cross-document references at all,
+    * and because only the adopter knows which pair of documents forms one.
+    * Supplying it IS the claim that editing `valid` rebuilds this document; the
+    * check then holds the head to reporting that on `onDocumentsBuilt`, which
+    * is the only channel that can carry it — the document has no subscriber and
+    * its file did not change, so neither the update channel nor a filesystem
+    * watcher can.
+    */
+   readonly dependent?: ConformanceModel;
+   /**
+    * Optional: a locale plus the sentence the server must publish in it. Read
+    * by the **LSP slice only**.
+    */
+   readonly renderedDiagnostic?: RenderedDiagnosticSpec;
+}
+
+/**
+ * A locale, and one sentence the server must produce in it for the `invalid`
+ * fixture.
+ *
+ * **Opt-in, and it has to be.** The framework ships no catalogue and selects no
+ * locale, so a server that installs no renderer correctly publishes English —
+ * mandating this check would fail every adopter without i18n for doing the right
+ * thing. Supplying the field is the adopter saying "I render server-side, hold me
+ * to it".
+ *
+ * `expected` is a SUBSTRING, not the whole message. The kit owns no grammar, so
+ * it cannot know how many diagnostics `invalid` produces or in what order, and
+ * an adopter should be able to pin the translated fragment without restating a
+ * sentence they may reword. A substring long enough to be wrong if the render
+ * did not happen is the whole requirement.
+ *
+ * `absentWithoutLocale` is what makes the check a pair rather than a single
+ * assertion: "the message contains X" also passes for a server whose English
+ * happens to contain X, and for one that renders regardless of locale. Naming
+ * the fragment that must DISAPPEAR when no locale is declared is what
+ * distinguishes those.
+ */
+export interface RenderedDiagnosticSpec {
+   /** The locale to declare at `initialize` — the tag whose catalogue the server has. */
+   readonly locale: Locale;
+   /** A fragment of the translated sentence, present in some diagnostic of the `invalid` fixture. */
+   readonly expected: string;
+   /**
+    * A fragment that must be absent once `locale` is declared, and present
+    * without it — normally a piece of the server's own English.
+    *
+    * Optional only because a catalogue may translate a message whose English
+    * shares no distinctive fragment with it. Omitting it drops the second half
+    * of the pair and leaves a check that a render-nothing server can pass; the
+    * kit reports that rather than pretending otherwise.
+    */
+   readonly absentWithLocale?: string;
 }