@peter.prib/renderengine 0.2.10 → 0.4.0

package/src/charting/requirements/RequirementsModel.js

@@ -0,0 +1,305 @@
+import { EditableModel } from '../model/EditableModel.js';
+import { EpicsCompared, ReleasesCompared, StoriesCompared } from './RequirementsCompared.js';
+import { RequirementsChecker } from './RequirementsChecker.js';
+import { Benchmark } from '../model/Benchmark.js';
+
+/** A plain copy of JSON-shaped data. */
+const copy = (value) => JSON.parse(JSON.stringify(value));
+
+/**
+ * What a story can trace to, and what its trace is called: ArchiMate's
+ * motivation and implementation elements, any other element of an
+ * architecture, and a data model's concepts, entities and tables — so a trace
+ * runs epic → story → requirement → component → entity → table. A trace's
+ * `kind` is any string; these are the ones offered.
+ */
+const TRACE_KINDS = Object.freeze([
+    ['requirement', 'Requirement (ArchiMate)'],
+    ['work-package', 'Work package (ArchiMate)'],
+    ['element', 'Architecture element'],
+    ['concept', 'Data concept'],
+    ['entity', 'Data entity'],
+    ['table', 'Table'],
+]);
+
+/** Where a story is in its life, in order; a status is any string, these are offered. */
+const STATUSES = Object.freeze(['To do', 'In progress', 'Done']);
+
+/**
+ * RequirementsModel — what a system is to do, as an agile team writes it:
+ * **epics** (large outcomes), the **stories** that deliver them ("As a … I
+ * want … so that …"), each with its **acceptance criteria**, sliced into
+ * **releases**; and **traces** from a story to what realises it in the other
+ * models (TRACE_KINDS: an ArchiMate requirement or work package, an element,
+ * a data concept, entity or table — `{kind, ref, name?, model?}`, `ref` that
+ * model's id).
+ *
+ * Read as a **story map** (`storyMap()`): epics across in order, releases
+ * down, each cell the stories of that epic in that release; stories with no
+ * epic or no release have a column and a row of their own. `coverage()` and
+ * the checker (RequirementsChecker) say what is missing — a story with no
+ * acceptance criteria, nothing realising it — the numbers a bench measures.
+ *
+ * Spec (its toJSON): `{ name?, epics: [{id, name, description?}], releases:
+ * [{id, name}], stories: [{id, name, epic?, release?, as?, want?, soThat?,
+ * description?, criteria: [{id, text}], status?, priority?, points?, labels?,
+ * source?: {system, key, url?}, traces: [{kind, ref, name?, model?}]}] }`.
+ * Ids are made from names when not given. Every edit is a command (one undo
+ * step); compare and merge, and changed-since-saved, are EditableModel's.
+ */
+export class RequirementsModel extends EditableModel {
+    static STATE = Object.freeze(['name', 'epics', 'releases', 'stories']);
+
+    static TRACE_KINDS = TRACE_KINDS;
+
+    static STATUSES = STATUSES;
+
+    /** A story map's column for stories with no epic, and its row for those in no release. */
+    static NO_EPIC = '';
+    static NO_RELEASE = '';
+
+    constructor(spec = {}) {
+        super(spec);
+        this.epics = [];
+        this.releases = [];
+        this.stories = [];
+        for (const e of spec.epics ?? []) this.epics.push(this._epic(e));
+        for (const r of spec.releases ?? []) this.releases.push(this._release(r));
+        for (const s of spec.stories ?? []) this.stories.push(this._story(s));
+    }
+
+    // ===== Reading =====
+
+    epic(id) { return this.epics.find(e => e.id === id) ?? null; }
+    release(id) { return this.releases.find(r => r.id === id) ?? null; }
+    story(id) { return this.stories.find(s => s.id === id) ?? null; }
+
+    /** The stories of an epic (NO_EPIC: of none), in order; with `release`, only those in it (NO_RELEASE: in none). */
+    storiesOf(epicId, release) {
+        return this.stories.filter(s => (s.epic || '') === (epicId || '')
+            && (release === undefined || (s.release || '') === (release || '')));
+    }
+
+    /** The story's sentence: "As a … I want … so that …", from what it has. */
+    static narrative(story) {
+        return [story.as && `As ${/^(a|an|the)\b/i.test(story.as) ? '' : 'a '}${story.as}`, story.want && `I want ${story.want}`, story.soThat && `so that ${story.soThat}`]
+            .filter(Boolean).join(', ');
+    }
+
+    /**
+     * The story map: `columns` the epics in order (then NO_EPIC, if any story
+     * has none), `rows` the releases in order (then NO_RELEASE, if any story is
+     * in none, or there are no releases), and `cell(epicId, releaseId)` the
+     * stories there, in order.
+     */
+    storyMap() {
+        const columns = [...this.epics.map(e => ({ id: e.id, name: e.name, epic: e }))];
+        if (this.stories.some(s => !this.epic(s.epic))) columns.push({ id: RequirementsModel.NO_EPIC, name: 'No epic', epic: null });
+        const rows = this.releases.map(r => ({ id: r.id, name: r.name, release: r }));
+        if (!rows.length || this.stories.some(s => !this.release(s.release))) rows.push({ id: RequirementsModel.NO_RELEASE, name: this.releases.length ? 'Not planned' : 'Stories', release: null });
+        const epicOf = (s) => (this.epic(s.epic) ? s.epic : RequirementsModel.NO_EPIC);
+        const releaseOf = (s) => (this.release(s.release) ? s.release : RequirementsModel.NO_RELEASE);
+        return {
+            columns, rows,
+            cell: (epicId, releaseId) => this.stories.filter(s => epicOf(s) === epicId && releaseOf(s) === releaseId),
+        };
+    }
+
+    /** The stories that trace to `ref` (with `kind`, only traces of that kind): what a change to it touches. */
+    tracingTo(ref, kind) {
+        return this.stories.filter(s => s.traces.some(t => t.ref === ref && (!kind || t.kind === kind)));
+    }
+
+    /**
+     * How complete it is, as numbers to measure by: stories, how many have
+     * acceptance criteria, how many trace to something, epics with no stories,
+     * and each as a share (0..1; 1 with nothing to count).
+     */
+    coverage() {
+        const stories = this.stories.length;
+        const withCriteria = this.stories.filter(s => s.criteria.length).length;
+        const traced = this.stories.filter(s => s.traces.length).length;
+        const emptyEpics = this.epics.filter(e => !this.storiesOf(e.id).length).length;
+        const share = (n, of) => (of ? n / of : 1);
+        return {
+            stories, withCriteria, traced, epics: this.epics.length, emptyEpics,
+            criteriaShare: share(withCriteria, stories), traceShare: share(traced, stories),
+        };
+    }
+
+    /** What it is measured by (Benchmark): its check's findings, and how many stories say when they are done and trace to something. */
+    benchmark() {
+        const c = this.coverage();
+        return [
+            ...Benchmark.findings(this),
+            { key: 'criteria', label: 'Stories with acceptance criteria', value: c.criteriaShare, better: 'higher', format: 'share' },
+            { key: 'traced', label: 'Stories traced', value: c.traceShare, better: 'higher', format: 'share' },
+        ];
+    }
+
+    /** Its checks (RequirementsChecker). */
+    checker(options) {
+        return new RequirementsChecker(this, options);
+    }
+
+    comparedKinds() {
+        return [new EpicsCompared(), new ReleasesCompared(), new StoriesCompared()];
+    }
+
+    // ===== Editing (each an editCommand: one undo step) =====
+
+    /** Add an epic (`id` null) or change one. The command's result is the epic. */
+    saveEpicCommand(id, spec) {
+        return this.editCommand(id ? `Edit epic ${spec.name ?? id}` : `New epic ${spec.name ?? ''}`.trim(), (model) => {
+            if (!id) { const epic = model._epic(spec); model.epics.push(epic); return epic; }
+            const epic = model.epic(id);
+            if (epic) Object.assign(epic, model._epic({ ...epic, ...spec, id }));
+            return epic;
+        });
+    }
+
+    /** Remove an epic; its stories stay, with no epic. */
+    removeEpicCommand(id) {
+        return this.editCommand(`Remove epic ${this.epic(id)?.name ?? id}`, (model) => {
+            model.epics = model.epics.filter(e => e.id !== id);
+            for (const s of model.stories) if (s.epic === id) s.epic = '';
+        });
+    }
+
+    /** Add a release (`id` null) or rename one. */
+    saveReleaseCommand(id, spec) {
+        return this.editCommand(id ? `Edit release ${spec.name ?? id}` : `New release ${spec.name ?? ''}`.trim(), (model) => {
+            if (!id) { const release = model._release(spec); model.releases.push(release); return release; }
+            const release = model.release(id);
+            if (release) Object.assign(release, model._release({ ...release, ...spec, id }));
+            return release;
+        });
+    }
+
+    /** Remove a release; its stories stay, planned in none. */
+    removeReleaseCommand(id) {
+        return this.editCommand(`Remove release ${this.release(id)?.name ?? id}`, (model) => {
+            model.releases = model.releases.filter(r => r.id !== id);
+            for (const s of model.stories) if (s.release === id) s.release = '';
+        });
+    }
+
+    /** Add a story (`id` null) or change one — what the spec leaves out kept. The command's result is the story. */
+    saveStoryCommand(id, spec) {
+        return this.editCommand(id ? `Edit ${spec.name ?? this.story(id)?.name ?? id}` : `New story ${spec.name ?? ''}`.trim(), (model) => {
+            if (!id) { const story = model._story(spec); model.stories.push(story); return story; }
+            const at = model.stories.findIndex(s => s.id === id);
+            if (at < 0) return null;
+            model.stories[at] = model._story({ ...model.stories[at], ...spec, id });
+            return model.stories[at];
+        });
+    }
+
+    removeStoryCommand(id) {
+        return this.editCommand(`Remove ${this.story(id)?.name ?? id}`, (model) => {
+            model.stories = model.stories.filter(s => s.id !== id);
+        });
+    }
+
+    /**
+     * Move a story on the map: to an epic and a release (NO_EPIC, NO_RELEASE:
+     * none), before another story there (`before`; none: last).
+     */
+    moveStoryCommand(id, { epic, release, before = null }) {
+        return this.editCommand(`Move ${this.story(id)?.name ?? id}`, (model) => {
+            const story = model.story(id);
+            if (!story || before === id) return;
+            if (epic !== undefined) story.epic = epic || '';
+            if (release !== undefined) story.release = release || '';
+            model.stories.splice(model.stories.indexOf(story), 1);
+            const at = before ? model.stories.findIndex(s => s.id === before) : -1;
+            model.stories.splice(at < 0 ? model.stories.length : at, 0, story);
+        });
+    }
+
+    /** Trace a story to something that realises it (`{kind, ref, name?, model?}`); once per kind and ref. */
+    traceCommand(storyId, trace) {
+        return this.editCommand(`Trace ${this.story(storyId)?.name ?? storyId} to ${trace.name || trace.ref}`, (model) => {
+            const story = model.story(storyId);
+            if (!story || story.traces.some(t => t.kind === trace.kind && t.ref === trace.ref)) return;
+            story.traces.push(RequirementsModel._trace(trace));
+        });
+    }
+
+    /** Remove a story's trace to `ref` (of `kind`, if given). */
+    untraceCommand(storyId, ref, kind) {
+        return this.editCommand(`Remove the trace of ${this.story(storyId)?.name ?? storyId}`, (model) => {
+            const story = model.story(storyId);
+            if (story) story.traces = story.traces.filter(t => !(t.ref === ref && (!kind || t.kind === kind)));
+        });
+    }
+
+    /**
+     * Bring epics, releases and stories in (an import): one undo step. One with
+     * the id of one there replaces it; the rest are added.
+     */
+    bringCommand({ epics = [], releases = [], stories = [] }, label = 'Import') {
+        return this.editCommand(label, (model) => {
+            const put = (list, item) => {
+                const at = list.findIndex(x => x.id === item.id);
+                if (at < 0) list.push(item); else list[at] = item;
+            };
+            for (const e of epics) put(model.epics, model._epic(e));
+            for (const r of releases) put(model.releases, model._release(r));
+            for (const s of stories) put(model.stories, model._story(s));
+        });
+    }
+
+    // ===== Its parts, read from a spec =====
+
+    /** @private */
+    _epic({ id, name = '', description = '', source } = {}) {
+        return {
+            id: id ?? this._freshId(name || 'epic', this.epics), name, description,
+            ...(source && { source: copy(source) }),
+        };
+    }
+
+    /** @private */
+    _release({ id, name = '' } = {}) {
+        return { id: id ?? this._freshId(name || 'release', this.releases), name };
+    }
+
+    /** @private */
+    _story(spec = {}) {
+        const { id, name = '', epic = '', release = '', as = '', want = '', soThat = '', description = '', status = '', priority = '', points = null, labels = [], source, criteria = [], traces = [] } = spec;
+        const story = {
+            id: id ?? this._freshId(name || 'story', this.stories), name, epic: epic ?? '', release: release ?? '',
+            as, want, soThat, description, status, priority,
+            points: Number.isFinite(Number(points)) && points !== null && points !== '' ? Number(points) : null,
+            labels: [...labels],
+            criteria: [],
+            traces: traces.map(t => RequirementsModel._trace(t)),
+            ...(source && { source: copy(source) }),
+        };
+        // A new criterion is numbered past every id the story's criteria have, so none is given twice.
+        const given = new Set(criteria.map(c => (typeof c === 'object' && c?.id) || null).filter(Boolean));
+        let n = 0;
+        const fresh = () => { let id; do id = `${story.id}-ac${++n}`; while (given.has(id)); given.add(id); return id; };
+        for (const c of criteria) {
+            const text = typeof c === 'string' ? c : c?.text;
+            if (!String(text ?? '').trim()) continue;
+            story.criteria.push({ id: (typeof c === 'object' && c.id) || fresh(), text: String(text).trim() });
+        }
+        return story;
+    }
+
+    /** @private */
+    static _trace({ kind = 'element', ref, name = '', model = '' } = {}) {
+        return { kind, ref: String(ref ?? ''), ...(name && { name }), ...(model && { model }) };
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            epics: copy(this.epics),
+            releases: copy(this.releases),
+            stories: copy(this.stories),
+        };
+    }
+}

