@istar-ts/core 0.13.7 → 0.14.0

package/dist/index.d.cts

@@ -208,6 +208,12 @@ export interface HubLinkParts {
   readonly leg: string;
   readonly end: string;
 }
+/**
+ * The kinds an n-ary link kind `K` generates under the default names: its hub element kind
+ * (`<K>Hub`), its leg (`<K>Start`) and its end (`<K>End`). A schema for one of them is declared
+ * like any other: `defineProperties('kaos.RefinementLinkStart', { … })`.
+ */
+export type HubPartKind<K extends string> = `${K}Hub` | `${K}Start` | `${K}End`;
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
  * which kinds may be the source and target. Entries are kind names (`istar.Goal`,
@@ -1087,14 +1093,25 @@ export interface PropertyOptions<T> {
   description?: string;
 }
 export interface PropertyType<T> {
-  readonly type: "string" | "number" | "boolean" | "enum";
+  readonly type: "string" | "number" | "boolean" | "enum" | "reference";
   readonly options: PropertyOptions<T>;
   readonly values?: readonly string[];
   readonly integer?: boolean;
   readonly min?: number;
   readonly max?: number;
+  /**
+   * Numbers with `max: 1` (a probability, a rate): the value may also be written as a
+   * percentage (`20.00%`). CAIRIS writes `0.2`, KAOSTools `.2` and `20.00%`.
+   */
+  readonly percent?: boolean;
+  /** References: the element or link kinds the id may name; absent, any kind. */
+  readonly kinds?: readonly string[];
   parse(raw: string): PropertyResult<T>;
-  serialize(value: T): string;
+  /**
+   * The value as a string. `previous`, the raw string being replaced, lets a type keep the form
+   * it was read in (a number read as `20.00%` is written as a percentage).
+   */
+  serialize(value: T, previous?: string): string;
 }
 export declare function string(options?: PropertyOptions<string>): PropertyType<string>;
 export declare function number(options?: PropertyOptions<number> & {
@@ -1104,11 +1121,20 @@ export declare function number(options?: PropertyOptions<number> & {
 }): PropertyType<number>;
 export declare function boolean(options?: PropertyOptions<boolean>): PropertyType<boolean>;
 export declare function enumOf<const V extends readonly string[]>(values: V, options?: PropertyOptions<V[number]>): PropertyType<V[number]>;
+/**
+ * A value that is another element's or link's id, e.g. the goal a KAOS resolution restores. The
+ * schema only checks it is non-empty; `validateModelProperties` reports an id that isn't in the
+ * model or names a kind outside `kinds`.
+ */
+export declare function reference(options?: PropertyOptions<string> & {
+  kinds?: readonly string[];
+}): PropertyType<string>;
 export declare const prop: {
   string: typeof string;
   number: typeof number;
   boolean: typeof boolean;
   enum: typeof enumOf;
+  reference: typeof reference;
 };
 export type PropertyShape = Record<string, PropertyType<unknown>>;
 export type InferProperties<S extends PropertyShape> = { [K in keyof S]: S[K] extends PropertyType<infer T> ? T : never; };

package/dist/index.d.ts

@@ -208,6 +208,12 @@ export interface HubLinkParts {
   readonly leg: string;
   readonly end: string;
 }
+/**
+ * The kinds an n-ary link kind `K` generates under the default names: its hub element kind
+ * (`<K>Hub`), its leg (`<K>Start`) and its end (`<K>End`). A schema for one of them is declared
+ * like any other: `defineProperties('kaos.RefinementLinkStart', { … })`.
+ */
+export type HubPartKind<K extends string> = `${K}Hub` | `${K}Start` | `${K}End`;
 /**
  * Declarative link rules, as piStar-ext's "Create a new Construct" dialog collects them:
  * which kinds may be the source and target. Entries are kind names (`istar.Goal`,
@@ -1087,14 +1093,25 @@ export interface PropertyOptions<T> {
   description?: string;
 }
 export interface PropertyType<T> {
-  readonly type: "string" | "number" | "boolean" | "enum";
+  readonly type: "string" | "number" | "boolean" | "enum" | "reference";
   readonly options: PropertyOptions<T>;
   readonly values?: readonly string[];
   readonly integer?: boolean;
   readonly min?: number;
   readonly max?: number;
+  /**
+   * Numbers with `max: 1` (a probability, a rate): the value may also be written as a
+   * percentage (`20.00%`). CAIRIS writes `0.2`, KAOSTools `.2` and `20.00%`.
+   */
+  readonly percent?: boolean;
+  /** References: the element or link kinds the id may name; absent, any kind. */
+  readonly kinds?: readonly string[];
   parse(raw: string): PropertyResult<T>;
-  serialize(value: T): string;
+  /**
+   * The value as a string. `previous`, the raw string being replaced, lets a type keep the form
+   * it was read in (a number read as `20.00%` is written as a percentage).
+   */
+  serialize(value: T, previous?: string): string;
 }
 export declare function string(options?: PropertyOptions<string>): PropertyType<string>;
 export declare function number(options?: PropertyOptions<number> & {
@@ -1104,11 +1121,20 @@ export declare function number(options?: PropertyOptions<number> & {
 }): PropertyType<number>;
 export declare function boolean(options?: PropertyOptions<boolean>): PropertyType<boolean>;
 export declare function enumOf<const V extends readonly string[]>(values: V, options?: PropertyOptions<V[number]>): PropertyType<V[number]>;
+/**
+ * A value that is another element's or link's id, e.g. the goal a KAOS resolution restores. The
+ * schema only checks it is non-empty; `validateModelProperties` reports an id that isn't in the
+ * model or names a kind outside `kinds`.
+ */
+export declare function reference(options?: PropertyOptions<string> & {
+  kinds?: readonly string[];
+}): PropertyType<string>;
 export declare const prop: {
   string: typeof string;
   number: typeof number;
   boolean: typeof boolean;
   enum: typeof enumOf;
+  reference: typeof reference;
 };
 export type PropertyShape = Record<string, PropertyType<unknown>>;
 export type InferProperties<S extends PropertyShape> = { [K in keyof S]: S[K] extends PropertyType<infer T> ? T : never; };

package/dist/index.js

@@ -2499,19 +2499,50 @@ function string(options) {
 		}
 	};
 }
+/** `20.00%` → 20.00 as text, or undefined when `raw` isn't a percentage. */
+function percentBody(raw) {
+	const text = raw.trim();
+	if (!text.endsWith("%")) return void 0;
+	const body = text.slice(0, -1).trim();
+	return body === "" ? void 0 : body;
+}
+/** Digits after the decimal point of a number written as text (`20.00` → 2). */
+function decimals(text) {
+	const dot = text.indexOf(".");
+	return dot === -1 ? 0 : text.length - dot - 1;
+}
+/** `value` without floating-point noise from a ×100 (0.35 * 100 = 35.00000000000001). */
+function plain(value) {
+	return String(Number(value.toPrecision(12)));
+}
+/** Writes `value` in the form of `previous`: a percentage, a leading dot, or plain. */
+function formatNumber(value, previous, percent) {
+	if (previous === void 0) return String(value);
+	const body = percent ? percentBody(previous) : void 0;
+	if (body !== void 0) {
+		const text = plain(value * 100);
+		const places = decimals(body);
+		return `${places > decimals(text) ? (value * 100).toFixed(places) : text}%`;
+	}
+	if (/^\s*[+-]?\.\d/.test(previous) && Math.abs(value) < 1) return String(value).replace(/^(-?)0\./, "$1.");
+	return String(value);
+}
 function number(options) {
 	const opts = options ?? {};
 	const integer = options?.integer;
 	const min = options?.min;
 	const max = options?.max;
+	const percent = max === 1;
 	return {
 		type: "number",
 		options: opts,
 		integer,
 		min,
 		max,
+		...percent ? { percent } : {},
 		parse(raw) {
-			const value = Number(raw);
+			const body = percent ? percentBody(raw) : void 0;
+			const value = body !== void 0 ? Number(body) / 100 : Number(raw);
 			if (!Number.isFinite(value)) return {
 				ok: false,
 				error: "must be a finite number"
@@ -2533,8 +2564,8 @@ function number(options) {
 				value
 			};
 		},
-		serialize(value) {
-			return String(value);
+		serialize(value, previous) {
+			return formatNumber(value, previous, percent);
 		}
 	};
 }
@@ -2581,11 +2612,34 @@ function enumOf(values, options) {
 		}
 	};
 }
+/**
+* A value that is another element's or link's id, e.g. the goal a KAOS resolution restores. The
+* schema only checks it is non-empty; `validateModelProperties` reports an id that isn't in the
+* model or names a kind outside `kinds`.
+*/
+function reference(options) {
+	const { kinds, ...opts } = options ?? {};
+	return {
+		type: "reference",
+		options: opts,
+		...kinds ? { kinds } : {},
+		parse(raw) {
+			return {
+				ok: true,
+				value: raw
+			};
+		},
+		serialize(value) {
+			return value;
+		}
+	};
+}
 const prop = {
 	string,
 	number,
 	boolean,
-	enum: enumOf
+	enum: enumOf,
+	reference
 };
 function isCustomPropertiesRecord(source) {
 	if ("customProperties" in source) return false;
@@ -2627,7 +2681,7 @@ function readShape(shape, source) {
 			}
 			issues.push({
 				key,
-				message: field.type === "boolean" ? "must be true or false" : field.type === "enum" ? `must be one of: ${field.values?.join(", ") ?? ""}` : "must be a finite number"
+				message: field.type === "boolean" ? "must be true or false" : field.type === "enum" ? `must be one of: ${field.values?.join(", ") ?? ""}` : field.type === "reference" ? "must be an element or link id" : "must be a finite number"
 			});
 			continue;
 		}
@@ -2646,6 +2700,15 @@ function readShape(shape, source) {
 		issues
 	};
 }
+/**
+* A patched value as a string, written back as read: the current string is kept when it already
+* holds the value (`.2` stays `.2`), and otherwise the type writes the value in its form.
+*/
+function writeField(field, value, current) {
+	const parsed = field.parse(current);
+	if (parsed.ok && Object.is(parsed.value, value)) return current;
+	return field.serialize(value, current);
+}
 function defineProperties(kind, shape, options) {
 	const crossValidate = options?.validate;
 	return {
@@ -2667,7 +2730,7 @@ function defineProperties(kind, shape, options) {
 					const patched = patch[key];
 					if (patched === void 0) continue;
 					const field = shape[key];
-					if (field) result[key] = field.serialize(patched);
+					if (field) result[key] = writeField(field, patched, value);
 				} else result[key] = value;
 				seen.add(key);
 			}
@@ -2701,20 +2764,39 @@ function validateModelProperties(model, schemas) {
 		byKind.set(schema.kind, list);
 	}
 	const issues = [];
-	for (const element of model.elements.values()) {
-		const kindSchemas = byKind.get(element.kind);
-		if (!kindSchemas) continue;
-		for (const schema of kindSchemas) for (const issue of schema.validate(element)) issues.push({
-			...issue,
-			id: element.id
+	const check = (owner) => {
+		const kindSchemas = byKind.get(owner.kind);
+		if (!kindSchemas) return;
+		for (const schema of kindSchemas) {
+			for (const issue of schema.validate(owner)) issues.push({
+				...issue,
+				id: owner.id
+			});
+			for (const issue of referenceIssues(model, schema.shape, owner.customProperties)) issues.push({
+				...issue,
+				id: owner.id
+			});
+		}
+	};
+	for (const element of model.elements.values()) check(element);
+	for (const link of model.links.values()) check(link);
+	return issues;
+}
+/** References (`prop.reference`) to ids that aren't in the model, or to the wrong kind. */
+function referenceIssues(model, shape, custom) {
+	const issues = [];
+	for (const [key, field] of Object.entries(shape)) {
+		if (field.type !== "reference") continue;
+		const id = custom?.[key];
+		if (id === void 0 || id === "") continue;
+		const target = model.elements.get(id) ?? model.links.get(id);
+		if (!target) issues.push({
+			key,
+			message: `refers to "${id}", which is not in the model`
 		});
-	}
-	for (const link of model.links.values()) {
-		const kindSchemas = byKind.get(link.kind);
-		if (!kindSchemas) continue;
-		for (const schema of kindSchemas) for (const issue of schema.validate(link)) issues.push({
-			...issue,
-			id: link.id
+		else if (field.kinds && !field.kinds.includes(target.kind)) issues.push({
+			key,
+			message: `must refer to a ${field.kinds.join(" or ")}`
 		});
 	}
 	return issues;
@@ -2890,6 +2972,6 @@ function fromNodeIdDiagnostics(diagnostics) {
 	return result;
 }
 //#endregion
-export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
+export { ACTOR_KINDS, ACTOR_LINK_KINDS, CONTRIBUTION_LABELS, DEFAULT_DIAGRAM, DEFAULT_ELEMENT_SIZE, DEPENDENCY_LINK_KINDS, DIAGNOSTIC_SEVERITIES, DIAGRAM_LAYOUT_KEY, DSM3_FILE_KEYS, DSM3_TOOL, ELEMENT_KINDS, FILE_METAMODEL_KEY, HUB_ENTRY_KEY, ISTAR_2_0, ISTAR_2_0_DECLARATION, ISTAR_PREFIX, ISTAR_VERSION, LINK_KINDS, LINK_KIND_INFO, LINK_SELECTOR, METAMODEL_VERSION, MetamodelError, ModelOperationError, NODE_KINDS, NODE_KIND_INFO, NODE_LINK_KINDS, PISTAR_TOOL, PistarParseError, PistarWriteError, addDependency, addElement, addLeg, boolean, canLink, childrenOf, compareSeverity, connect, createDiagnosticsStore, createEmptyModel, createModelStore, defaultHubPosition, defaultIdGenerator, defineMetamodel, defineMetamodelExtension, defineProperties, dependencyEnds, dependencyLinksOf, detectFramework, detectPrefix, disconnect, effectiveElementKind, effectiveLinkKind, elementBehavesLike, elementCenter, elementKindDefinition, enumOf, extendMetamodel, fileMetamodelExtension, fileMetamodelOf, fromLspDiagnostic, fromLspDiagnostics, fromNodeIdDiagnostic, fromNodeIdDiagnostics, getSourceLayout, groupDiagnostics, hostMetamodelOf, hubEntryLayoutKey, hubLinkOf, hubOfLink, inheritMetamodel, inheritSourceLayout, isActor, isActorIn, isActorKind, isActorKindIn, isActorLinkKind, isContributionLabel, isDependencyLinkKind, isElementKind, isHubElement, isLinkKind, isLinkRef, isNode, isNodeIn, isNodeKind, isNodeKindIn, isNodeLinkKind, linkBehavesLike, linkKindDefinition, linkTargetOf, linksOf, mergeDiagnostics, metamodelOf, moveElement, nestElement, number, parsePistar, prop, reference, removeElement, removeElements, removeLeg, setHostMetamodel, shortKindName, string, targetsLinks, toPistar, toPistarObject, updateDiagram, updateElement, updateLink, validateFileMetamodel, validateModel, validateModelProperties, withFileMetamodel, withMetamodel, worstDiagnosticSeverity };
 
 //# sourceMappingURL=index.js.map