@peter.prib/renderengine 0.2.11 → 0.5.0

package/src/charting/requirements/TrackerExport.js

@@ -0,0 +1,274 @@
+import { parseCsvTable } from '../../csvTable.js';
+
+/**
+ * Where each tracker's export keeps what a story needs: per tracker, the
+ * column names (CSV) each field may be under, first found wins; which issue
+ * types are epics; how its list fields are separated. One definition per
+ * tracker — the CSV and the JSON readers both map onto these fields. A host
+ * gives its own (a custom field's column) through `new TrackerExport({ columns })`.
+ */
+export const TRACKERS = Object.freeze({
+    jira: {
+        label: 'Jira',
+        // Columns only its exports have, to tell it by.
+        marks: ['Issue key', 'Issue Type'],
+        columns: {
+            key: ['Issue key', 'Key'], id: ['Issue id'], type: ['Issue Type'], title: ['Summary'],
+            description: ['Description'], parent: ['Parent', 'Parent id', 'Parent key', 'Custom field (Epic Link)', 'Epic Link'],
+            status: ['Status'], priority: ['Priority'],
+            points: ['Custom field (Story Points)', 'Story Points', 'Custom field (Story point estimate)', 'Story point estimate'],
+            release: ['Fix Version/s', 'Fix versions', 'Sprint'], labels: ['Labels'],
+            criteria: ['Custom field (Acceptance Criteria)', 'Acceptance Criteria'], url: [],
+        },
+        epicTypes: ['Epic'], skipTypes: ['Sub-task', 'Subtask'], labelSeparator: /[\s,]+/,
+    },
+    azure: {
+        label: 'Azure DevOps',
+        marks: ['Work Item Type'],
+        columns: {
+            key: ['ID'], id: ['ID'], type: ['Work Item Type'], title: ['Title', 'Title 1', 'Title 2', 'Title 3'],
+            description: ['Description'], parent: ['Parent'], status: ['State'], priority: ['Priority'],
+            points: ['Story Points', 'Effort', 'Size'], release: ['Iteration Path'], labels: ['Tags'],
+            criteria: ['Acceptance Criteria'], url: [],
+        },
+        epicTypes: ['Epic', 'Feature'], skipTypes: ['Task'], labelSeparator: /\s*;\s*/,
+    },
+    gitlab: {
+        label: 'GitLab',
+        marks: ['Issue ID', 'URL'],
+        columns: {
+            key: ['Issue ID', 'IID'], id: ['Issue ID', 'IID'], type: [], title: ['Title'], description: ['Description'],
+            parent: ['Epic ID'], parentName: ['Epic Title'], status: ['State'], priority: [], points: ['Weight'],
+            release: ['Milestone'], labels: ['Labels'], criteria: [], url: ['URL'],
+        },
+        epicTypes: [], skipTypes: [], labelSeparator: /\s*,\s*/,
+    },
+});
+
+/**
+ * Where Jira's JSON keeps what has no field of its own: custom fields, by key.
+ * Jira Cloud's "Story point estimate" is customfield_10016 unless a site
+ * changed it; a host names its own (`columns: { points: ['customfield_10026'] }`).
+ */
+const JIRA_FIELDS = Object.freeze({
+    points: ['story_points', 'storyPoints', 'customfield_10016'],
+    criteria: ['acceptanceCriteria'],
+});
+
+/** Text with HTML in it (Azure DevOps keeps descriptions as HTML) as lines of plain text. */
+function plainText(value) {
+    if (value == null) return '';
+    if (typeof value === 'object') return documentText(value);
+    return String(value)
+        .replace(/<\s*(br|\/p|\/div|\/li|\/h\d)\s*\/?>/gi, '\n').replace(/<\s*li[^>]*>/gi, '- ')
+        .replace(/<[^>]+>/g, '')
+        .replace(/&nbsp;/g, ' ').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&')
+        .replace(/\r\n?/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+/** Jira Cloud's description, a document of nodes, as text: each paragraph and list item a line. */
+function documentText(node) {
+    if (!node || typeof node !== 'object') return '';
+    if (node.type === 'text') return node.text ?? '';
+    const inner = (node.content ?? []).map(documentText).join('');
+    return ['paragraph', 'heading', 'listItem', 'codeBlock'].includes(node.type) ? `${node.type === 'listItem' ? '- ' : ''}${inner.trim()}\n` : inner;
+}
+
+/** The lines of a list: "- x", "* x", "1. x", "• x", "[ ] x" — each item a line, its marker gone. */
+function listItems(text) {
+    return String(text ?? '').split('\n')
+        .map(line => line.replace(/^\s*(?:[-*•+]|\d+[.)]|\[[ xX]?\])\s+/, '').trim())
+        .filter(Boolean);
+}
+
+/**
+ * Acceptance criteria in a story's text: the lines under an "Acceptance
+ * criteria" heading, else its Given/When/Then scenarios (one each), else none.
+ * @returns {{criteria: Array<string>, rest: string}} - and the text without them
+ */
+export function criteriaFrom(text) {
+    const s = plainText(text);
+    const heading = /^\s*(?:#+\s*|\*\*)?acceptance criteria\b[^\n]*\n/im.exec(s);
+    if (heading) {
+        const after = s.slice(heading.index + heading[0].length);
+        const end = after.search(/\n\s*\n\s*(?:#+\s|\*\*|[A-Z][^\n:]{0,40}:\s*\n)/);
+        const block = end < 0 ? after : after.slice(0, end);
+        return { criteria: listItems(block), rest: (s.slice(0, heading.index) + (end < 0 ? '' : after.slice(end))).replace(/\n{3,}/g, '\n\n').trim() };
+    }
+    const scenarios = [];
+    let current = null;
+    for (const line of s.split('\n')) {
+        const t = line.replace(/^\s*(?:[-*•]\s+)?/, '').trim();
+        if (/^given\b/i.test(t)) { current = [t]; scenarios.push(current); } else if (current && /^(when|then|and|but)\b/i.test(t)) current.push(t); else current = null;
+    }
+    if (scenarios.length) return { criteria: scenarios.map(lines => lines.join(' ')), rest: s.split('\n').filter(l => !/^\s*(?:[-*•]\s+)?(given|when|then|and|but)\b/i.test(l)).join('\n').trim() };
+    return { criteria: [], rest: s };
+}
+
+/** A field that holds only acceptance criteria: as criteriaFrom reads them, else each of its lines one. */
+function criteriaField(text) {
+    const found = criteriaFrom(text).criteria;
+    return found.length ? found : listItems(plainText(text));
+}
+
+/** "As a <who>, I want <what> so that <why>" in a text: its three parts (empty where it says nothing). */
+export function narrativeFrom(text) {
+    const m = /\bas an?\s+([^,\n]+?)\s*,?\s+i\s+(?:want|need|would like)\s+([^\n]+?)(?:\s*,?\s+so\s+that\s+([^\n]+?))?\s*(?:[.\n]|$)/i.exec(plainText(text));
+    return m ? { as: m[1].trim(), want: m[2].trim(), soThat: (m[3] ?? '').trim() } : { as: '', want: '', soThat: '' };
+}
+
+/** A text without its "As a … I want …" line: what is left to describe the story, once its sentence is read (narrativeFrom). */
+export function withoutNarrative(text) {
+    return String(text ?? '').replace(/^\s*\**\s*as an?\s[^\n]*\bi\s+(want|need|would like)\b[^\n]*\n?/im, '').trim();
+}
+
+/**
+ * TrackerExport — epics and stories from what an issue tracker exports: Jira,
+ * Azure DevOps or GitLab (TRACKERS), as CSV or as their API's JSON. An issue
+ * of an epic type becomes an epic (GitLab's epics are named by their issues'
+ * Epic ID and title); the rest become stories under their parent epic, with
+ * their status, priority, points, labels and release (fix version, iteration
+ * or milestone). Acceptance criteria come from their own field, else from
+ * the description (criteriaFrom); "As a … I want … so that …" from the
+ * description or the title (narrativeFrom). Each keeps where it came from
+ * (`source: {system, key, url?}`), and its id is the tracker's key, so
+ * reading a newer export over a model replaces what it had.
+ *
+ * `read(text)` gives a RequirementsModel spec (`{epics, releases, stories}`).
+ */
+export class TrackerExport {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.tracker] - 'jira', 'azure', 'gitlab' (default: told from the export)
+     * @param {Object<string, Array<string>>} [options.columns] - Column names to look in first, by field (in Jira's JSON, field keys)
+     */
+    constructor({ tracker = null, columns = {} } = {}) {
+        this.tracker = tracker;
+        this.columns = columns;
+    }
+
+    /** What a tracker is called ('Jira'). */
+    static label(tracker) {
+        return TRACKERS[tracker]?.label ?? 'Tracker';
+    }
+
+    /** Which tracker an export's columns (or JSON) are from, or null. */
+    static detect(text) {
+        const json = TrackerExport._json(text);
+        if (json) {
+            if (Array.isArray(json.issues) && json.issues[0]?.fields) return 'jira';
+            if (Array.isArray(json.value ?? json.workItems) && (json.value ?? json.workItems)[0]?.fields) return 'azure';
+            if (Array.isArray(json) && json[0] && 'iid' in json[0]) return 'gitlab';
+            return null;
+        }
+        const { columns } = parseCsvTable(text);
+        const has = new Set(columns.map(c => c.toLowerCase()));
+        const found = Object.entries(TRACKERS).find(([, t]) => t.marks.every(m => has.has(m.toLowerCase())));
+        return found?.[0] ?? null;
+    }
+
+    /** @private — an API's JSON, given as text or already parsed. */
+    static _json(text) {
+        if (text && typeof text === 'object') return text;
+        const s = String(text ?? '').trim();
+        if (!s.startsWith('{') && !s.startsWith('[')) return null;
+        try { return JSON.parse(s); } catch { return null; }
+    }
+
+    /**
+     * The export (its text; an API's JSON as text or parsed — TrackerApi) as a requirements model's spec.
+     * @returns {{epics: Array, releases: Array, stories: Array, tracker: string|null}}
+     */
+    read(text) {
+        const tracker = this.tracker ?? TrackerExport.detect(text) ?? 'jira';
+        const def = TRACKERS[tracker];
+        if (!def) throw new Error(`Unknown tracker: "${tracker}"`);
+        const json = TrackerExport._json(text);
+        const issues = json ? this._fromJson(tracker, json) : this._fromCsv(def, text);
+        return { ...this._model(tracker, def, issues), tracker };
+    }
+
+    /** CSV rows as issues: each field from the first of its columns there. @private */
+    _fromCsv(def, text) {
+        const { columns, rows } = parseCsvTable(text);
+        const lower = new Map(columns.map(c => [c.toLowerCase(), c]));
+        const columnOf = (field) => [...(this.columns[field] ?? []), ...(def.columns[field] ?? [])].map(c => lower.get(c.toLowerCase())).find(Boolean);
+        const fields = Object.keys({ ...def.columns, ...this.columns, parentName: [] });
+        const at = Object.fromEntries(fields.map(f => [f, columnOf(f)]));
+        return rows.map(row => Object.fromEntries(fields.map(f => [f, at[f] ? row[at[f]] : ''])));
+    }
+
+    /** An API's JSON as issues, in the CSV's fields. @private */
+    _fromJson(tracker, json) {
+        if (tracker === 'jira') {
+            return (json.issues ?? []).map(({ key, id, fields: f = {} }) => {
+                const custom = (names) => Object.entries(f).find(([k]) => names.some(n => k.toLowerCase().includes(n)))?.[1];
+                // A field the host named (its custom field's key), else Jira Cloud's usual one.
+                const field = (name) => [...(this.columns[name] ?? []), ...(JIRA_FIELDS[name] ?? [])].map(k => f[k]).find(v => v != null && v !== '');
+                return {
+                    key, id: String(id ?? ''), type: f.issuetype?.name ?? '', title: f.summary ?? '', description: f.description ?? '',
+                    parent: f.parent?.key ?? f.parent?.id ?? '', status: f.status?.name ?? '', priority: f.priority?.name ?? '',
+                    points: field('points') ?? custom(['storypoint', 'story_point']) ?? '',
+                    release: (f.fixVersions ?? [])[0]?.name ?? '', labels: (f.labels ?? []).join(' '),
+                    criteria: field('criteria') ?? custom(['acceptance']) ?? '', url: '',
+                };
+            });
+        }
+        if (tracker === 'azure') {
+            return (json.value ?? json.workItems ?? []).map(({ id, fields: f = {}, url }) => ({
+                key: String(id), id: String(id), type: f['System.WorkItemType'] ?? '', title: f['System.Title'] ?? '',
+                description: f['System.Description'] ?? '', parent: String(f['System.Parent'] ?? ''), status: f['System.State'] ?? '',
+                priority: String(f['Microsoft.VSTS.Common.Priority'] ?? ''),
+                points: f['Microsoft.VSTS.Scheduling.StoryPoints'] ?? f['Microsoft.VSTS.Scheduling.Effort'] ?? '',
+                release: f['System.IterationPath'] ?? '', labels: f['System.Tags'] ?? '',
+                criteria: f['Microsoft.VSTS.Common.AcceptanceCriteria'] ?? '', url: url ?? '',
+            }));
+        }
+        return (Array.isArray(json) ? json : []).map(i => ({
+            key: String(i.iid ?? i.id), id: String(i.iid ?? i.id), type: '', title: i.title ?? '', description: i.description ?? '',
+            parent: String(i.epic?.id ?? i.epic_iid ?? ''), parentName: i.epic?.title ?? '', status: i.state ?? '', priority: '',
+            points: i.weight ?? '', release: i.milestone?.title ?? '', labels: (i.labels ?? []).map(l => l.name ?? l).join(','),
+            criteria: '', url: i.web_url ?? '',
+        }));
+    }
+
+    /** Issues as epics, releases and stories. @private */
+    _model(tracker, def, issues) {
+        const is = (list, type) => list.some(t => t.toLowerCase() === String(type ?? '').trim().toLowerCase());
+        const keyOf = new Map();   // an issue's id or key → its key (Jira's CSV names a parent by its id)
+        for (const i of issues) for (const k of [i.key, i.id]) if (k) keyOf.set(String(k), String(i.key || i.id));
+        const source = (i, key) => ({ system: tracker, key, ...(i.url && { url: i.url }) });
+
+        const epics = new Map();
+        for (const i of issues) {
+            if (!is(def.epicTypes, i.type)) continue;
+            const key = String(i.key || i.id);
+            epics.set(key, { id: key, name: plainText(i.title), description: plainText(i.description), source: source(i, key) });
+        }
+        const releases = new Map();
+        const stories = [];
+        for (const i of issues) {
+            if (is(def.epicTypes, i.type) || is(def.skipTypes, i.type) || !String(i.title ?? '').trim()) continue;
+            const key = String(i.key || i.id);
+            const parent = i.parent ? keyOf.get(String(i.parent)) ?? String(i.parent) : '';
+            if (parent && !epics.has(parent) && i.parentName) epics.set(parent, { id: parent, name: plainText(i.parentName), description: '', source: { system: tracker, key: parent } });
+            const release = plainText(i.release);
+            if (release && !releases.has(release)) releases.set(release, { id: release, name: release.split(/[\\/]/).pop() });
+            const own = criteriaField(i.criteria);
+            const inText = own.length ? { criteria: [], rest: plainText(i.description) } : criteriaFrom(i.description);
+            const said = narrativeFrom(i.description);
+            const { as, want, soThat } = said.want ? said : narrativeFrom(i.title);
+            stories.push({
+                id: key, name: plainText(i.title), epic: parent, release,
+                as, want, soThat, description: said.want ? withoutNarrative(inText.rest) : inText.rest,
+                criteria: own.length ? own : inText.criteria,
+                status: plainText(i.status), priority: plainText(i.priority), points: i.points === '' ? null : i.points,
+                labels: String(i.labels ?? '').split(def.labelSeparator).map(l => l.trim()).filter(Boolean),
+                source: source(i, key), traces: [],
+            });
+        }
+        // A story whose parent is no epic here (a story's sub-item, an epic not exported) is under none.
+        for (const s of stories) if (s.epic && !epics.has(s.epic)) s.epic = '';
+        return { epics: [...epics.values()], releases: [...releases.values()], stories };
+    }
+}

package/src/charting/requirements/index.js

@@ -0,0 +1,12 @@
+export { RequirementsModel } from './RequirementsModel.js';
+export { RequirementsChecker } from './RequirementsChecker.js';
+export { EpicsCompared, ReleasesCompared, StoriesCompared } from './RequirementsCompared.js';
+export { RequirementsFileFormat } from './RequirementsFileFormat.js';
+export { TrackerExportFileFormat, StoryboardFileFormat } from './RequirementsImportFormats.js';
+export { TrackerExport, TRACKERS, criteriaFrom, narrativeFrom, withoutNarrative } from './TrackerExport.js';
+export { Storyboard } from './Storyboard.js';
+export { TrackerApi } from './TrackerApi.js';
+export { JiraApi } from './JiraApi.js';
+export { AzureDevOpsApi } from './AzureDevOpsApi.js';
+export { GitLabApi } from './GitLabApi.js';
+export { TRACKER_APIS, trackerApi, trackerConnectionFields } from './trackerApis.js';

package/src/charting/requirements/trackerApis.js

@@ -0,0 +1,21 @@
+import { JiraApi } from './JiraApi.js';
+import { AzureDevOpsApi } from './AzureDevOpsApi.js';
+import { GitLabApi } from './GitLabApi.js';
+
+/** Each tracker's API, by its key in TRACKERS. */
+export const TRACKER_APIS = Object.freeze({ jira: JiraApi, azure: AzureDevOpsApi, gitlab: GitLabApi });
+
+/**
+ * The API reader for a connection (`connection.tracker`: 'jira', 'azure',
+ * 'gitlab'); `options` as TrackerApi takes them.
+ */
+export function trackerApi(connection, options) {
+    const Api = TRACKER_APIS[connection?.tracker];
+    if (!Api) throw new Error(`No API reader for tracker "${connection?.tracker ?? ''}" (${Object.keys(TRACKER_APIS).join(', ')})`);
+    return new Api(connection, options);
+}
+
+/** What each tracker's connection asks for: `[{tracker, label, fields}]`, for a host's form. */
+export function trackerConnectionFields() {
+    return Object.entries(TRACKER_APIS).map(([tracker, Api]) => ({ tracker, label: new Api({}).label, fields: Api.fields }));
+}

package/src/index.js

@@ -166,6 +166,10 @@ import { buildTypeCategoryTree, buildPropertyTree } from './charting/modelTree/b
 import { DiagramTabs } from './charting/modelTree/DiagramTabs.js';
 import { DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole } from './datamodel.js';
 import { DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory } from './charting/datamodel/index.js';
+import { RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard, TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields } from './charting/requirements/index.js';
+import { EditableModel } from './charting/model/EditableModel.js';
+import { ModelEditCommand } from './charting/model/ModelEditCommand.js';
+import { Benchmark } from './charting/model/Benchmark.js';
 import { BianNotation, BianFunctionalPattern, BianActionTerm } from './bian.js';
 import {
     ARCHI_VISUAL_OBJECTS, ARCHI_VIEW_TYPES,
@@ -224,6 +228,9 @@ export {
   buildModelTreePanel, buildAnalysisPanel, buildAnalysisData, buildTypeCategoryTree, buildPropertyTree, DiagramTabs,
   DataModelNotation, DataModelLevel, AttributedLevel, ConceptualLevel, LogicalLevel, PhysicalLevel, NotationStyle, RelationshipKind, AssociationKind, GeneralizationKind, EntityRole, FactRole, DimensionRole,
   DataModel, DataModelPerspective, DataModelContext, LevelSchema, LevelMapping, ServiceDomain, DataModelFileFormat, ServiceLandscape, BianLandscapeReader, BianSemanticApiReader, DataType, EnumerationType, StructuredType, NamingStandard, NameStyle, ClassificationScheme, ClassificationLens, SqlDdl, SqlDdlFileFormat, ModelScorecard, ScorecardCategory, MeasuredCategory,
+  RequirementsModel, RequirementsChecker, RequirementsFileFormat, TrackerExportFileFormat, StoryboardFileFormat, TrackerExport, TRACKERS, Storyboard,
+  TrackerApi, JiraApi, AzureDevOpsApi, GitLabApi, TRACKER_APIS, trackerApi, trackerConnectionFields,
+  EditableModel, ModelEditCommand, Benchmark,
   BianNotation, BianFunctionalPattern, BianActionTerm,
   exportElementsCSV, exportRelationshipsCSV, exportModelCSV,
   importElementsCSV, importRelationshipsCSV, importModelCSV,