@peter.prib/renderengine 0.2.6 → 0.2.10

package/src/charting/datamodel/scorecard/ScorecardCategory.js

@@ -0,0 +1,46 @@
+/** A ratio as a whole score out of 100 (none: null). */
+export const percent = (part, whole) => (whole ? Math.round((100 * part) / whole) : null);
+
+/**
+ * ScorecardCategory — one of the Data Model Scorecard's ten categories (Steve
+ * Hoberman, *Data Model Scorecard*, 2015): its `key`, `label` and the question
+ * it asks. This base is one a reviewer scores (`measure` says nothing); a
+ * subclass measures it from the model, a score out of 100 and notes on why,
+ * or null when the model cannot say. A reviewer's score overrides either.
+ */
+export class ScorecardCategory {
+    /**
+     * @param {string} key - 'correctness'
+     * @param {string} label - 'Correctness'
+     * @param {string} question - What it asks of the model
+     */
+    constructor(key, label, question) {
+        Object.assign(this, { key, label, question });
+    }
+
+    /** Whether the model says how it scores (else a reviewer must). */
+    get measured() {
+        return false;
+    }
+
+    /**
+     * Its score from the model: `{ score: 0..100 | null, notes: string[] }`.
+     * @param {DataModel} model
+     * @param {Array<Object>} findings - The model check's findings (DataModelChecker#run)
+     */
+    measure(model, findings) {
+        return { score: null, notes: ['for a reviewer to score'] };
+    }
+}
+
+/** A category measured from the model: a subclass says how. */
+export class MeasuredCategory extends ScorecardCategory {
+    get measured() {
+        return true;
+    }
+
+    /** @abstract */
+    measure(model, findings) {
+        throw new Error(`${this.constructor.name} must implement measure()`);
+    }
+}

package/src/charting/datamodel/scorecard/StandardsCategory.js

@@ -0,0 +1,29 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+
+/**
+ * Standards: are names as the model's naming standard says? Measured as the
+ * share of entity and attribute names that keep it; without a standard the
+ * model cannot say (a reviewer may).
+ */
+export class StandardsCategory extends MeasuredCategory {
+    constructor() {
+        super('standards', 'Standards', 'Are names written as the naming standard says?');
+    }
+
+    measure(model) {
+        const standard = model.namingStandard;
+        if (!standard) return { score: null, notes: ['no naming standard: set one to measure this'] };
+        let names = 0, kept = 0;
+        for (const level of model.constructor.LEVELS) {
+            for (const e of model.level(level).entities) {
+                names++;
+                if (!standard.check(level, 'entities', e.name).length) kept++;
+                for (const a of e.attributes ?? []) {
+                    names++;
+                    if (!standard.check(level, 'attributes', a.name).length) kept++;
+                }
+            }
+        }
+        return names ? { score: percent(kept, names), notes: [`${kept} of ${names} names keep the naming standard`] } : { score: null, notes: ['no names'] };
+    }
+}

package/src/charting/datamodel/scorecard/StructureCategory.js

@@ -0,0 +1,32 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+
+/** The model check's findings that are about structure. */
+const STRUCTURAL = new Set([
+    'no-primary-key', 'reference-missing', 'foreign-key-without-relationship', 'foreign-key-unrelated',
+    'many-to-many', 'repeating-group', 'generalization-cycle',
+]);
+
+/**
+ * Structure: is the model sound? Measured as the share of logical entities and
+ * tables the model check finds nothing structural on (keys, foreign keys,
+ * many-to-many, repeating groups, generalizations going round).
+ */
+export class StructureCategory extends MeasuredCategory {
+    static STRUCTURAL = STRUCTURAL;
+
+    constructor() {
+        super('structure', 'Structure', 'Is it sound: keys, foreign keys, no repeating groups or unresolved many-to-many?');
+    }
+
+    measure(model, findings) {
+        const entities = ['logical', 'physical'].flatMap(level => model.level(level).entities.map(e => `${level}:${e.id}`));
+        if (!entities.length) return { score: null, notes: ['no logical entities or tables'] };
+        const structural = findings.filter(f => STRUCTURAL.has(f.code));
+        const touched = new Set(structural.flatMap(f => (f.ids ?? []).map(id => `${f.level}:${id}`)).filter(k => entities.includes(k)));
+        const counts = structural.reduce((m, f) => ((m[f.code] = (m[f.code] ?? 0) + 1), m), {});
+        return {
+            score: percent(entities.length - touched.size, entities.length),
+            notes: [`${entities.length - touched.size} of ${entities.length} logical entities and tables sound`, ...Object.entries(counts).map(([code, n]) => `${n} ${code}`)],
+        };
+    }
+}

