@peter.prib/renderengine 0.2.7 → 0.2.11

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

@@ -0,0 +1,113 @@
+import { ScorecardCategory } from './ScorecardCategory.js';
+import { CompletenessCategory } from './CompletenessCategory.js';
+import { StructureCategory } from './StructureCategory.js';
+import { StandardsCategory } from './StandardsCategory.js';
+import { DefinitionsCategory } from './DefinitionsCategory.js';
+import { ConsistencyCategory } from './ConsistencyCategory.js';
+import { ReadabilityCategory } from './ReadabilityCategory.js';
+
+/**
+ * The ten categories in the Scorecard's order: those the model measures, and
+ * those a reviewer scores (Correctness, Scheme, Abstraction, Data).
+ */
+const CATEGORIES = Object.freeze([
+    new ScorecardCategory('correctness', 'Correctness', 'Does the model capture the requirements?'),
+    new CompletenessCategory(),
+    new ScorecardCategory('scheme', 'Scheme', 'Is the scheme (relational, dimensional...) the right one for what it is for?'),
+    new StructureCategory(),
+    new ScorecardCategory('abstraction', 'Abstraction', 'Is it as general as it should be, and no more?'),
+    new StandardsCategory(),
+    new ReadabilityCategory(),
+    new DefinitionsCategory(),
+    new ConsistencyCategory(),
+    new ScorecardCategory('data', 'Data', 'Does the data in the database match what the model says of it?'),
+]);
+
+/**
+ * ModelScorecard — a data model scored as DMBOK2 has a model reviewed, on the
+ * Data Model Scorecard's ten categories (Steve Hoberman, 2015). Six the model
+ * measures (ScorecardCategory subclasses); four a reviewer scores; a reviewer's
+ * score, kept in the model (`model.scorecard.reviews[key]: { score, note }`),
+ * overrides a measured one too. The total is the weighted average of the
+ * categories with a score, out of 100. Weights are the model's own
+ * (`model.scorecard.weights`); by default equal, 10 each: the book gives its
+ * own weighting, and an organisation sets the one it reviews by.
+ */
+export class ModelScorecard {
+    static CATEGORIES = CATEGORIES;
+    static DEFAULT_WEIGHT = 10;
+
+    /** @param {DataModel} model */
+    constructor(model) {
+        this.model = model;
+    }
+
+    /** What the model keeps of the scorecard: `{ weights, reviews }`. */
+    get kept() {
+        return this.model.scorecard ?? {};
+    }
+
+    /** A category's weight: the model's, else the default. */
+    weight(key) {
+        const w = Number(this.kept.weights?.[key]);
+        return Number.isFinite(w) && w >= 0 ? w : ModelScorecard.DEFAULT_WEIGHT;
+    }
+
+    /**
+     * Each category: `{ category, weight, measured: {score, notes}, review: {score, note}|null,
+     * score (the review's, else the measured, or null), source: 'reviewed'|'measured'|null }`.
+     */
+    results() {
+        const findings = this.model.checker().run();
+        return CATEGORIES.map(category => {
+            const measured = category.measure(this.model, findings);
+            const kept = this.kept.reviews?.[category.key];
+            const review = Number.isFinite(Number(kept?.score)) && kept?.score !== '' && kept?.score != null ? { score: Number(kept.score), note: kept.note ?? '' } : null;
+            const score = review ? review.score : measured.score;
+            return { category, weight: this.weight(category.key), measured, review, score, source: review ? 'reviewed' : (measured.score == null ? null : 'measured') };
+        });
+    }
+
+    /** The weighted average of the categories with a score (null: none has), and how much of the weight that is. */
+    total(results = this.results()) {
+        const scored = results.filter(r => r.score != null && r.weight > 0);
+        const weight = scored.reduce((s, r) => s + r.weight, 0);
+        const all = results.reduce((s, r) => s + r.weight, 0);
+        return {
+            score: weight ? Math.round(scored.reduce((s, r) => s + r.score * r.weight, 0) / weight) : null,
+            coverage: all ? Math.round((100 * weight) / all) : 0,
+        };
+    }
+
+    /**
+     * Its dialog's fields: a heading per category (its question as the hint),
+     * what the model measured (shown), the reviewer's score and note, its weight.
+     * The score and weight are text, not number, fields: a number field reads
+     * empty as 0, and an empty score means "not scored", not nought.
+     */
+    fields(results = this.results()) {
+        return results.flatMap(({ category, measured, review, weight }) => [
+            { type: 'heading', label: category.label },
+            {
+                key: `${category.key}.measured`, label: 'Measured', type: 'text', readOnly: true,
+                value: measured.score == null ? '—' : `${measured.score}`, hint: [category.question, ...measured.notes].join(' · '),
+            },
+            { key: `${category.key}.score`, label: 'Reviewer\'s score', type: 'text', value: review?.score ?? '', placeholder: category.measured ? 'the measured one' : '0–100' },
+            { key: `${category.key}.note`, label: 'Note', type: 'text', value: review?.note ?? '' },
+            { key: `${category.key}.weight`, label: 'Weight', type: 'text', value: weight },
+        ]);
+    }
+
+    /** What the model keeps from those fields: weights other than the default, and the reviews given. */
+    static specFrom(values) {
+        const weights = {}, reviews = {};
+        for (const { key } of CATEGORIES) {
+            const weight = values[`${key}.weight`];
+            if (String(weight ?? '').trim() !== '' && Number(weight) !== ModelScorecard.DEFAULT_WEIGHT && Number.isFinite(Number(weight))) weights[key] = Number(weight);
+            const score = values[`${key}.score`];
+            const note = String(values[`${key}.note`] ?? '').trim();
+            if (String(score ?? '').trim() !== '' && Number.isFinite(Number(score))) reviews[key] = { score: Math.max(0, Math.min(100, Number(score))), ...(note && { note }) };
+        }
+        return { ...(Object.keys(weights).length && { weights }), ...(Object.keys(reviews).length && { reviews }) };
+    }
+}

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

