@peter.prib/renderengine 0.2.11 → 0.5.0

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/AzureDevOpsApi.js

@@ -0,0 +1,55 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Azure DevOps (Boards) through its REST API: a WIQL query for a project's
+ * work items (but its tasks — TRACKERS), then the items, 200 at a time. Signs
+ * in with a personal access token. Each item's link is its page in Boards.
+ */
+export class AzureDevOpsApi extends TrackerApi {
+    static tracker = 'azure';
+
+    /** Most ids one work-items request takes. */
+    static BATCH = 200;
+
+    static API_VERSION = '7.1';
+
+    static baseUrlPlaceholder = 'https://dev.azure.com/your-organisation';
+
+    static tokenHint = 'A personal access token with Work Items (Read)';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'The project, e.g. Shop' },
+            { key: 'query', label: 'WIQL condition', placeholder: "[System.AreaPath] UNDER 'Shop\\Checkout' (and the project's)" },
+        ];
+    }
+
+    headers() {
+        return { Authorization: `Basic ${TrackerApi.base64(`:${this.connection.token}`)}` };
+    }
+
+    /** The WIQL: the project's work items, not its tasks, and the condition given. */
+    get wiql() {
+        const types = this.skipTypes.map(t => `'${t.replace(/'/g, "''")}'`).join(', ');
+        const condition = String(this.connection.query ?? '').trim();
+        return `SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project`
+            + (types ? ` AND [System.WorkItemType] NOT IN (${types})` : '')
+            + (condition ? ` AND (${condition})` : '')
+            + ' ORDER BY [System.Id]';
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const version = `api-version=${this.constructor.API_VERSION}`;
+        const { json } = await this.request(this.url(`/${project}/_apis/wit/wiql?${version}`), { method: 'POST', body: { query: this.wiql } });
+        const ids = (json.workItems ?? []).map(w => w.id);
+        const value = [];
+        for (let i = 0; i < ids.length; i += this.constructor.BATCH) {
+            const batch = ids.slice(i, i + this.constructor.BATCH);
+            const { json: items } = await this.request(this.url(`/${project}/_apis/wit/workitems?ids=${batch.join(',')}&${version}`));
+            const got = (items.value ?? []).map(w => ({ ...w, url: this.url(`/${project}/_workitems/edit/${w.id}`) }));
+            if (this.keep(value, got)) { this.truncated ||= i + batch.length < ids.length; break; }
+        }
+        return { value };
+    }
+}

package/src/charting/requirements/GitLabApi.js

@@ -0,0 +1,43 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * GitLab through its REST API: a project's issues, open and closed, 100 a
+ * page; filtered as its issues API filters (`labels=…&milestone=…`). Signs
+ * in with a personal, project or group access token. An issue's epic
+ * (GitLab Premium) is its epic.
+ */
+export class GitLabApi extends TrackerApi {
+    static tracker = 'gitlab';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://gitlab.com';
+
+    static tokenHint = 'An access token with read_api';
+
+    static get ownFields() {
+        return [
+            { key: 'project', label: 'Project', required: true, placeholder: 'group/project, or its id' },
+            { key: 'query', label: 'Filter', placeholder: 'labels=requirements&milestone=Release 2 (as the issues API takes)' },
+        ];
+    }
+
+    headers() {
+        return { 'PRIVATE-TOKEN': String(this.connection.token) };
+    }
+
+    async _read() {
+        const project = encodeURIComponent(String(this.connection.project).trim());
+        const issues = [];
+        for (let page = 1; page;) {
+            const params = new URLSearchParams(String(this.connection.query ?? '').trim());
+            for (const [k, v] of Object.entries({ state: params.get('state') ?? 'all', per_page: String(this.constructor.PAGE), page: String(page) })) params.set(k, v);
+            const { json, headers } = await this.request(this.url(`/api/v4/projects/${project}/issues?${params}`));
+            const got = Array.isArray(json) ? json : [];
+            const next = Number(headers?.get?.('x-next-page')) || (got.length === this.constructor.PAGE && !headers?.has?.('x-next-page') ? page + 1 : 0);
+            if (this.keep(issues, got)) { this.truncated ||= !!next; break; }
+            page = got.length ? next : 0;
+        }
+        return issues;
+    }
+}

package/src/charting/requirements/JiraApi.js

@@ -0,0 +1,69 @@
+import { TrackerApi } from './TrackerApi.js';
+
+/**
+ * Jira through its REST API: the issues a JQL query finds (a project's, by
+ * default), every field (custom ones too: story points, acceptance criteria).
+ * Jira Cloud signs in with an email and an API token and pages by token
+ * (`/rest/api/3/search/jql`); Jira Server and Data Center with a personal
+ * access token (no email), paging by offset (`/rest/api/2/search`).
+ */
+export class JiraApi extends TrackerApi {
+    static tracker = 'jira';
+
+    static PAGE = 100;
+
+    static baseUrlPlaceholder = 'https://your-site.atlassian.net';
+
+    static tokenHint = 'Jira Cloud: an API token (with the email above). Server / Data Center: a personal access token (no email).';
+
+    static get ownFields() {
+        return [
+            { key: 'edition', label: 'Jira', type: 'select', choices: [['cloud', 'Cloud'], ['server', 'Server / Data Center']], value: 'cloud' },
+            { key: 'user', label: 'Email', placeholder: 'The account the API token is for (Cloud)' },
+            { key: 'project', label: 'Project key', placeholder: 'SHOP — or leave it and give a JQL query' },
+            { key: 'query', label: 'JQL', placeholder: 'project = SHOP AND issuetype != Sub-task (instead of the project)' },
+        ];
+    }
+
+    problems() {
+        const out = super.problems();
+        if (!String(this.connection.project ?? '').trim() && !String(this.connection.query ?? '').trim()) out.push('A project key or a JQL query is needed.');
+        return out;
+    }
+
+    /** The JQL: the one given, else the project's issues in key order. */
+    get jql() {
+        const { query, project } = this.connection;
+        if (String(query ?? '').trim()) return String(query).trim();
+        return `project = "${String(project).trim().replace(/"/g, '\\"')}" ORDER BY key`;
+    }
+
+    headers() {
+        const { user, token } = this.connection;
+        return { Authorization: String(user ?? '').trim() ? `Basic ${TrackerApi.base64(`${String(user).trim()}:${token}`)}` : `Bearer ${token}` };
+    }
+
+    async _read() {
+        const issues = [];
+        const page = this.constructor.PAGE;
+        const query = (extra) => new URLSearchParams({ jql: this.jql, fields: '*all', maxResults: String(page), ...extra }).toString();
+        if (this.connection.edition === 'server') {
+            for (let startAt = 0; ; startAt += page) {
+                const { json } = await this.request(this.url(`/rest/api/2/search?${query({ startAt: String(startAt) })}`));
+                const got = json.issues ?? [];
+                const more = got.length > 0 && startAt + got.length < (json.total ?? 0);
+                if (this.keep(issues, got)) { this.truncated ||= more; break; }
+                if (!more) break;
+            }
+        } else {
+            for (let token = null; ;) {
+                const { json } = await this.request(this.url(`/rest/api/3/search/jql?${query(token ? { nextPageToken: token } : {})}`));
+                const got = json.issues ?? [];
+                token = json.isLast ? null : json.nextPageToken ?? null;
+                if (this.keep(issues, got)) { this.truncated ||= !!token; break; }
+                if (!token || !got.length) break;
+            }
+        }
+        return { issues };
+    }
+}

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);
+    }
+}