package/src/charting/datamodel/scorecard/index.js

@@ -0,0 +1,8 @@
+export { ScorecardCategory, MeasuredCategory } from './ScorecardCategory.js';
+export { CompletenessCategory } from './CompletenessCategory.js';
+export { StructureCategory } from './StructureCategory.js';
+export { StandardsCategory } from './StandardsCategory.js';
+export { DefinitionsCategory } from './DefinitionsCategory.js';
+export { ConsistencyCategory } from './ConsistencyCategory.js';
+export { ReadabilityCategory } from './ReadabilityCategory.js';
+export { ModelScorecard } from './ModelScorecard.js';

package/src/charting/diagramModel/MergeModelCommand.js

@@ -1,37 +1,43 @@
-import { Command } from '../CommandHistory.js';
-
-/**
- * MergeModelCommand — things from another model brought into this one
- * (ModelComparison#mergeCommand): each step a ComparedKind's `bring`, in the
- * order given (what is needed first). One undo step; undo takes each back,
- * last first.
- */
-export class MergeModelCommand extends Command {
-    /** A merge is no edit on one view: undoing it shows no other. */
-    viewId = null;
-
-    /**
-     * @param {ViewSetModel} model - Merged into
-     * @param {ViewSetModel} from - Merged from
-     * @param {Array<{kind: ComparedKind, item: Object}>} steps
-     * @param {string} [label]
-     */
-    constructor(model, from, steps, label = `Merge ${steps.length} item${steps.length === 1 ? '' : 's'} from "${from.name || 'another model'}"`) {
-        super(label);
-        this.model = model;
-        this.from = from;
-        this.steps = steps;
-        this._undos = [];
-    }
-
-    execute() {
-        this._undos = this.steps.map(({ kind, item }) => kind.bring(this.model, item, this.from));
-        this.model._notify();
-    }
-
-    undo() {
-        for (const undo of [...this._undos].reverse()) undo();
-        this._undos = [];
-        this.model._notify();
-    }
-}
+import { Command } from '../CommandHistory.js';
+
+/**
+ * MergeModelCommand — things from another model brought into this one
+ * (ModelComparison#mergeCommand): each step a ComparedKind's `bring`, in the
+ * order given (what is needed first). One undo step; undo takes each back,
+ * last first.
+ */
+export class MergeModelCommand extends Command {
+    /** A merge is no edit on one view: undoing it shows no other. */
+    viewId = null;
+
+    /**
+     * @param {ViewSetModel} model - Merged into
+     * @param {ViewSetModel} from - Merged from
+     * @param {Array<{kind: ComparedKind, item: Object}>} steps
+     * @param {string} [label]
+     */
+    constructor(model, from, steps, label = `Merge ${steps.length} item${steps.length === 1 ? '' : 's'} from "${from.name || 'another model'}"`) {
+        super(label);
+        this.model = model;
+        this.from = from;
+        this.steps = steps;
+        this._undos = [];
+    }
+
+    execute() {
+        this._undos = this.steps.map(({ kind, item }) => kind.bring(this.model, item, this.from));
+        this._changed();
+    }
+
+    undo() {
+        for (const undo of [...this._undos].reverse()) undo();
+        this._undos = [];
+        this._changed();
+    }
+
+    /** The model changed: a view set tells its listeners; a model without views (a DataModel) says it was edited. @private */
+    _changed() {
+        this.model._notify?.();
+        this.model.edited?.();
+    }
+}

package/src/charting/diagramModel/OpenViewList.js