package/src/charting/requirements/Storyboard.js

@@ -0,0 +1,94 @@
+import { criteriaFrom, narrativeFrom, withoutNarrative } from './TrackerExport.js';
+
+/**
+ * Storyboard — epics and stories from a storyboard or requirements document
+ * written in Markdown (or plain text with Markdown headings), as teams keep
+ * them beside or before a tracker:
+ *
+ * - a heading that says "Epic" (`## Epic: Checkout`) is an epic, one that says
+ *   "Story" (`### Story: Pay by card`) a story; otherwise the document's one
+ *   title (`#`) is its name, the next level down are epics and the level
+ *   below that stories;
+ * - under an epic, a list item that reads "As a … I want …" is a story too;
+ * - under a story, "As a … I want … so that …" is its narrative, the list
+ *   under "Acceptance criteria" (or its Given/When/Then lines) its criteria,
+ *   and the rest its description — a picture (`![caption](file)`) kept there
+ *   by its caption.
+ *
+ * `read(text)` gives a RequirementsModel spec (`{name, epics, stories}`); ids
+ * are made from names (prefix: `prefix`, so two storyboards read into one
+ * model stay apart).
+ */
+export class Storyboard {
+    /** @param {{prefix?: string}} [options] */
+    constructor({ prefix = '' } = {}) {
+        this.prefix = prefix;
+    }
+
+    read(text) {
+        const lines = String(text ?? '').replace(/\r\n?/g, '\n').split('\n');
+        const headings = lines.map((line, at) => ({ at, m: /^(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line) })).filter(h => h.m)
+            .map(({ at, m }) => ({ at, level: m[1].length, text: m[2].trim() }));
+        const kindOf = (h) => (/^epic\b/i.test(h.text) ? 'epic' : /^(user\s+)?story\b/i.test(h.text) || /\bas an?\s+\S/i.test(h.text) ? 'story' : null);
+        const top = Math.min(...headings.map(h => h.level));
+        const tops = headings.filter(h => h.level === top);
+        // One top heading, a title (#), names the document; its children are the epics.
+        const named = top === 1 && tops.length === 1 && !kindOf(tops[0]) && headings.length > 1;
+        const epicLevel = named ? top + 1 : top;
+        const strip = (t) => t.replace(/^(epic|(user\s+)?story)\s*[:\-–—]?\s*/i, '').trim();
+
+        const epics = [], stories = [];
+        const ids = new Set();
+        const idFor = (name, kind) => {
+            const base = `${this.prefix}${String(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || kind}`;
+            let id = base;
+            for (let n = 2; ids.has(id); n++) id = `${base}-${n}`;
+            ids.add(id);
+            return id;
+        };
+        const bodyOf = (h, i) => lines.slice(h.at + 1, headings[i + 1]?.at ?? lines.length).join('\n');
+        let epic = null;
+        headings.forEach((h, i) => {
+            if (named && h === tops[0]) return;
+            const kind = kindOf(h) ?? (h.level === epicLevel ? 'epic' : h.level === epicLevel + 1 ? 'story' : null);
+            const body = bodyOf(h, i);
+            if (kind === 'epic') {
+                epic = { id: idFor(strip(h.text), 'epic'), name: strip(h.text), description: '' };
+                epics.push(epic);
+                const listed = this._listedStories(body);
+                epic.description = listed.rest;
+                for (const s of listed.stories) stories.push({ ...s, id: idFor(s.name, 'story'), epic: epic.id });
+            } else if (kind === 'story') {
+                stories.push({ ...this._story(strip(h.text), body), id: idFor(strip(h.text), 'story'), epic: epic?.id ?? '' });
+            }
+        });
+        if (!headings.length || (!epics.length && !stories.length)) {
+            for (const s of this._listedStories(lines.join('\n')).stories) stories.push({ ...s, id: idFor(s.name, 'story') });
+        }
+        return { name: named ? tops[0].text : '', epics, stories };
+    }
+
+    /** A story from its heading and what is under it. @private */
+    _story(name, body) {
+        const pictures = [...body.matchAll(/!\[([^\]]*)\]\([^)]*\)/g)].map(m => m[1]).filter(Boolean);
+        const text = body.replace(/!\[([^\]]*)\]\([^)]*\)/g, '').trim();
+        const said = narrativeFrom(text);
+        const { as, want, soThat } = said.want ? said : narrativeFrom(name);
+        const { criteria, rest } = criteriaFrom(text);
+        const description = [withoutNarrative(rest), ...pictures.map(c => `Picture: ${c}`)].filter(Boolean).join('\n');
+        return { name, as, want, soThat, description, criteria };
+    }
+
+    /** "As a … I want …" list items: stories; the rest of the text, kept. @private */
+    _listedStories(body) {
+        const stories = [];
+        const rest = [];
+        for (const line of body.split('\n')) {
+            const item = /^\s*(?:[-*•+]|\d+[.)])\s+(.*)$/.exec(line);
+            const said = item && narrativeFrom(item[1]);
+            if (said?.want) stories.push({ name: said.want.replace(/^to\s+/i, '').replace(/^./, c => c.toUpperCase()), ...said, description: '', criteria: [] });
+            else rest.push(line);
+        }
+        return { stories, rest: rest.join('\n').trim() };
+    }
+}