@istar-ts/core 0.11.0 → 0.13.0

package/README.md

@@ -216,8 +216,9 @@ const model = parsePistar(text, { metamodel: RATIONAL_AGENTS });
   Either way, an optional `check(context)` predicate runs last. Dependency-category kinds must
   behave like `istar.DependencyLink`; `addDependency({ …, linkKind })` creates them.
 
-- **Names.** Kinds are namespaced (`rationalAgents.Plan`). `istar.` is reserved for iStar 2.0, and a
-  name or `pistarType` that collides with an existing one throws `MetamodelError`. Extensions
+- **Names.** Kinds are namespaced (`rationalAgents.Plan`). The root metamodel's prefix (`istar.` for
+  iStar 2.0) is reserved for it, and a name or `pistarType` that collides with an existing one
+  throws `MetamodelError`. Extensions
   stack, and a later one may build on an earlier one's kinds.
 - **The model remembers its metamodel.** `parsePistar`, `createEmptyModel(undefined, { metamodel })`
   and `createModelStore(undefined, { metamodel })` associate it, and every operation and store
@@ -251,6 +252,137 @@ rather than writing a type that can't be read back.
 
 See [docs/metamodel-extensions.md](../../docs/metamodel-extensions.md) for the design.
 
+## Root metamodels
+
+iStar 2.0 is one root metamodel: a whole modelling language rather than a dialect of another.
+`defineMetamodel` builds others, such as the KAOS and NFR languages of
+[DSM3-goals](https://github.com/vieirin/istar-ts/issues/7), from the same element and link
+declarations that extensions use. `ISTAR_2_0` is itself `defineMetamodel(ISTAR_2_0_DECLARATION)`.
+
+```ts
+import { createEmptyModel, defineMetamodel, extendMetamodel, parsePistar } from '@istar-ts/core';
+
+const KAOS = defineMetamodel({
+  name: 'kaos', // the metamodel's name and framework
+  prefix: 'kaos', // its namespace, reserved against extensions
+  elements: [
+    { kind: 'kaos.Goal', category: 'node', size: { width: 135, height: 36 } },
+    { kind: 'kaos.Softgoal', behavesLike: 'kaos.Goal' },
+    { kind: 'kaos.Agent', category: 'node' },
+  ],
+  links: [
+    {
+      kind: 'kaos.ResponsibilityAssignment',
+      rules: { sources: ['kaos.Agent'], targets: ['node'], sameActor: false },
+    },
+  ],
+  file: {
+    tool: 'dsm3-goals',
+    extra: { metamodelVersion: '1.0' },
+    keys: [
+      'actors',
+      'orphans',
+      'dependencies',
+      'links',
+      'display',
+      'tool',
+      'metamodelVersion',
+      'saveDate',
+      'diagram',
+    ],
+  },
+});
+
+const model = parsePistar(text, { metamodel: KAOS });
+const blank = createEmptyModel(undefined, { metamodel: KAOS }); // tool "dsm3-goals", no "istar"
+```
+
+- **Declarations.** Kinds are declared in order, with the same validation and errors as
+  `extendMetamodel`. `behavesLike` and link rules refer to kinds declared before them. A root may
+  use any namespace. Nodes default to DSM3-goals' containment rules: inner element, dependum and
+  on paper. A root's link kind may give neither `rules` nor `behavesLike`, as iStar 2.0's do:
+  their rules are built into the library, and any other such kind accepts no link.
+- **Identity.** `metamodel.framework` is the root's name (`istar-2.0`, `kaos`). `prefix` is its
+  reserved namespace, so `extendMetamodel(KAOS, …)` rejects `kaos.*` kinds. Extensions keep both,
+  and `file`; `name` gains the extensions' names (`kaos+ops`).
+- **Files.** `file` describes the files of models that weren't read from one. `createEmptyModel`
+  records `file.tool` (default `pistar.2.1.0`), `file.istar` only when set (iStar 2.0 sets
+  `"2.0"`), and `file.extra` as extra top-level keys. `toPistar` orders top-level keys like the
+  source file, else like `file.keys`, else like piStar.
+- **Which root a file uses.** `detectFramework(text, [ISTAR_2_0, KAOS, NFR])` picks the root whose
+  `prefix` is the namespace of the file's first `type` (`detectPrefix`). For a file without
+  types, it picks the only root whose `file.tool` is the file's `tool`; otherwise it returns
+  `undefined`.
+
+### Hub links
+
+A link kind with `arity: 'n'` has several sources and one target, like KAOS's AND-refinement. In a
+model it is a hub element, a leg from each source to the hub, and an end from the hub to the
+target, as DSM3-goals draws and saves it. The declaration generates the three kinds from the
+base kind's name: `<kind>Hub`, `<kind>Start` (legs) and `<kind>End`.
+
+```ts
+const KAOS = defineMetamodel<KaosElementKind, KaosLinkKind>({
+  // …
+  links: [
+    {
+      kind: 'kaos.RefinementLink',
+      arity: 'n',
+      rules: {
+        sources: ['kaos.BehavioralGoal', 'kaos.Softgoal'],
+        targets: ['node'],
+        sameActor: false,
+      },
+    },
+  ],
+});
+
+const made = store.connect({ kind: 'kaos.RefinementLink', source: goalA, target: parent });
+if (made.ok && made.hub) {
+  // made.hub: { hub, legs: [leg], end }. The hub sits centred between goalA and parent.
+  store.connect({ kind: 'kaos.RefinementLink', source: goalB, target: made.hub.hub.id }); // 2nd leg
+}
+```
+
+- **Kinds.** The hub kind has `role: 'hub'` and `of` (the base kind), a 20×20 circle shape and
+  `canBeOnPaper`. Legs and ends have `role: 'leg' | 'end'`. `parts` renames them and `hubSize`
+  resizes the hub. Generated kinds aren't inferred into the metamodel's kind types, so name
+  them in `defineMetamodel`'s type arguments if you need them typed.
+- **Rules.** The `node`, `actor` and `*` selectors never match a hub. A link of another kind
+  towards a hub fails with code `hub-target`. A source gets one leg per hub, and a hub has one
+  end. The base kind's `sameActor` holds between each leg's source and the end's target.
+- **Operations.** `connect` with the base kind creates the hub, a leg and the end, or adds a leg
+  when the target is one of its hubs. `input.id` and `customProperties` go to the hub; `label` and
+  `name` go to the end. `addLeg(model, hubId, source)` and `removeLeg(model, legId)` exist in
+  operations and on the store. Removing a hub's end or its last leg removes the hub. Removing the
+  hub removes its legs and end.
+- **Queries.** Use `hubLinkOf(model, hubId)`, `hubOfLink(model, linkId)`,
+  `isHubElement(metamodel, element)`, `elementCenter` and `defaultHubPosition`.
+  `validateModel` reports a hub without an end or legs as `incomplete-hub`, with the hub's id as
+  `linkId`.
+- **On disk.** An entry in `links` holds `{ hub, starts, end }`, with no id of its own and no
+  `text` on the hub, as DSM3-goals writes it. The entry's unknown keys are kept on the hub's
+  `extra[HUB_ENTRY_KEY]` and written back. Hubs never appear in `orphans`.
+
+### Links that target links
+
+A link kind may point at another link, like NFR's Argument, which is a Claim about a Contribution.
+Its `rules.targets` holds `link` (any link) or link kind names:
+
+```ts
+{ kind: 'nfr.ArgumentLink', rules: { sources: ['nfr.Claim'], targets: ['link'], sameActor: false } }
+```
+
+- **Checks.** `canLink(model, claim, contributionLinkId, 'nfr.ArgumentLink')` looks the target up
+  among elements, then links. Element selectors never match a link, and link selectors never
+  match an element. The self-link, dependum and same-actor rules don't apply to a link target.
+  iStar 2.0's built-in rules refuse one.
+- **Predicates.** `LinkRuleContext.target` is an `IstarElement` or an `IstarLink`, so narrow it
+  with `isLinkRef`. `linkTargetOf(model, link)` returns what a link points at.
+- **Models.** `validateModel` checks links that target links after the others, whatever their
+  order in the file. Removing a link removes the links that target it. `linksOf(model, linkId)`
+  lists them.
+
 ## A model's own metamodel
 
 A file can declare the constructs it adds to iStar in a top-level `"metamodel"` block, so they
@@ -304,6 +436,15 @@ toPistar(extended); // writes the "metamodel" block
   into a store (`store.load` or `store.replace`) to keep editing.
 - `pistarType` works as for any extension, so `istar.<Name>` types on disk still read.
 
+## Diagnostics
+
+`GoalDiagnostic` (`{ elementId, key?, severity, message, source?, range?, code?, data? }`) is the
+data shape for findings about elements and links. Analysers publish them per source to a
+`createDiagnosticsStore()`; `getAll()` returns the union of every source, deduplicated by
+`(elementId, key, message)`. `fromLspDiagnostics` and `fromNodeIdDiagnostics` adapt LSP and MutRoSe
+diagnostics. Diagnostics are never part of the model and never serialized. `@istar-ts/react`
+shows them as badges and in the inspector (see its README).
+
 ## Credits
 
 The metamodel, link constraints, element shapes, and file format are derived from