@@ -0,0 +1,75 @@
+/**
+ * OpenViewList — the views of a model that have a tab, in tab order, as a
+ * browser keeps its tabs: closing a tab leaves the view in the model, and a
+ * view is opened by going to it (from the tree, a search, a new view). It
+ * starts with the view in front only, so a model opened or imported with many
+ * views does not fill the tab strip.
+ *
+ * It follows the model: `sync()` drops views since deleted and opens the one in
+ * front, unless paused (`while`: a report passing through every view opens none).
+ */
+export class OpenViewList {
+    /**
+     * @param {ViewSetModel} model
+     * @param {Iterable<string>} [ids] - Those open to start with (default: the view in front)
+     */
+    constructor(model, ids = null) {
+        this.model = model;
+        this.ids = ids ? [...ids] : (model.currentViewId ? [model.currentViewId] : []);
+        this._paused = 0;
+        this.sync();
+    }
+
+    /** Follow the model: deleted views gone, the one in front open (last). Returns the open views. */
+    sync() {
+        this.ids = this.ids.filter(id => this.model.getView(id));
+        const current = this.model.currentViewId;
+        if (!this._paused && current && !this.ids.includes(current)) this.ids.push(current);
+        return this.views();
+    }
+
+    /** The open views, in tab order. */
+    views() {
+        return this.ids.map(id => this.model.getView(id)).filter(Boolean);
+    }
+
+    isOpen(id) {
+        return this.ids.includes(id);
+    }
+
+    /** Open a view's tab (if not open) and bring it to the front. */
+    open(id) {
+        if (!this.model.getView(id)) return false;
+        if (!this.ids.includes(id)) this.ids.push(id);
+        if (this.model.currentViewId !== id) this.model.switchTo(id);
+        return true;
+    }
+
+    /** Whether a tab may be closed: one always stays open. */
+    canClose(id) {
+        return this.ids.includes(id) && this.ids.length > 1;
+    }
+
+    /**
+     * Close a view's tab; the view stays in the model. Closing the tab in front
+     * brings its neighbour (the next, else the one before) to the front.
+     * @returns {boolean} whether it closed
+     */
+    close(id) {
+        if (!this.canClose(id)) return false;
+        const index = this.ids.indexOf(id);
+        this.ids.splice(index, 1);
+        if (this.model.currentViewId === id) this.model.switchTo(this.ids[Math.min(index, this.ids.length - 1)]);
+        return true;
+    }
+
+    /** Run `fn` with the list paused: going through views (a report's pictures) opens none. */
+    while(fn) {
+        this._paused++;
+        try { return fn(); } finally { this._paused--; }
+    }
+
+    toJSON() {
+        return [...this.ids];
+    }
+}

package/src/charting/diagramModel/ViewSetChecker.js

@@ -1,34 +1,22 @@
-/**
- * ViewSetChecker — checks over any ViewSetModel (a template editor's
- * DiagramModel, an ArchimateModel): what is wrong or worth a look across its
- * views. A notation adds its own checks in a subclass (ArchimateModelChecker).
- * DOM-free and advisory.
- *
- * Each finding: `{ code, severity: 'warning'|'info', message, kind, ids }`;
- * `kind` says what the ids name ('view' here; a subclass adds its own).
- * Each check is a method listed by `checks()`, so a subclass can add, drop or
- * reorder them.
- */
-export class ViewSetChecker {
-    /** @param {ViewSetModel} model */
-    constructor(model) {
-        this.model = model;
-    }
-
-    /** The checks to run, in the order their findings are listed. */
-    checks() {
-        return [this.emptyViews];
-    }
-
-    /** Every finding. @returns {Array<Object>} */
-    run() {
-        return this.checks().flatMap(check => check.call(this));
-    }
-
-    /** Views with nothing on them (a template is left out: an empty one is still a start). */
-    emptyViews() {
-        return this.model.views()
-            .filter(v => !v.template && v.isEmpty())
-            .map(v => ({ code: 'empty-view', severity: 'info', kind: 'view', ids: [v.id], message: `View "${v.title || v.name || v.id}" is empty` }));
-    }
-}
+import { ModelChecker } from '../ModelChecker.js';
+
+/**
+ * ViewSetChecker — checks over any ViewSetModel (a template editor's
+ * DiagramModel, an ArchimateModel): what is wrong or worth a look across its
+ * views (a ModelChecker: findings, checks listed by `checks()`). A notation
+ * adds its own checks in a subclass (ArchimateModelChecker). `kind` in a
+ * finding is 'view' here; a subclass adds its own.
+ */
+export class ViewSetChecker extends ModelChecker {
+    /** The checks to run, in the order their findings are listed. */
+    checks() {
+        return [this.emptyViews];
+    }
+
+    /** Views with nothing on them (a template is left out: an empty one is still a start). */
+    emptyViews() {
+        return this.model.views()
+            .filter(v => !v.template && v.isEmpty())
+            .map(v => ({ code: 'empty-view', severity: 'info', kind: 'view', ids: [v.id], message: `View "${v.title || v.name || v.id}" is empty` }));
+    }
+}

package/src/charting/diagrams/DataModelDiagram.js

