@istar-ts/core 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -908,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

@@ -908,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

package/dist/index.js

@@ -2026,6 +2026,176 @@ function validateModelProperties(model, schemas) {
 	return issues;
 }
 //#endregion
-export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, ELEMENT_KINDS, FILE_METAMODEL_KEY, ISTAR_2_0, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, boolean, canLink, childrenOf, connect, createEmptyModel, createModelStore, defaultIdGenerator, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, getSourceLayout, hostMetamodelOf, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isLinkKind, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkKindDefinition, linksOf, metamodelOf, moveElement, nestElement, number, parsePistar, prop, removeElement, removeElements, setHostMetamodel, shortKindName, string, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel };
+//#region src/diagnostics.ts
+/** Most severe first. */
+const DIAGNOSTIC_SEVERITIES = [
+	"error",
+	"warning",
+	"info",
+	"hint"
+];
+const RANK = {
+	error: 0,
+	warning: 1,
+	info: 2,
+	hint: 3
+};
+/** Negative when `a` is more severe than `b`. */
+function compareSeverity(a, b) {
+	return RANK[a] - RANK[b];
+}
+/** The most severe severity in a list (what a badge shows), or `undefined` if it is empty. */
+function worstDiagnosticSeverity(diagnostics) {
+	let worst;
+	for (const d of diagnostics ?? []) {
+		if (worst === void 0 || RANK[d.severity] < RANK[worst]) worst = d.severity;
+		if (worst === "error") break;
+	}
+	return worst;
+}
+function identity(d) {
+	return `${d.elementId}\u0000${d.key ?? ""}\u0000${d.message}`;
+}
+/**
+* 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.
+*/
+function mergeDiagnostics(lists) {
+	const result = [];
+	const index = /* @__PURE__ */ new Map();
+	for (const list of lists) for (const d of list ?? []) {
+		const id = identity(d);
+		const at = index.get(id);
+		if (at === void 0) {
+			index.set(id, result.length);
+			result.push(d);
+		} else if (RANK[d.severity] < RANK[result[at].severity]) result[at] = {
+			...result[at],
+			severity: d.severity
+		};
+	}
+	return result;
+}
+/** Diagnostics by element (or link) id, each list in the input order. */
+function groupDiagnostics(diagnostics) {
+	const map = /* @__PURE__ */ new Map();
+	for (const d of diagnostics ?? []) {
+		const list = map.get(d.elementId);
+		if (list) list.push(d);
+		else map.set(d.elementId, [d]);
+	}
+	return map;
+}
+const NONE = [];
+function createDiagnosticsStore() {
+	const bySource = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let merged = NONE;
+	const changed = () => {
+		merged = bySource.size === 0 ? NONE : mergeDiagnostics(bySource.values());
+		for (const listener of listeners) listener();
+	};
+	return {
+		publish(source, diagnostics) {
+			if (diagnostics.length === 0) {
+				if (bySource.delete(source)) changed();
+				return;
+			}
+			bySource.set(source, diagnostics.map((d) => d.source === void 0 ? {
+				...d,
+				source
+			} : d));
+			changed();
+		},
+		clear(source) {
+			if (source === void 0) {
+				if (bySource.size === 0) return;
+				bySource.clear();
+			} else if (!bySource.delete(source)) return;
+			changed();
+		},
+		sources: () => [...bySource.keys()],
+		get: (source) => bySource.get(source) ?? NONE,
+		getAll: () => merged,
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+const LSP_SEVERITIES = [
+	"error",
+	"warning",
+	"info",
+	"hint"
+];
+function anchorOf(data) {
+	if (typeof data !== "object" || data === null) return {};
+	const record = data;
+	const elementId = typeof record.elementId === "string" ? record.elementId : typeof record.nodeId === "string" ? record.nodeId : void 0;
+	return {
+		...elementId ? { elementId } : {},
+		...typeof record.key === "string" ? { key: record.key } : {}
+	};
+}
+function convertLsp(d, options) {
+	const anchor = anchorOf(d.data);
+	const elementId = anchor.elementId ?? options.elementIdFor?.(d);
+	if (!elementId) return void 0;
+	const base = options.severityNumbering === "vscode" ? 0 : 1;
+	const severity = d.severity === void 0 ? "error" : LSP_SEVERITIES[d.severity - base] ?? "error";
+	const code = typeof d.code === "object" ? d.code.value : d.code;
+	return {
+		elementId,
+		...anchor.key !== void 0 ? { key: anchor.key } : {},
+		severity,
+		message: typeof d.message === "string" ? d.message : d.message.value,
+		...d.source !== void 0 ? { source: d.source } : {},
+		...d.range ? { range: d.range } : {},
+		...code !== void 0 ? { code: String(code) } : {},
+		...d.data !== void 0 ? { data: d.data } : {}
+	};
+}
+/**
+* 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`.
+*/
+function fromLspDiagnostic(diagnostic) {
+	return convertLsp(diagnostic, {});
+}
+/** LSP diagnostics as goal diagnostics; those that can't be anchored to an element are dropped. */
+function fromLspDiagnostics(diagnostics, options = {}) {
+	const result = [];
+	for (const d of diagnostics) {
+		const converted = convertLsp(d, options);
+		if (converted) result.push(converted);
+	}
+	return result;
+}
+/** One `{ nodeId, severity, message }` diagnostic, or `undefined` without a `nodeId`. */
+function fromNodeIdDiagnostic(diagnostic) {
+	const { nodeId, severity, ...rest } = diagnostic;
+	if (!nodeId) return void 0;
+	return {
+		...rest,
+		elementId: nodeId,
+		severity: Object.hasOwn(RANK, severity) ? severity : "info"
+	};
+}
+/**
+* `{ nodeId, severity, message }` diagnostics (MutRoSe) as goal diagnostics, dropping those
+* without a node: `store.publish('mutrose', fromNodeIdDiagnostics(message.diagnostics))`.
+*/
+function fromNodeIdDiagnostics(diagnostics) {
+	const result = [];
+	for (const d of diagnostics) {
+		const converted = fromNodeIdDiagnostic(d);
+		if (converted) result.push(converted);
+	}
+	return result;
+}
+//#endregion
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, ELEMENT_KINDS, FILE_METAMODEL_KEY, ISTAR_2_0, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, boolean, canLink, childrenOf, compareSeverity, connect, createDiagnosticsStore, createEmptyModel, createModelStore, defaultIdGenerator, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isLinkKind, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkKindDefinition, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, removeElement, removeElements, setHostMetamodel, shortKindName, string, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
 
 //# sourceMappingURL=index.js.map