@hydranium/conformance 1.0.0-next.24 → 1.0.0-next.241

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 {
@@ -76,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`. */
@@ -177,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({
@@ -273,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.
  *
@@ -79,12 +81,53 @@ export function resolveModel(model: ConformanceModel): ResolvedConformanceModel
 export interface EditSpec {
    /** Replacement model text; {@link Deferred} for the same reasons as `ConformanceModel.text`. */
    readonly to: Deferred<string>;
+   /** True of the root after the edit and false of `valid`'s root, so a check can tell the two apart. */
    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.
+ * across heads; every other field is a per-head opt-in.
  *
  * Requiring BOTH a valid and an invalid model is the false-green guard — a
  * vacuous "invalid" model that actually parses clean fails the diagnostics
@@ -98,13 +141,18 @@ 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).
+ * - `dependent` and `breakingEdit` — read by the **data slice only**.
+ * - `renderedDiagnostic` — read by the **LSP slice only**.
  *
- * Both extras are optional and their checks report *skipped* when absent,
- * rather than silently not running. Making either mandatory would defeat the
- * shared fixture: the head that ignores the field has to invent a value for it,
- * and the two heads' inventions drift apart until one fixture contradicts the
- * other. A required field that one head ignores does not produce a shared
- * fixture; it produces a misleading one.
+ * The opt-ins are optional and their checks report *skipped* when absent,
+ * rather than silently not running. Making any of them mandatory would defeat
+ * the shared fixture: the head that ignores the field has to invent a value
+ * for it, and the two heads' inventions drift apart until one fixture
+ * contradicts the other. A required field that one head ignores does not
+ * produce a shared fixture; it produces a misleading one.
  *
  * The GLSP fixture is separate (per-diagram-type, generic over the adopter
  * action type) — see `./glsp`.
@@ -114,9 +162,87 @@ export interface LanguageFixture {
    readonly invalid: ConformanceModel;
    /**
     * Optional: an edit plus its observability assertion. The data slice's
-    * round-trip and subscription-delivery checks run only when it is supplied.
+    * checks that need a second, observably different text run only when it is
+    * supplied.
     */
    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 replacement text for {@link valid} that changes what
+    * {@link dependent} shows, typically by breaking its reference into
+    * `valid`, so that the dependent reports a diagnostic. Read by the **data
+    * slice only**, and only with `dependent`.
+    *
+    * {@link edit} does not serve here: an edit that leaves the dependent as it
+    * was may send a watcher of the dependent nothing, as the framework's head
+    * suppresses an update that changes nothing observable. Supplying this is
+    * the claim that writing it makes a watched `dependent` receive an update
+    * event, which the check then holds to being a rebuild that names no
+    * client.
+    */
+   readonly breakingEdit?: Deferred<string>;
+   /**
+    * 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.
+ *
+ * `absentWithLocale` 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 once the 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;
 }