@@ -0,0 +1,37 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+import { DataModelDiagram } from '../../diagrams/DataModelDiagram.js';
+import { DataModelNotation } from '../../../datamodel.js';
+
+/**
+ * Readability: can it be read as drawn? Measured as the average of the share
+ * of placed boxes, at each level, clear of every other box, and the share of
+ * associations with a name (a generalization needs none).
+ */
+export class ReadabilityCategory extends MeasuredCategory {
+    constructor() {
+        super('readability', 'Readability', 'Can it be read as drawn: boxes clear of each other, relationships named?');
+    }
+
+    measure(model) {
+        let placed = 0, clear = 0, associations = 0, named = 0;
+        for (const level of model.constructor.LEVELS) {
+            const notation = DataModelNotation.notation('crowsfoot');
+            const boxes = model.level(level).entities
+                .map(e => DataModelDiagram.boxOf(DataModelDiagram.buildNode({ ...e, [level]: { attributes: e.attributes ?? [] } }, { level, notation })))
+                .filter(Boolean);
+            placed += boxes.length;
+            clear += boxes.filter((a, i) => !boxes.some((b, j) => j !== i && a.x0 < b.x1 && b.x0 < a.x1 && a.y0 < b.y1 && b.y0 < a.y1)).length;
+            for (const r of model.level(level).relationships) {
+                if (!DataModelNotation.relationshipKind(r).hasCardinality) continue;
+                associations++;
+                if (String(r.name ?? '').trim()) named++;
+            }
+        }
+        const shares = [['boxes clear of the others', clear, placed], ['relationships named', named, associations]].filter(([, , whole]) => whole);
+        if (!shares.length) return { score: null, notes: ['nothing drawn yet'] };
+        return {
+            score: Math.round(shares.reduce((sum, [, part, whole]) => sum + percent(part, whole), 0) / shares.length),
+            notes: shares.map(([what, part, whole]) => `${part} of ${whole} ${what}`),
+        };
+    }
+}

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/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
@@ -68,12 +69,17 @@ export class RelationshipAsNodeStrategy extends DataModelRelationshipStrategy {
         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)];

package/src/charting/diagrams/NodeGeometry.js

@@ -55,7 +55,11 @@ export class NodeGeometry {
         return posEntry.y - size.h / 2 + headerH + idx * rowH + rowH / 2;
     }
 
-    /** Draws a table-card node's header + one row per column into wrapper `g`. */
+    /**
+     * Draws a table-card node's header + one row per column into wrapper `g`;
+     * the node's own `color` tints the card's body (a lens, a marked control
+     * record), the header staying as it is so its name reads.
+     */
     static buildTableNodeContent(renderer, g, node) {
         const { headerH, rowH } = NodeGeometry.TABLE_NODE;
         const { w, h } = NodeGeometry.tableNodeSize(node);
@@ -65,7 +69,7 @@ export class NodeGeometry {
         const borderWidth = node.selected ? 2 : 1;
 
         const TYPE_COLORS = { NUMBER: '#74b9ff', TEXT: '#a29bfe', TIMESTAMP: '#55efc4', BOOLEAN: '#ffeaa7', JSON: '#fd79a8', UNKNOWN: '#dfe6e9' };
-        g.appendChild(renderer.rect(x0, y0, w, h, '#ffffff', { color: borderColor, width: borderWidth }));
+        g.appendChild(renderer.rect(x0, y0, w, h, node.color || '#ffffff', { color: borderColor, width: borderWidth }));
         g.appendChild(renderer.rect(x0, y0, w, headerH, '#1976d2', null));
         g.appendChild(renderer.text(LabelHelper.resolveNodeLabel(node), x0 + 8, y0 + headerH / 2, {
             fill: '#fff', textAnchor: 'start', verticalAlign: 'middle', fontSize: '11px', fontWeight: 'bold', 'pointer-events': 'none',

package/src/charting/toolbar/ToolbarSelect.js

@@ -35,4 +35,10 @@ export class ToolbarSelect extends ToolbarItem {
             ],
         };
     }
+
+    /** Show the value as it is now (it may have been chosen other than through this select). */
+    refresh(node) {
+        const select = [...(node?.children ?? [])].find(c => c.tagName === 'SELECT');
+        if (select) select.value = this.value();
+    }
 }