@istar-ts/core 0.10.1 → 0.12.0

package/dist/index.d.cts

@@ -128,6 +128,25 @@ export declare function validateModel(model: IstarModel): ModelIssue[];
 //#endregion
 //#region src/metamodels.d.ts
 export type ElementCategory = "actor" | "node";
+/**
+ * Presentation hints a kind may carry, as data (core never draws). `@istar-ts/react` uses them as
+ * the defaults for the kind: a shape as SVG path data, the label's text box, a link's line.
+ */
+export interface KindShape {
+  readonly path: string;
+  readonly viewBox?: string;
+}
+export interface KindTextBox {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface KindLine {
+  readonly dash?: string;
+  readonly marker?: string | false;
+  readonly markerFilled?: boolean;
+}
 export type LinkCategory = "actor" | "node" | "dependency";
 /** A resolved element kind of a metamodel. */
 export interface ElementKindDefinition<K extends string = string> {
@@ -145,6 +164,9 @@ export interface ElementKindDefinition<K extends string = string> {
   readonly pistarType: string;
   /** Name of the extension that declared it; absent for iStar 2.0 kinds. */
   readonly extension?: string;
+  /** Presentation hints (drawn by `@istar-ts/react`). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
@@ -184,6 +206,8 @@ export interface LinkKindDefinition<K extends string = string> {
   readonly check?: (context: LinkRuleContext) => LinkCheck;
   readonly pistarType: string;
   readonly extension?: string;
+  /** Presentation hint (drawn by `@istar-ts/react`). */
+  readonly line?: KindLine;
 }
 /** A metamodel: the element and link kinds a model may use, and their rules. */
 export interface Metamodel<EK extends string = ElementKind, LK extends string = LinkKind> {
@@ -222,6 +246,9 @@ export interface ElementKindDeclaration<K extends string = string> {
    * constructs as `istar.<Name>`, so `pistarType: 'istar.Planning'` reads its files.
    */
   readonly pistarType?: string;
+  /** Presentation hints, kept as data for renderers (`@istar-ts/react` draws them). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 export interface LinkKindDeclaration<K extends string = string> {
   readonly kind: K;
@@ -237,6 +264,8 @@ export interface LinkKindDeclaration<K extends string = string> {
   /** Default: that of `behavesLike`, else none (no fixed label, no changeable value). */
   readonly info?: LinkKindInfo;
   readonly pistarType?: string;
+  /** Presentation hint, kept as data for renderers (`@istar-ts/react` draws it). */
+  readonly line?: KindLine;
 }
 /** A named set of new kinds, applied to a metamodel with `extendMetamodel`. */
 export interface MetamodelExtension<NEK extends string = string, NLK extends string = string> {
@@ -381,6 +410,10 @@ export type AnyIstarModel = IstarModel<string, string>;
  * the association.
  */
 export declare function withMetamodel<EK extends string, LK extends string>(model: IstarModel<string, string>, metamodel: Metamodel<EK, LK>): IstarModel<EK, LK>;
+/** @internal Records the host part of a model's metamodel (used by serialization). */
+export declare function setHostMetamodel(model: object, metamodel: AnyMetamodel | undefined): void;
+/** @internal The host part of a model's metamodel, if the file declares the rest. */
+export declare function hostMetamodelOf(model: object): AnyMetamodel | undefined;
 /** Gives `to` the metamodel of `from` (used for every model an operation derives). */
 export declare function inheritMetamodel<M extends IstarModel<string, string>>(from: IstarModel<string, string>, to: M): M;
 export declare function createEmptyModel<EK extends string, LK extends string>(diagram: Diagram | undefined, options: {
@@ -416,6 +449,38 @@ export declare function dependencyLinksOf<EK extends string, LK extends string>(
   outbound?: IstarLink<LK>;
 };
 //#endregion
+//#region src/file-metamodel.d.ts
+/** The top-level key of the block in piStar JSON. */
+export declare const FILE_METAMODEL_KEY = "metamodel";
+export interface FileElementKind extends Omit<ElementKindDeclaration<string>, "info"> {
+  readonly info?: {
+    readonly canBeInnerElement?: boolean;
+    readonly canBeDependum?: boolean;
+    readonly canBeOnPaper?: boolean;
+  };
+  readonly [key: string]: unknown;
+}
+export interface FileLinkKind extends Omit<LinkKindDeclaration<string>, "check"> {
+  readonly [key: string]: unknown;
+}
+/** The `"metamodel"` block of a model file. */
+export interface FileMetamodel {
+  /** Identifies the constructs' dialect, e.g. `iStar4RationalAgents`. */
+  readonly name: string;
+  readonly elements?: readonly FileElementKind[];
+  readonly links?: readonly FileLinkKind[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Checks that `value` is a well-formed `"metamodel"` block and returns it typed. Throws
+ * `MetamodelError` naming the offending path (`metamodel.elements[1].kind must be a string`).
+ * Whether its kinds fit a given metamodel (namespacing, collisions, `behavesLike` targets) is
+ * checked when it is applied, by `extendMetamodel`.
+ */
+export declare function validateFileMetamodel(value: unknown, path?: string): FileMetamodel;
+/** The block as an extension `extendMetamodel` applies (it ignores the extra keys). */
+export declare function fileMetamodelExtension(block: FileMetamodel): MetamodelExtension<string, string>;
+//#endregion
 //#region src/serialization.d.ts
 export interface PistarElementJson {
   id: string;
@@ -494,12 +559,21 @@ export declare function inheritSourceLayout<M extends IstarModel<string, string>
  * `if (element.x && element.y)` silently drops them, which looks unintended.
  */
 export interface ParsePistarOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  /**
+   * Read the file's own `"metamodel"` block (see `FileMetamodel`) and parse with `metamodel`
+   * (or iStar 2.0) extended by it. Default false: the block is kept as an unknown key and not
+   * applied, as before. A block whose kinds collide with the metamodel throws `MetamodelError`.
+   */
+  readonly fileMetamodel?: boolean;
   /**
    * The metamodel whose kinds the file may use. Default iStar 2.0: any other `type` throws,
    * as in the piStar tool. The parsed model remembers it (see `metamodelOf`).
    */
   readonly metamodel?: Metamodel<EK, LK>;
 }
+export declare function parsePistar(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<string, string> & {
+  readonly fileMetamodel: true;
+}): IstarModel<string, string>;
 export declare function parsePistar<EK extends string, LK extends string>(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<EK, LK> & {
   readonly metamodel: Metamodel<EK, LK>;
 }): IstarModel<EK, LK>;
@@ -519,6 +593,19 @@ export interface ToPistarOptions {
 export declare function toPistarObject<EK extends string, LK extends string>(input: IstarModel<EK, LK>, options?: ToPistarOptions): PistarFile;
 /** Serializes a model to piStar's JSON text (2-space indentation, no trailing newline). */
 export declare function toPistar<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options?: ToPistarOptions): string;
+/**
+ * The constructs the model's file declares in its `"metamodel"` block, when they were applied
+ * (read with `fileMetamodel: true`, or set with `withFileMetamodel`); `undefined` otherwise.
+ * Kinds the host supplied are never part of it.
+ */
+export declare function fileMetamodelOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>): FileMetamodel | undefined;
+/**
+ * A copy of `model` whose file declares `block` (`null` removes the block): its metamodel is the
+ * host's extended by `block`, and `toPistar` writes the block. This is how a tool's "Add new"
+ * construct joins a model. Throws `MetamodelError` if the block is malformed, collides with the
+ * host's kinds, or leaves out a kind the model still uses.
+ */
+export declare function withFileMetamodel<EK extends string, LK extends string>(model: IstarModel<EK, LK>, block: FileMetamodel | null): IstarModel<string, string>;
 declare namespace operations_d_exports {
   export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, updateDiagram, updateElement, updateLink };
 }
@@ -821,4 +908,137 @@ export declare function defineProperties<const S extends PropertyShape, const Ki
 }): PropertySchema<S, Kind>;
 export declare function validateModelProperties<EK extends string, LK extends string>(model: IstarModel<EK, LK>, schemas: readonly PropertySchema<PropertyShape, string>[]): ModelPropertyIssue[];
 //#endregion
+//#region src/diagnostics.d.ts
+/**
+ * The Goal Model Diagnostics Protocol: findings about a model's elements and links, published by
+ * any analyser (a language server, a validator, a simulation…) and anchored by element id rather
+ * than by text position. Data only: diagnostics are never part of the model and are never
+ * written to disk.
+ *
+ * See goal-controller issue #24 (option D). Producers publish per source; consumers see the
+ * union of every source, deduplicated by `(elementId, key, message)`.
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** Most severe first. */
+export declare const DIAGNOSTIC_SEVERITIES: readonly DiagnosticSeverity[];
+/** A zero-based position in the producer's document (as in LSP). */
+export interface DiagnosticPosition {
+  readonly line: number;
+  readonly character: number;
+}
+export interface DiagnosticRange {
+  readonly start: DiagnosticPosition;
+  readonly end: DiagnosticPosition;
+}
+export interface GoalDiagnostic {
+  /** Id of the element or link the diagnostic is about. */
+  readonly elementId: string;
+  /** The custom property it is about; absent for the element as a whole. */
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  /** Who published it (e.g. `mutrose`, `goal-language`). */
+  readonly source?: string;
+  /** Where it was found in the producer's document, if it has one. */
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+  /** Producer data, passed through untouched. */
+  readonly data?: unknown;
+}
+/** Negative when `a` is more severe than `b`. */
+export declare function compareSeverity(a: DiagnosticSeverity, b: DiagnosticSeverity): number;
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+export declare function worstDiagnosticSeverity(diagnostics: readonly {
+  readonly severity: DiagnosticSeverity;
+}[] | undefined): DiagnosticSeverity | undefined;
+/**
+ * The union of several lists, in order, without duplicates: diagnostics with the same
+ * `(elementId, key, message)` count once, keeping the first one's position and the most severe
+ * severity among them.
+ */
+export declare function mergeDiagnostics(lists: Iterable<readonly GoalDiagnostic[] | undefined>): GoalDiagnostic[];
+/** Diagnostics by element (or link) id, each list in the input order. */
+export declare function groupDiagnostics(diagnostics: readonly GoalDiagnostic[] | undefined): ReadonlyMap<string, readonly GoalDiagnostic[]>;
+/**
+ * Holds the diagnostics of several sources. Each `publish` replaces that source's set, so a
+ * producer re-publishes everything it currently reports, as an LSP server does.
+ */
+export interface DiagnosticsStore {
+  /**
+   * Replaces `source`'s diagnostics (an empty list clears them). Entries without a `source` get
+   * this one.
+   */
+  publish(source: string, diagnostics: readonly GoalDiagnostic[]): void;
+  /** Removes one source's diagnostics, or every source's. */
+  clear(source?: string): void;
+  /** Sources with diagnostics, in the order they first published. */
+  sources(): readonly string[];
+  /** One source's diagnostics. */
+  get(source: string): readonly GoalDiagnostic[];
+  /**
+   * Every source's diagnostics, merged (see `mergeDiagnostics`). The same array until the next
+   * change, so it can back `useSyncExternalStore`.
+   */
+  getAll(): readonly GoalDiagnostic[];
+  subscribe(listener: () => void): () => void;
+}
+export declare function createDiagnosticsStore(): DiagnosticsStore;
+/**
+ * The parts of an LSP `Diagnostic` the adapter reads (structurally typed, so no LSP library is
+ * needed). The element is taken from `data.elementId`, or MutRoSe's `data.nodeId`; the property
+ * from `data.key`.
+ */
+export interface LspDiagnosticLike {
+  readonly range?: DiagnosticRange;
+  /** LSP numbering: 1 error, 2 warning, 3 information, 4 hint. */
+  readonly severity?: number;
+  readonly message: string | {
+    readonly value: string;
+  };
+  readonly source?: string;
+  readonly code?: string | number | {
+    readonly value: string | number;
+  };
+  readonly data?: unknown;
+}
+export interface FromLspOptions<D extends LspDiagnosticLike = LspDiagnosticLike> {
+  /**
+   * The element of a diagnostic whose `data` names none, e.g. by looking its range up in the
+   * document. Return `undefined` to drop it.
+   */
+  readonly elementIdFor?: (diagnostic: D) => string | undefined;
+  /**
+   * `'vscode'` for `vscode.Diagnostic` objects, whose severity counts from 0 (error) to 3
+   * (hint). Default `'lsp'`, the protocol's 1 to 4.
+   */
+  readonly severityNumbering?: "lsp" | "vscode";
+}
+/**
+ * One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
+ * names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
+ */
+export declare function fromLspDiagnostic(diagnostic: LspDiagnosticLike): GoalDiagnostic | undefined;
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+export declare function fromLspDiagnostics<D extends LspDiagnosticLike>(diagnostics: readonly D[], options?: FromLspOptions<D>): GoalDiagnostic[];
+/**
+ * The shape MutRoSe's VS Code extension posts to its webview: `{ nodeId, severity, message }`
+ * (plus `range` and `source`). `nodeId` is missing when no node could be found.
+ */
+export interface NodeIdDiagnostic {
+  readonly nodeId?: string;
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity | string;
+  readonly message: string;
+  readonly source?: string;
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+export declare function fromNodeIdDiagnostic(diagnostic: NodeIdDiagnostic): GoalDiagnostic | undefined;
+/**
+ * `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+ * without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+ */
+export declare function fromNodeIdDiagnostics(diagnostics: readonly NodeIdDiagnostic[]): GoalDiagnostic[];
+//#endregion
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -128,6 +128,25 @@ export declare function validateModel(model: IstarModel): ModelIssue[];
 //#endregion
 //#region src/metamodels.d.ts
 export type ElementCategory = "actor" | "node";
+/**
+ * Presentation hints a kind may carry, as data (core never draws). `@istar-ts/react` uses them as
+ * the defaults for the kind: a shape as SVG path data, the label's text box, a link's line.
+ */
+export interface KindShape {
+  readonly path: string;
+  readonly viewBox?: string;
+}
+export interface KindTextBox {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+export interface KindLine {
+  readonly dash?: string;
+  readonly marker?: string | false;
+  readonly markerFilled?: boolean;
+}
 export type LinkCategory = "actor" | "node" | "dependency";
 /** A resolved element kind of a metamodel. */
 export interface ElementKindDefinition<K extends string = string> {
@@ -145,6 +164,9 @@ export interface ElementKindDefinition<K extends string = string> {
   readonly pistarType: string;
   /** Name of the extension that declared it; absent for iStar 2.0 kinds. */
   readonly extension?: string;
+  /** Presentation hints (drawn by `@istar-ts/react`). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
@@ -184,6 +206,8 @@ export interface LinkKindDefinition<K extends string = string> {
   readonly check?: (context: LinkRuleContext) => LinkCheck;
   readonly pistarType: string;
   readonly extension?: string;
+  /** Presentation hint (drawn by `@istar-ts/react`). */
+  readonly line?: KindLine;
 }
 /** A metamodel: the element and link kinds a model may use, and their rules. */
 export interface Metamodel<EK extends string = ElementKind, LK extends string = LinkKind> {
@@ -222,6 +246,9 @@ export interface ElementKindDeclaration<K extends string = string> {
    * constructs as `istar.<Name>`, so `pistarType: 'istar.Planning'` reads its files.
    */
   readonly pistarType?: string;
+  /** Presentation hints, kept as data for renderers (`@istar-ts/react` draws them). */
+  readonly shape?: KindShape;
+  readonly textBox?: KindTextBox;
 }
 export interface LinkKindDeclaration<K extends string = string> {
   readonly kind: K;
@@ -237,6 +264,8 @@ export interface LinkKindDeclaration<K extends string = string> {
   /** Default: that of `behavesLike`, else none (no fixed label, no changeable value). */
   readonly info?: LinkKindInfo;
   readonly pistarType?: string;
+  /** Presentation hint, kept as data for renderers (`@istar-ts/react` draws it). */
+  readonly line?: KindLine;
 }
 /** A named set of new kinds, applied to a metamodel with `extendMetamodel`. */
 export interface MetamodelExtension<NEK extends string = string, NLK extends string = string> {
@@ -381,6 +410,10 @@ export type AnyIstarModel = IstarModel<string, string>;
  * the association.
  */
 export declare function withMetamodel<EK extends string, LK extends string>(model: IstarModel<string, string>, metamodel: Metamodel<EK, LK>): IstarModel<EK, LK>;
+/** @internal Records the host part of a model's metamodel (used by serialization). */
+export declare function setHostMetamodel(model: object, metamodel: AnyMetamodel | undefined): void;
+/** @internal The host part of a model's metamodel, if the file declares the rest. */
+export declare function hostMetamodelOf(model: object): AnyMetamodel | undefined;
 /** Gives `to` the metamodel of `from` (used for every model an operation derives). */
 export declare function inheritMetamodel<M extends IstarModel<string, string>>(from: IstarModel<string, string>, to: M): M;
 export declare function createEmptyModel<EK extends string, LK extends string>(diagram: Diagram | undefined, options: {
@@ -416,6 +449,38 @@ export declare function dependencyLinksOf<EK extends string, LK extends string>(
   outbound?: IstarLink<LK>;
 };
 //#endregion
+//#region src/file-metamodel.d.ts
+/** The top-level key of the block in piStar JSON. */
+export declare const FILE_METAMODEL_KEY = "metamodel";
+export interface FileElementKind extends Omit<ElementKindDeclaration<string>, "info"> {
+  readonly info?: {
+    readonly canBeInnerElement?: boolean;
+    readonly canBeDependum?: boolean;
+    readonly canBeOnPaper?: boolean;
+  };
+  readonly [key: string]: unknown;
+}
+export interface FileLinkKind extends Omit<LinkKindDeclaration<string>, "check"> {
+  readonly [key: string]: unknown;
+}
+/** The `"metamodel"` block of a model file. */
+export interface FileMetamodel {
+  /** Identifies the constructs' dialect, e.g. `iStar4RationalAgents`. */
+  readonly name: string;
+  readonly elements?: readonly FileElementKind[];
+  readonly links?: readonly FileLinkKind[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Checks that `value` is a well-formed `"metamodel"` block and returns it typed. Throws
+ * `MetamodelError` naming the offending path (`metamodel.elements[1].kind must be a string`).
+ * Whether its kinds fit a given metamodel (namespacing, collisions, `behavesLike` targets) is
+ * checked when it is applied, by `extendMetamodel`.
+ */
+export declare function validateFileMetamodel(value: unknown, path?: string): FileMetamodel;
+/** The block as an extension `extendMetamodel` applies (it ignores the extra keys). */
+export declare function fileMetamodelExtension(block: FileMetamodel): MetamodelExtension<string, string>;
+//#endregion
 //#region src/serialization.d.ts
 export interface PistarElementJson {
   id: string;
@@ -494,12 +559,21 @@ export declare function inheritSourceLayout<M extends IstarModel<string, string>
  * `if (element.x && element.y)` silently drops them, which looks unintended.
  */
 export interface ParsePistarOptions<EK extends string = ElementKind, LK extends string = LinkKind> {
+  /**
+   * Read the file's own `"metamodel"` block (see `FileMetamodel`) and parse with `metamodel`
+   * (or iStar 2.0) extended by it. Default false: the block is kept as an unknown key and not
+   * applied, as before. A block whose kinds collide with the metamodel throws `MetamodelError`.
+   */
+  readonly fileMetamodel?: boolean;
   /**
    * The metamodel whose kinds the file may use. Default iStar 2.0: any other `type` throws,
    * as in the piStar tool. The parsed model remembers it (see `metamodelOf`).
    */
   readonly metamodel?: Metamodel<EK, LK>;
 }
+export declare function parsePistar(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<string, string> & {
+  readonly fileMetamodel: true;
+}): IstarModel<string, string>;
 export declare function parsePistar<EK extends string, LK extends string>(input: string | PistarFile | Record<string, unknown>, options: ParsePistarOptions<EK, LK> & {
   readonly metamodel: Metamodel<EK, LK>;
 }): IstarModel<EK, LK>;
@@ -519,6 +593,19 @@ export interface ToPistarOptions {
 export declare function toPistarObject<EK extends string, LK extends string>(input: IstarModel<EK, LK>, options?: ToPistarOptions): PistarFile;
 /** Serializes a model to piStar's JSON text (2-space indentation, no trailing newline). */
 export declare function toPistar<EK extends string, LK extends string>(model: IstarModel<EK, LK>, options?: ToPistarOptions): string;
+/**
+ * The constructs the model's file declares in its `"metamodel"` block, when they were applied
+ * (read with `fileMetamodel: true`, or set with `withFileMetamodel`); `undefined` otherwise.
+ * Kinds the host supplied are never part of it.
+ */
+export declare function fileMetamodelOf<EK extends string, LK extends string>(model: IstarModel<EK, LK>): FileMetamodel | undefined;
+/**
+ * A copy of `model` whose file declares `block` (`null` removes the block): its metamodel is the
+ * host's extended by `block`, and `toPistar` writes the block. This is how a tool's "Add new"
+ * construct joins a model. Throws `MetamodelError` if the block is malformed, collides with the
+ * host's kinds, or leaves out a kind the model still uses.
+ */
+export declare function withFileMetamodel<EK extends string, LK extends string>(model: IstarModel<EK, LK>, block: FileMetamodel | null): IstarModel<string, string>;
 declare namespace operations_d_exports {
   export { AddDependencyResult, ConnectOptions, ConnectResult, ElementPatch, IdGenerator, LinkPatch, ModelOperationError, NewDependency, NewElement, NewLink, OperationContext, addDependency, addElement, connect, defaultIdGenerator, dependencyEnds, disconnect, moveElement, nestElement, removeElement, removeElements, updateDiagram, updateElement, updateLink };
 }
@@ -821,4 +908,137 @@ export declare function defineProperties<const S extends PropertyShape, const Ki
 }): PropertySchema<S, Kind>;
 export declare function validateModelProperties<EK extends string, LK extends string>(model: IstarModel<EK, LK>, schemas: readonly PropertySchema<PropertyShape, string>[]): ModelPropertyIssue[];
 //#endregion
+//#region src/diagnostics.d.ts
+/**
+ * The Goal Model Diagnostics Protocol: findings about a model's elements and links, published by
+ * any analyser (a language server, a validator, a simulation…) and anchored by element id rather
+ * than by text position. Data only: diagnostics are never part of the model and are never
+ * written to disk.
+ *
+ * See goal-controller issue #24 (option D). Producers publish per source; consumers see the
+ * union of every source, deduplicated by `(elementId, key, message)`.
+ */
+export type DiagnosticSeverity = "error" | "warning" | "info" | "hint";
+/** Most severe first. */
+export declare const DIAGNOSTIC_SEVERITIES: readonly DiagnosticSeverity[];
+/** A zero-based position in the producer's document (as in LSP). */
+export interface DiagnosticPosition {
+  readonly line: number;
+  readonly character: number;
+}
+export interface DiagnosticRange {
+  readonly start: DiagnosticPosition;
+  readonly end: DiagnosticPosition;
+}
+export interface GoalDiagnostic {
+  /** Id of the element or link the diagnostic is about. */
+  readonly elementId: string;
+  /** The custom property it is about; absent for the element as a whole. */
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  /** Who published it (e.g. `mutrose`, `goal-language`). */
+  readonly source?: string;
+  /** Where it was found in the producer's document, if it has one. */
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+  /** Producer data, passed through untouched. */
+  readonly data?: unknown;
+}
+/** Negative when `a` is more severe than `b`. */
+export declare function compareSeverity(a: DiagnosticSeverity, b: DiagnosticSeverity): number;
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+export declare function worstDiagnosticSeverity(diagnostics: readonly {
+  readonly severity: DiagnosticSeverity;
+}[] | undefined): DiagnosticSeverity | undefined;
+/**
+ * The union of several lists, in order, without duplicates: diagnostics with the same
+ * `(elementId, key, message)` count once, keeping the first one's position and the most severe
+ * severity among them.
+ */
+export declare function mergeDiagnostics(lists: Iterable<readonly GoalDiagnostic[] | undefined>): GoalDiagnostic[];
+/** Diagnostics by element (or link) id, each list in the input order. */
+export declare function groupDiagnostics(diagnostics: readonly GoalDiagnostic[] | undefined): ReadonlyMap<string, readonly GoalDiagnostic[]>;
+/**
+ * Holds the diagnostics of several sources. Each `publish` replaces that source's set, so a
+ * producer re-publishes everything it currently reports, as an LSP server does.
+ */
+export interface DiagnosticsStore {
+  /**
+   * Replaces `source`'s diagnostics (an empty list clears them). Entries without a `source` get
+   * this one.
+   */
+  publish(source: string, diagnostics: readonly GoalDiagnostic[]): void;
+  /** Removes one source's diagnostics, or every source's. */
+  clear(source?: string): void;
+  /** Sources with diagnostics, in the order they first published. */
+  sources(): readonly string[];
+  /** One source's diagnostics. */
+  get(source: string): readonly GoalDiagnostic[];
+  /**
+   * Every source's diagnostics, merged (see `mergeDiagnostics`). The same array until the next
+   * change, so it can back `useSyncExternalStore`.
+   */
+  getAll(): readonly GoalDiagnostic[];
+  subscribe(listener: () => void): () => void;
+}
+export declare function createDiagnosticsStore(): DiagnosticsStore;
+/**
+ * The parts of an LSP `Diagnostic` the adapter reads (structurally typed, so no LSP library is
+ * needed). The element is taken from `data.elementId`, or MutRoSe's `data.nodeId`; the property
+ * from `data.key`.
+ */
+export interface LspDiagnosticLike {
+  readonly range?: DiagnosticRange;
+  /** LSP numbering: 1 error, 2 warning, 3 information, 4 hint. */
+  readonly severity?: number;
+  readonly message: string | {
+    readonly value: string;
+  };
+  readonly source?: string;
+  readonly code?: string | number | {
+    readonly value: string | number;
+  };
+  readonly data?: unknown;
+}
+export interface FromLspOptions<D extends LspDiagnosticLike = LspDiagnosticLike> {
+  /**
+   * The element of a diagnostic whose `data` names none, e.g. by looking its range up in the
+   * document. Return `undefined` to drop it.
+   */
+  readonly elementIdFor?: (diagnostic: D) => string | undefined;
+  /**
+   * `'vscode'` for `vscode.Diagnostic` objects, whose severity counts from 0 (error) to 3
+   * (hint). Default `'lsp'`, the protocol's 1 to 4.
+   */
+  readonly severityNumbering?: "lsp" | "vscode";
+}
+/**
+ * One LSP diagnostic anchored by `data.elementId` (or `data.nodeId`), or `undefined` when it
+ * names no element. For range-anchored diagnostics use `fromLspDiagnostics` with `elementIdFor`.
+ */
+export declare function fromLspDiagnostic(diagnostic: LspDiagnosticLike): GoalDiagnostic | undefined;
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+export declare function fromLspDiagnostics<D extends LspDiagnosticLike>(diagnostics: readonly D[], options?: FromLspOptions<D>): GoalDiagnostic[];
+/**
+ * The shape MutRoSe's VS Code extension posts to its webview: `{ nodeId, severity, message }`
+ * (plus `range` and `source`). `nodeId` is missing when no node could be found.
+ */
+export interface NodeIdDiagnostic {
+  readonly nodeId?: string;
+  readonly key?: string;
+  readonly severity: DiagnosticSeverity | string;
+  readonly message: string;
+  readonly source?: string;
+  readonly range?: DiagnosticRange;
+  readonly code?: string;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+export declare function fromNodeIdDiagnostic(diagnostic: NodeIdDiagnostic): GoalDiagnostic | undefined;
+/**
+ * `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+ * without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+ */
+export declare function fromNodeIdDiagnostics(diagnostics: readonly NodeIdDiagnostic[]): GoalDiagnostic[];
+//#endregion
 //# sourceMappingURL=index.d.ts.map