@@ -94,8 +94,8 @@ export class DataModelDiagram extends Diagram {
      * note to what it is about, or (the `links` option) a mapping between levels.
      * @param {{id?: string, source: string, target: string, label?: string}} link
      */
-    static buildLink({ id, source, target, label }) {
-        return { ...(id && { id }), source, target, ...(label && { label }), lineStyle: 'dotted', arrowhead: 'none', arrowheadStart: 'none' };
+    static buildLink({ id, source, target, label, color }) {
+        return { ...(id && { id }), source, target, ...(label && { label }), ...(color && { color }), lineStyle: 'dotted', arrowhead: 'none', arrowheadStart: 'none' };
     }
 
     static typeGroup(type) {
@@ -146,15 +146,8 @@ export class DataModelDiagram extends Diagram {
         };
     }
 
+    /** A relationship's edge in a notation, as its kind draws it (DataModelNotation.relationshipKind). */
     static buildEdge(relationship, notation) {
-        return {
-            ...relationship,
-            label: relationship.name,
-            lineStyle: relationship.identifying === false ? 'dashed' : 'solid',
-            arrowheadStart: notation.cardinalityArrowhead(relationship.sourceCardinality) || 'none',
-            arrowhead: notation.cardinalityArrowhead(relationship.targetCardinality) || 'none',
-            sourceLabel: notation.cardinalityLabel(relationship.sourceCardinality),
-            targetLabel: notation.cardinalityLabel(relationship.targetCardinality),
-        };
+        return DataModelNotation.relationshipKind(relationship).edge(relationship, notation);
     }
 }

package/src/charting/diagrams/DataModelRelationshipStrategy.js

@@ -1,3 +1,4 @@
+import { DataModelNotation } from '../../datamodel.js';
 /**
  * Strategy interface for turning data-model relationships into diagram nodes
  * and edges. Crow's Foot and UML keep relationships as direct edges; Chen
@@ -42,7 +43,7 @@ export class RelationshipAsNodeStrategy extends DataModelRelationshipStrategy {
     /**
      * Where a diamond between two places goes: their midpoint when it is clear
      * of everything in `occupied`, else the nearest clear spot stepping out
-     * across the line, one side then the other; the midpoint when none is clear.
+     * across the line, one side then the other; when none is clear, the least covered.
      * @returns {{x: number, y: number}}
      */
     static spotFor(from, to, occupied) {
@@ -50,22 +51,35 @@ export class RelationshipAsNodeStrategy extends DataModelRelationshipStrategy {
         const mid = { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
         const length = Math.hypot(to.x - from.x, to.y - from.y) || 1;
         const across = { x: -(to.y - from.y) / length, y: (to.x - from.x) / length };
-        const clear = ({ x, y }) => occupied.every(o => x + width / 2 <= o.x0 || o.x1 <= x - width / 2 || y + height / 2 <= o.y0 || o.y1 <= y - height / 2);
+        // How much of a diamond at a spot is covered by what is there (0: clear).
+        const covered = ({ x, y }) => occupied.reduce((sum, o) => {
+            const w = Math.min(x + width / 2, o.x1) - Math.max(x - width / 2, o.x0);
+            const h = Math.min(y + height / 2, o.y1) - Math.max(y - height / 2, o.y0);
+            return sum + (w > 0 && h > 0 ? w * h : 0);
+        }, 0);
+        let best = mid, least = Infinity;
         for (let k = 0; k <= RelationshipAsNodeStrategy.TRIES; k++) {
             for (const side of k ? [1, -1] : [0]) {
                 const at = { x: mid.x + across.x * side * k * RelationshipAsNodeStrategy.STEP, y: mid.y + across.y * side * k * RelationshipAsNodeStrategy.STEP };
-                if (clear(at)) return at;
+                const c = covered(at);
+                if (c === 0) return at;
+                if (c < least) { best = at; least = c; }
             }
         }
-        return mid;
+        return best;   // none clear: the least covered
     }
 
-    apply(relationships, { notation, entity = () => undefined, occupied = [] }) {
+    apply(relationships, { notation, buildEdge, entity = () => undefined, occupied = [] }) {
         const nodes = [];
         const edges = [];
         const taken = [...occupied];
         const { width, height } = RelationshipAsNodeStrategy.DIAMOND;
         relationships.forEach((relationship, i) => {
+            // A kind drawn as a line in this notation (a generalization) is one.
+            if (!DataModelNotation.relationshipKind(relationship).drawnAsNode(notation)) {
+                edges.push(buildEdge(relationship, notation));
+                return;
+            }
             const relId = relationship.id || `${relationship.source}__${relationship.target}__rel${i}`;
             const lineStyle = relationship.identifying === false ? 'dashed' : 'solid';
             const [from, to] = [entity(relationship.source), entity(relationship.target)];