@peter.prib/renderengine 0.2.10 → 0.4.0

package/src/charting/model/EditableModel.js

@@ -0,0 +1,104 @@
+import { CommandHistory } from '../CommandHistory.js';
+import { ModelComparison } from '../diagramModel/ModelComparison.js';
+import { ModelEditCommand } from './ModelEditCommand.js';
+
+/**
+ * EditableModel — base of a model edited as a whole rather than view by view
+ * (DataModel, RequirementsModel; a ViewSetModel keeps its views' histories
+ * its own way). What a part needs of any model it edits, keeps and merges:
+ *
+ * - a name;
+ * - whether it changed since it was saved (`edited()`, `markSaved()`,
+ *   `isDirty()`, `onEdit(fn)`), so a part shows it, keeps it and asks before
+ *   it is lost;
+ * - an undo history, every edit one step on it (`editCommand(label, change)`:
+ *   the model before and after, as its toJSON, put back by `restore`);
+ * - how it differs from another of its kind (`compareWith`, over the
+ *   subclass's `comparedKinds()`), which merges the other's into it.
+ *
+ * A subclass gives `toJSON()`, its constructor reading that back, and
+ * `static STATE`: the fields `restore` puts back.
+ */
+export class EditableModel {
+    /** The fields a snapshot puts back (restore). A subclass lists its own, `name` among them. */
+    static STATE = Object.freeze(['name']);
+
+    /** @param {{name?: string}} [spec] */
+    constructor(spec = {}) {
+        if (new.target === EditableModel) throw new TypeError('EditableModel is abstract — subclass it');
+        /** What the model is called. */
+        this.name = spec.name ?? '';
+        this._version = 0;
+        this._saved = 0;
+        this._editListeners = [];
+    }
+
+    /** The kinds it is compared on and merged by (ComparedKind), in the order a merge brings them. None here. */
+    comparedKinds() {
+        return [];
+    }
+
+    /** How this model differs from another (ModelComparison), which can merge the other's into it. */
+    compareWith(other) {
+        return new ModelComparison(this, other);
+    }
+
+    /** Its undo history: a merge is one step on it. */
+    get history() {
+        return (this._history ??= new CommandHistory());
+    }
+
+    /** A change made as one undo step (ModelEditCommand), not yet run. */
+    editCommand(label, change) {
+        return new ModelEditCommand(this, label, change);
+    }
+
+    /** Put the model back as a snapshot (its toJSON) says: the fields its class lists (STATE). */
+    restore(json) {
+        const back = new this.constructor(JSON.parse(JSON.stringify(json)));
+        for (const key of this.constructor.STATE) this[key] = back[key];
+    }
+
+    // ===== Changed since saved =====
+
+    /** Something changed: listeners hear of it. */
+    edited() {
+        this._version++;
+        this._emitEdit();
+    }
+
+    /** This state is the saved one (a file opened or saved). */
+    markSaved() {
+        this._saved = this._version;
+        this._emitEdit();
+    }
+
+    /** Whether it changed since markSaved. */
+    isDirty() {
+        return this._version !== this._saved;
+    }
+
+    /** Call `fn(model)` after every change (and markSaved). Returns an unsubscribe function. */
+    onEdit(fn) {
+        this._editListeners.push(fn);
+        return () => { this._editListeners = this._editListeners.filter(l => l !== fn); };
+    }
+
+    /** @private */
+    _emitEdit() {
+        for (const fn of this._editListeners) fn(this);
+    }
+
+    /** An id made from `name`, unlike any of `taken`'s ids ('customer', 'customer-2'). */
+    _freshId(name, taken) {
+        const base = String(name ?? 'item').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'item';
+        let id = base;
+        for (let n = 2; taken.some(t => t.id === id); n++) id = `${base}-${n}`;
+        return id;
+    }
+
+    /** The model as plain JSON, read back by its constructor. @abstract */
+    toJSON() {
+        throw new Error(`${this.constructor.name} must implement toJSON()`);
+    }
+}

package/src/charting/{datamodel/DataModelEditCommand.js → model/ModelEditCommand.js}

