@peter.prib/renderengine 0.2.11 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # RenderEngine
 
-**An ArchiMate modeller, a data modeller, a diagram editor and a chart library that run in any browser tab, with
-no install and no runtime dependencies.**
+**An ArchiMate modeller, a data modeller, a requirements story map, a diagram editor and a chart library that run
+in any browser tab, with no install and no runtime dependencies.**
 
 Open an Archi model, edit it the way you would in Archi, and save it back to the same `.archimate` file, without
 installing anything. Model data at three levels, governed and checked the way DAMA-DMBOK2 has it, with banking at
@@ -167,6 +167,20 @@ the browser and backed up.
 
 ---
 
+## Requirements and story maps
+
+Bring in the epics and stories your team already has: a Jira, Azure DevOps or GitLab export (CSV or JSON), or a
+storyboard written in Markdown. Read as a **story map** (epics across, releases down) or a **backlog**, each story
+carries its "As a … I want … so that …", its acceptance criteria (read from their own field, a list in the
+description, or Given/When/Then) and its **traces** to what realises it: an ArchiMate requirement or work package,
+a component, a data concept, entity or table. Drag a card to another epic or release; the toolbar says how many
+stories say when they are done and how many trace to something, and **Check model** lists what is missing.
+
+- **Every model alike**: kept, compared and merged as the ArchiMate and data models are, a newer tracker export
+  brought in over the old one replacing what changed.
+- **Yours to extend**: a host says what can be traced to, what a story's live state is, and how to find stories by
+  meaning (a vector store) — the SqlEngine workbench does all three.
+
 ## The diagram editor
 
 The ArchiMate modeller is built on a general diagram editor, and every editing feature above is part of that
