@hydranium/conformance 1.0.0-next.28 → 1.0.0-next.280

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;
 }

package/src/vitest/index.ts

@@ -57,7 +57,7 @@ const vitestRunner: ConformanceRunner = {
 export function runDataConformance<TTransfer extends TransferElement, TDiagnostic extends TransferDiagnostic = TransferDiagnostic>(
    options: DataConformanceOptions<TTransfer, TDiagnostic>
 ): void {
-   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'conformance: data-server', buildDataChecks(options));
+   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'data-server conformance', buildDataChecks(options));
 }
 
 /**
@@ -66,7 +66,7 @@ export function runDataConformance<TTransfer extends TransferElement, TDiagnosti
  * per language) and a ran-vs-skipped summary.
  */
 export function runLspConformance(options: LspConformanceOptions): void {
-   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'conformance: lsp', buildLspChecks(options));
+   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'lsp conformance', buildLspChecks(options));
 }
 
 /**
@@ -77,5 +77,5 @@ export function runLspConformance(options: LspConformanceOptions): void {
 export function runGlspConformance<TAction, TDriver extends GlspConformanceDriver<TAction>>(
    options: GlspConformanceOptions<TAction, TDriver>
 ): void {
-   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'conformance: glsp', buildGlspChecks(options));
+   emitConformanceSuite(vitestRunner, options.suiteTitle ?? 'glsp conformance', buildGlspChecks(options));
 }