@@ -1,47 +1,47 @@
-import { Command } from '../CommandHistory.js';
-
-/**
- * DataModelEditCommand — one edit of a DataModel (an entity, an attribute, a
- * relationship, a delete) as one undo step: run, it makes the change and keeps
- * the model as it was before and after (DataModel#toJSON); undone or redone, it
- * puts the model back as it was (DataModel#restore). Any change to a model is
- * undoable this way, whatever it touches.
- */
-export class DataModelEditCommand extends Command {
-    /** A model edit is no edit on one view: undoing it shows no other. */
-    viewId = null;
-
-    /**
-     * @param {DataModel} model
-     * @param {string} label - What the undo menu calls it ('Edit Customer')
-     * @param {(model: DataModel) => *} change - Makes the change
-     */
-    constructor(model, label, change) {
-        super(label);
-        this.model = model;
-        this.change = change;
-        this.before = null;
-        this.after = null;
-    }
-
-    execute() {
-        if (this.after) {
-            this.model.restore(this.after);
-        } else {
-            this.before = DataModelEditCommand.snapshot(this.model);
-            this.result = this.change(this.model);
-            this.after = DataModelEditCommand.snapshot(this.model);
-        }
-        this.model.edited();
-    }
-
-    undo() {
-        this.model.restore(this.before);
-        this.model.edited();
-    }
-
-    /** The model as it is, a copy nothing later changes (its toJSON shares some arrays). */
-    static snapshot(model) {
-        return JSON.parse(JSON.stringify(model.toJSON()));
-    }
-}
+import { Command } from '../CommandHistory.js';
+
+/**
+ * ModelEditCommand — one edit of an EditableModel (a data model's entity, a
+ * requirements model's story, a delete) as one undo step: run, it makes the
+ * change and keeps the model as it was before and after (its toJSON); undone
+ * or redone, it puts the model back as it was (its restore). Any change to a
+ * model is undoable this way, whatever it touches.
+ */
+export class ModelEditCommand extends Command {
+    /** A model edit is no edit on one view: undoing it shows no other. */
+    viewId = null;
+
+    /**
+     * @param {EditableModel} model
+     * @param {string} label - What the undo menu calls it ('Edit Customer')
+     * @param {(model: EditableModel) => *} change - Makes the change
+     */
+    constructor(model, label, change) {
+        super(label);
+        this.model = model;
+        this.change = change;
+        this.before = null;
+        this.after = null;
+    }
+
+    execute() {
+        if (this.after) {
+            this.model.restore(this.after);
+        } else {
+            this.before = ModelEditCommand.snapshot(this.model);
+            this.result = this.change(this.model);
+            this.after = ModelEditCommand.snapshot(this.model);
+        }
+        this.model.edited();
+    }
+
+    undo() {
+        this.model.restore(this.before);
+        this.model.edited();
+    }
+
+    /** The model as it is, a copy nothing later changes (its toJSON may share arrays). */
+    static snapshot(model) {
+        return JSON.parse(JSON.stringify(model.toJSON()));
+    }
+}

package/src/charting/requirements/RequirementsChecker.js

@@ -0,0 +1,76 @@
+import { ModelChecker } from '../ModelChecker.js';
+
+/**
+ * RequirementsChecker — what a requirements model is missing, as a team
+ * reviewing a backlog would say it: a story with no acceptance criteria
+ * (nothing to say when it is done), one that says neither who wants it nor
+ * what (no "As a … I want …"), one that traces to nothing (nothing realises
+ * it), one under no epic, an epic with no stories, two stories of one name.
+ *
+ * With `resolve(trace)` — the host's way to find what a trace names in its
+ * other models (true, false, or undefined when it cannot tell) — a trace to
+ * something that is not there is found too.
+ *
+ * Findings name a story or an epic (`kind`), as ModelChecker's do.
+ */
+export class RequirementsChecker extends ModelChecker {
+    /**
+     * @param {RequirementsModel} model
+     * @param {{resolve?: (trace: Object) => (boolean|undefined)}} [options]
+     */
+    constructor(model, { resolve = null } = {}) {
+        super(model);
+        this.resolve = resolve;
+    }
+
+    checks() {
+        return [this.noCriteria, this.noNarrative, this.untraced, this.brokenTraces, this.noEpic, this.emptyEpics, this.sameNames];
+    }
+
+    /** @private */
+    _story(story, code, severity, message) {
+        return { code, severity, kind: 'story', ids: [story.id], message };
+    }
+
+    noCriteria() {
+        return this.model.stories.filter(s => !s.criteria.length)
+            .map(s => this._story(s, 'story-no-criteria', 'warning', `"${s.name}" has no acceptance criteria: nothing says when it is done`));
+    }
+
+    noNarrative() {
+        return this.model.stories.filter(s => !s.want && !s.description)
+            .map(s => this._story(s, 'story-no-narrative', 'info', `"${s.name}" says neither who wants it nor what (As a … I want … so that …)`));
+    }
+
+    untraced() {
+        return this.model.stories.filter(s => !s.traces.length)
+            .map(s => this._story(s, 'story-untraced', 'info', `"${s.name}" traces to nothing that realises it`));
+    }
+
+    brokenTraces() {
+        if (!this.resolve) return [];
+        return this.model.stories.flatMap(s => s.traces.filter(t => this.resolve(t) === false)
+            .map(t => this._story(s, 'trace-missing', 'warning', `"${s.name}" traces to ${t.kind} "${t.name || t.ref}", which is not there`)));
+    }
+
+    noEpic() {
+        if (!this.model.epics.length) return [];
+        return this.model.stories.filter(s => !this.model.epic(s.epic))
+            .map(s => this._story(s, 'story-no-epic', 'info', `"${s.name}" is under no epic`));
+    }
+
+    emptyEpics() {
+        return this.model.epics.filter(e => !this.model.storiesOf(e.id).length)
+            .map(e => ({ code: 'epic-empty', severity: 'info', kind: 'epic', ids: [e.id], message: `Epic "${e.name}" has no stories` }));
+    }
+
+    sameNames() {
+        const byName = new Map();
+        for (const s of this.model.stories) {
+            const key = s.name.trim().toLowerCase();
+            if (key) byName.set(key, [...(byName.get(key) ?? []), s]);
+        }
+        return [...byName.values()].filter(list => list.length > 1)
+            .map(list => ({ code: 'story-duplicate', severity: 'warning', kind: 'story', ids: list.map(s => s.id), message: `${list.length} stories are called "${list[0].name}"` }));
+    }
+}