@@ -237,10 +251,12 @@ page:
 </script>
 ```
 
-Use `editorType: 'diagram-editor'` with `DiagramEditorPart` for the diagram editor, and `editorType: 'data-model'`
-with `DataModelPart` for the data modeller. The models are plain JavaScript APIs (`ArchimateModel`, `DiagramModel`,
-`DataModel`), so you can also build, check, score, search, report on and export models with no UI at all, under
-Node too: `new DataModel(spec).checker().run()`, `new SqlDdl().write(model)`.
+Use `editorType: 'diagram-editor'` with `DiagramEditorPart` for the diagram editor, `editorType: 'data-model'`
+with `DataModelPart` for the data modeller, and `editorType: 'requirements'` with `RequirementsPart` for the story
+map. The models are plain JavaScript APIs (`ArchimateModel`, `DiagramModel`, `DataModel`, `RequirementsModel`), so
+you can also build, check, score, search, report on and export models with no UI at all, under Node too:
+`new DataModel(spec).checker().run()`, `new SqlDdl().write(model)`,
+`new RequirementsModel(new TrackerExport().read(csv)).coverage()`.
 
 ---
 

package/REFERENCE.md

@@ -881,6 +881,12 @@ types — see `ARCHITECTURE.md`):
   `LevelSchema.resolveReference(ref)`: the whole text as a table (by id or name, any case), else what is before its
   last dot as the table and the rest as its column — `{ entity, column }`, or null.
 
+  **Edit ▸ Lay out.** The level shown is laid out again by one of the arrangement's layouts (`LAYOUTS`: grid, circle,
+  a tree down or right, force-directed, by kind — the same ones a diagram's Arrange ▸ Layout uses), its relationships
+  guiding the trees and the force, only what the perspective draws moving (`part.layoutCommand(kind)`, one undo
+  step; where each box goes is kept as a drag would keep it). Not the mapping view or the other views, which lay
+  themselves out.
+
   **A dimensional scheme.** At the logical and physical levels an entity may have a role (`EntityRole`, registered as
   relationship kinds are): a **fact** (`FactRole`, `role: 'fact'`: what is measured, at a stated `grain`, its
   attributes' `measure` additive, semi-additive or non-additive) or a **dimension** (`DimensionRole`: its `scdType`,
@@ -1623,7 +1629,10 @@ sharing the spec's data cannot reach them). File ▸ New ▸ **From base: …**
 `models.baseItems()`) opens a model as a copy of one; Tools ▸ **Compare with** and **Merge from** offer them, after
 the other open models (`models.toolItems(part)`); File ▸ **Duplicate model** (`models.duplicate(part)`) opens a copy
 of the model in front, written and read back through its own file format. A copy, from a base or duplicated, is named
-"… (copy)" (`ModelsPart.copyName`, the suffix once).
+"… (copy)" (`ModelsPart.copyName`, the suffix once). A host whose reference models change (a live database
+whose schema changed) gives them afresh with `models.setBases(specs)`; what is open is left alone. File ▸ New ▸ **View base: …**
+(`models.viewBase(i)`) opens a base to look at: a tab of its own copy, named "… (view)", that can be laid out and
+moved about but is never kept (`part.keepOff`).
 
 **Kept in this browser, and backed up.** With `keep: true` in its spec, a `ModelsPart` keeps every model it holds
 in this browser, so work outlives the page without saving a file: a moment after each edit (`ModelsPart.KEEP_DELAY`)
@@ -1640,6 +1649,38 @@ as a history, and under its plain name too (`keepUnstamped`); where a folder can
 permission refused) they download instead. `backups.log()` records each (newest first, `LOG_MAX`), and
 `backups.daysSinceLast()` how long ago the last was. `examples/archimate.html` keeps its models.
 
+**A host's live status, and its menu items.** A host subclass of `ArchimateCanvasPart` says what it knows of an
+element that the model does not: `elementStatus(element)` → `{ text, color }` (or null) is drawn as a pill inside
+the bottom right of each of the element's boxes, asked afresh whenever the view is drawn and never written to the
+model; `elementMenuExtras(element)` → menu items end a box's right-click menu and the element's menu in the model
+tree. The canvas editor takes them as options (`ArchimateCanvasEditor`'s `elementStatus`, `elementMenuExtras`;
+the part hands them over in `editorHooks()`); a box's status is its template's `status` (`statusPill(ctx)`).
+
+```js
+class LiveArchitecture extends ArchimateCanvasPart {
+    elementStatus(el) { const s = states.get(el.id); return s ? { text: s, color: s === 'deployed' ? '#2e7d32' : '#f9a825' } : null; }
+    elementMenuExtras(el) { return transitions(el.id).map(t => ({ label: t, action: () => fire(el.id, t) })); }
+}
+```
+
+**Kept where the host says.** A host keeps the models itself by giving a library among the workspace's services
+(`ws.services = { modelLibrary }`, reaching the part as `ctx.modelLibrary`): anything with `ModelLibrary`'s methods
+(`keep`, `load`, `list`, `openOnes`, `setOpen`, `remove`) and a `label`, which the File menu and the tab menu use in
+place of **This browser** (`models.keptWhere`). An entry is the model in its editor's file format, so the host
+stores it as it likes — a database row, a file, a graph read from it. The backup folder's handle stays in the
+browser's store.
+
+```js
+ws.services = { modelLibrary: new ModelLibrary(myStore, { label: 'The engine' }) };   // myStore: a KeyValueStore
+```
+
+**Proposals.** A model offered as a change to the one in front — by an agent, a colleague, an import — waits as a
+proposal: `models.propose({ title, rationale, source, spec })`, `spec` a model as the editor takes it (as a base is
+given). Tools ▸ **Proposals (n)** lists them (`models.proposalItems(part)`); **Review and merge…**
+(`models.reviewProposal(part, p)`) is the merge dialog with who proposed it and why above the differences
+(`ModelMergeDialog`'s `note`), so what is taken is chosen and is one undo step; taking it, or **Dismiss**
+(`models.dismissProposal(p)`), removes it from the list.
+
 ```js
 ws.addParts([{ id: 'models', type: 'models', editorType: 'archimate-canvas', newModel: { analysis: true },
     models: [{ id: 'modeller', title: 'Sample model', elements: [...], views: [...] }] }]);
