@hydranium/conformance 1.0.0-next.8 → 1.0.0-next.85

package/src/model.ts

@@ -82,6 +82,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 +138,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 +162,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: string;
+   /** 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;
 }