package/src/charting/requirements/RequirementsCompared.js

@@ -0,0 +1,33 @@
+import { ListCompared } from '../diagramModel/ListCompared.js';
+
+/**
+ * The kinds two RequirementsModels are compared on and merged by
+ * (ModelComparison): epics, releases, then stories, in the order a merge
+ * brings them — a story needs its epic and its release.
+ */
+
+export class EpicsCompared extends ListCompared {
+    get key() { return 'epic'; }
+    get label() { return 'Epics'; }
+    list(model) { return model.epics; }
+    content(epic) { return { ...epic }; }
+}
+
+export class ReleasesCompared extends ListCompared {
+    get key() { return 'release'; }
+    get label() { return 'Releases'; }
+    list(model) { return model.releases; }
+    content(release) { return { ...release }; }
+}
+
+/** Stories: compared on everything, where they sit in the list aside. */
+export class StoriesCompared extends ListCompared {
+    get key() { return 'story'; }
+    get label() { return 'Stories'; }
+    list(model) { return model.stories; }
+    content(story) { return JSON.parse(JSON.stringify(story)); }
+
+    requires(story) {
+        return [...(story.epic ? [['epic', story.epic]] : []), ...(story.release ? [['release', story.release]] : [])];
+    }
+}

package/src/charting/requirements/RequirementsFileFormat.js

@@ -0,0 +1,32 @@
+import { ModelFileFormat } from '../ModelFileFormat.js';
+import { RequirementsModel } from './RequirementsModel.js';
+
+/**
+ * RequirementsFileFormat — a requirements model as a file
+ * (`.requirements.json`): its epics, releases and stories
+ * (RequirementsModel#toJSON), read back by `new RequirementsModel(json)`.
+ */
+export class RequirementsFileFormat extends ModelFileFormat {
+    get label() { return '.requirements.json'; }
+    get accept() { return '.requirements.json,.json'; }
+    get fileName() { return 'model.requirements.json'; }
+    get featureName() { return 'Requirements'; }
+
+    /** JSON with a requirements model's shape: stories, or epics. */
+    recognizes(text) {
+        try {
+            const json = JSON.parse(text);
+            return !!json && typeof json === 'object' && (Array.isArray(json.stories) || Array.isArray(json.epics));
+        } catch {
+            return false;
+        }
+    }
+
+    export(model) {
+        return { data: JSON.stringify(model.toJSON(), null, 2), mimeType: 'application/json' };
+    }
+
+    import(text) {
+        return new RequirementsModel(JSON.parse(text));
+    }
+}

package/src/charting/requirements/RequirementsImportFormats.js

@@ -0,0 +1,48 @@
+import { ModelFileFormat } from '../ModelFileFormat.js';
+import { RequirementsModel } from './RequirementsModel.js';
+import { TrackerExport } from './TrackerExport.js';
+import { Storyboard } from './Storyboard.js';
+
+/**
+ * The files a requirements model is read from that another tool wrote — they
+ * import only: a tracker's export (TrackerExport: Jira, Azure DevOps,
+ * GitLab, CSV or JSON) and a storyboard (Storyboard: Markdown). Each reads
+ * the file as a new model; `spec(text)` is what it holds, for a part that
+ * brings it into the model open (RequirementsModel#bringCommand).
+ */
+class RequirementsImportFormat extends ModelFileFormat {
+    get exports() { return false; }
+
+    /** What the file holds, as a RequirementsModel spec. @abstract */
+    spec(text) { throw new Error(`${this.constructor.name} must implement spec()`); }
+
+    import(text) {
+        return new RequirementsModel(this.spec(text));
+    }
+}
+
+export class TrackerExportFileFormat extends RequirementsImportFormat {
+    get label() { return 'Tracker export (Jira, Azure DevOps, GitLab)'; }
+    get accept() { return '.csv,.json'; }
+    get featureName() { return 'TrackerExport'; }
+
+    /** A CSV or JSON export one of the trackers wrote. */
+    recognizes(text) {
+        return !!TrackerExport.detect(text);
+    }
+
+    spec(text) {
+        const { tracker, ...spec } = new TrackerExport().read(text);
+        return { name: `${TrackerExport.label(tracker)} export`, ...spec };
+    }
+}
+
+export class StoryboardFileFormat extends RequirementsImportFormat {
+    get label() { return 'Storyboard (Markdown)'; }
+    get accept() { return '.md,.markdown,.txt'; }
+    get featureName() { return 'Storyboard'; }
+
+    spec(text) {
+        return new Storyboard().read(text);
+    }
+}