@@ -1738,7 +1779,8 @@ editor.colourByCommand('property:Lifecycle', { invest: '#98fb98', maintain: '#ff
 **Layouts, in every editor.** The toolbar's **Arrange** menu has **Layout** (**Layout the view** with fewer than two
 shapes selected): **Grid**, **Circle**, **Tree, top down**, **Tree, left to right** (along the lines between the
 shapes: a parent centred over its children; a shape no line reaches is a root), **Force-directed** (lines pull,
-shapes push apart; the same input gives the same result) and **By kind, a row each** (the shape class in the
+shapes push apart, within a frame round where they were, so one no line reaches stays near the rest; the same
+input gives the same result) and **By kind, a row each** (the shape class in the
 template editor, the layer on the ArchiMate canvas). The shapes keep the top-left corner of the area they took;
 what a container holds goes with it; one undo step; a locked shape stops it. On the ArchiMate canvas, an element
 with parts on the view (the targets of its composition and aggregation relationships) has **Nest its parts inside**
@@ -2520,6 +2562,94 @@ class. Library code imports its collaborators directly rather than looking them
 `undo()` rather than checking `instanceof Command`. A command built from either bundle therefore
 works in either bundle's history.
 
+### Models edited as a whole: `EditableModel` and `ModelHosted`
+
+A model edited as a whole rather than view by view extends `EditableModel` (`DataModel`, `RequirementsModel`): a
+`name`; changed since saved (`edited()`, `markSaved()`, `isDirty()`, `onEdit(fn)`); an undo history
+(`model.history`), every edit one step on it — `model.editCommand(label, change)` keeps the model before and after
+as its `toJSON()` and puts it back with `restore` (the fields the class lists in `static STATE`); and
+`compareWith(other)` over its `comparedKinds()`, which merges the other's into it. A list of things with ids is
+compared and merged by a `ListCompared` subclass (`list(model)`, `content(item)`, `requires(item)`).
+
+Its part mixes in `ModelHosted` (`class DataModelPart extends ModelHosted(ChartPart)`): the file (`part.file`, a
+`ModelFile`), `keepId`/`keepEntry()` for a `ModelsPart`, the File menu (Open…, Save, Save As…, **Import ▸** each
+format that only reads — another tool's export, `format.exports === false`, opened as a new model — then New,
+Duplicate, Close model, where models are kept), `undoItems()`, `runModelEdit(command)` (then `afterModelEdit()`,
+the part's redraw) and `readInto({ accept, command, … })` (a file read into the model as one undo step).
+
+**The bench.** `Benchmark.of(model)` is what a model is measured by — `[{ key, label, value, better: 'lower' |
+'higher', format }]`: every model's check warnings and findings (`Benchmark.findings`), and a model's own
+`benchmark()` beyond them (a data model's Scorecard total, a requirements model's share of stories with
+acceptance criteria and of stories traced). `Benchmark.compare(before, after)` says of each whether it got better,
+worse or stayed, `Benchmark.text(rows)` in a line. A `ModelsPart` proposal's review says how the proposal, taken
+whole, would move them (`modelsPart.proposalBench(part, proposal)`), so an agent's suggestion is judged by the
+model's own checks. `modelsPart.propose({ title, rationale, source, spec | entry, onSettle })` takes the model as
+a spec or as an `entry` in one of the editor's file formats (`{ format, data }`, as a kept model is — what a
+server hands back); `onSettle(outcome, { bench })` hears whether it was `'taken'` (with how what was taken moved
+the bench) or `'dismissed'`, once, so whoever proposed it can record the outcome. A host adds its own tools for the model in front
+— an agent to run on it — as `modelTools(part, models)` among the workspace's services (`workspace.services`);
+their items end the Tools menu.
+
+### Requirements: epics, stories and the story map
+
+`RequirementsModel` holds what a system is to do as an agile team writes it: **epics**, the **stories** that deliver
+them ("As a … I want … so that …": `as`, `want`, `soThat`), each with **acceptance criteria**, sliced into
+**releases**, and **traces** from a story to what realises it in the other models — `{ kind, ref, name?, model? }`,
+`kind` one of `RequirementsModel.TRACE_KINDS` (an ArchiMate requirement or work package, an element, a data
+concept, entity or table) or any other. `storyMap()` gives the map: `columns` the epics (then *No epic*), `rows`
+the releases (then *Not planned*), `cell(epicId, releaseId)` the stories there. `tracingTo(ref, kind?)` says what
+a change to something touches; `coverage()` how complete it is (stories with criteria, traced; each a share);
+`checker()` (`RequirementsChecker`) what is missing — no criteria, no narrative, traced to nothing (or, with
+`resolve(trace)`, to something not there), no epic, an empty epic, two stories of one name. Every edit is a
+command (`saveStoryCommand`, `moveStoryCommand`, `traceCommand`, `bringCommand`, …), merged and compared as the
+other models are (a story brings its epic and release). Saved as `.requirements.json` (`RequirementsFileFormat`).
+
+Read from what teams already have — each an import-only format, and `format.spec(text)` for bringing into an
+open model:
+
+- **A tracker's export** (`TrackerExportFileFormat`, `TrackerExport`): Jira, Azure DevOps or GitLab, CSV or their
+  API's JSON, told apart by its columns. Epics by issue type (GitLab's from its issues' epic), stories under them,
+  status, priority, points, labels and release (fix version, iteration, milestone); criteria from their own field,
+  else from the description (an "Acceptance criteria" list, or Given/When/Then); the sentence from the description
+  or title. Ids are the tracker's keys, so a newer export brought in replaces what it had. Where each tracker keeps
+  each field is data (`TRACKERS`); a team's own column is given with `new TrackerExport({ columns: { criteria:
+  ['Done when'] } })` (in Jira's JSON, a custom field's key).
+- **A tracker, live** (`TrackerApi`; `JiraApi`, `AzureDevOpsApi`, `GitLabApi`): the issues a connection names, read
+  through the tracker's API page by page — Jira by JQL (a project's by default; Cloud with an email and API token,
+  Server / Data Center with a personal access token), Azure DevOps by WIQL (a project's work items but its tasks,
+  200 at a time, each linked to its page in Boards), GitLab a project's issues (open and closed, filtered as its
+  issues API filters). `read()` is the JSON `TrackerExport` reads, `model()` the model's spec, named as the
+  connection is; at most `maxIssues` (5000) are read, `truncated` saying when there were more. `fetch` is given,
+  since a tracker's token belongs where the request is made (a server); an error says what the tracker answered,
+  never the token. What a connection asks for is each class's `fields` (`trackerConnectionFields()`: per tracker,
+  `{key, label, type?, choices?, required?, secret?, placeholder?, hint?}`), for a host to build its form from;
+  `problems()` what is missing before the tracker is asked.
+- **A storyboard** (`StoryboardFileFormat`, `Storyboard`): Markdown — a `#` title names it, `##` are epics (or any
+  heading saying *Epic*), `###` stories (or *Story*); "As a … I want …" list items under an epic are stories; a
+  picture is kept by its caption.
+
+```javascript
+const { RequirementsModel, TrackerExport } = window.RenderEngine;
+const model = new RequirementsModel(new TrackerExport().read(jiraCsvText));
+model.storyMap().columns.map(c => c.name);   // the epics, across
+model.coverage().criteriaShare;              // how many stories say when they are done
+
+// The same, live — on a server, where the token is kept:
+const api = trackerApi({ tracker: 'jira', name: 'Shop backlog', baseUrl: 'https://shop.atlassian.net',
+    user: 'me@example.com', token: process.env.JIRA_TOKEN, project: 'SHOP' }, { fetch });
+const live = new RequirementsModel(await api.model());
+```
+
+`RequirementsPart` (type `requirements`, in a `ModelsPart` with `editorType: 'requirements'`) shows the model as
+the **story map** (a card per story — its criteria, traces, points, status — dragged to another epic or release,
+or before another card; + adds one in a cell) or the **backlog** (a row per story); a card opened edits the story,
+right-clicked traces it (Trace to…) or removes it. Model ▸ New story / epic / release, **Bring in stories** (from a
+tracker's export or a storyboard, one undo step), **Check model…**; the toolbar says how complete it is. A host
+extends it by subclass: `traceTargets()` (what can be traced to, suggested in the dialog), `resolveTrace(trace)`
+(for the check), `storyStatus(story)` (a live state on the card), and `searchByMeaning(query)` — a promise of
+`[{ id, score }]` — which adds Model ▸ **Find by meaning…** (results listed in the `ModelCheckDialog`, which takes a
+`title` and `empty` text for any list of things to open).
+
 ### Toolbars and dialogs
 
 `MenuBar` renders a row of toolbar items and has no controls of its own. Each editor contributes its