@peter.prib/renderengine 0.2.6 → 0.2.10

package/src/charting/datamodel/StructuredType.js

@@ -0,0 +1,63 @@
+import { DataType } from './DataType.js';
+
+/**
+ * StructuredType — a data type made of named fields, each of a type (a plain
+ * type's name or another data type's): BIAN's Amount, Datetime, Identifier.
+ * `fields` as `[{ name, type?, description?, iso20022? }]`. Drawn as a box with
+ * a row per field, joined to the data types its fields are.
+ */
+export class StructuredType extends DataType {
+    static kind = 'structure';
+    static kindLabel = 'Structure';
+
+    /** @param {Object} spec - As DataType, plus `fields: [{ name, type?, description?, iso20022? }]` */
+    constructor({ fields = [], ...spec } = {}) {
+        super(spec);
+        this.fields = fields.map(f => ({
+            name: String(f.name),
+            ...(f.type && { type: String(f.type) }),
+            ...(f.description && { description: f.description }),
+            ...(f.iso20022 && { iso20022: f.iso20022 }),
+        }));
+    }
+
+    summary() {
+        return `${this.name}: ${this.fields.map(f => (f.type ? `${f.name} (${f.type})` : f.name)).join(', ')}`;
+    }
+
+    rows() {
+        return this.fields.map(f => ({ name: f.name, ...(f.type && { type: f.type }) }));
+    }
+
+    uses() {
+        return [...super.uses(), ...this.fields.map(f => f.type).filter(Boolean)];
+    }
+
+    toJSON() {
+        return { ...super.toJSON(), fields: this.fields.map(f => ({ ...f })) };
+    }
+
+    /** A plain type's fields, then its fields a line each: `name | type`. */
+    static fields(model, type = null) {
+        return [
+            ...DataType.fields(model, type),
+            {
+                key: 'fields', label: 'Fields', type: 'textarea', rows: 6,
+                value: (type?.fields ?? []).map(f => (f.type ? `${f.name} | ${f.type}` : f.name)).join('\n'),
+                hint: 'One a line: name | type (a plain type, or a data type by name)',
+            },
+        ];
+    }
+
+    static specFrom(values, model, type = null) {
+        return {
+            ...super.specFrom(values),
+            fields: DataType.lines(values.fields).map(([name, fieldType]) => {
+                const kept = type?.fields.find(f => f.name === name);
+                return { ...kept, name, ...(fieldType ? { type: fieldType } : { type: undefined }) };
+            }).map(f => JSON.parse(JSON.stringify(f))),
+        };
+    }
+}
+
+DataType.register(StructuredType);

package/src/charting/datamodel/index.js

@@ -1,5 +1,21 @@
-export { DataModel } from './DataModel.js';
-export { DataModelPerspective } from './DataModelPerspective.js';
-export { DataModelContext } from './DataModelContext.js';
-export { LevelSchema } from './LevelSchema.js';
-export { LevelMapping } from './LevelMapping.js';
+export { DataModel } from './DataModel.js';
+export { DataModelPerspective } from './DataModelPerspective.js';
+export { DataModelContext } from './DataModelContext.js';
+export { ServiceDomain } from './ServiceDomain.js';
+export { DataModelChecker } from './DataModelChecker.js';
+export { ModelScorecard, ScorecardCategory, MeasuredCategory } from './scorecard/index.js';
+export { ClassificationScheme } from './ClassificationScheme.js';
+export { ClassificationLens } from './ClassificationLens.js';
+export { NamingStandard, NameStyle } from './naming/index.js';
+export { DataType } from './DataType.js';
+export { EnumerationType } from './EnumerationType.js';
+export { StructuredType } from './StructuredType.js';
+export { ServiceLandscape } from './ServiceLandscape.js';
+export { BianLandscapeReader } from './BianLandscapeReader.js';
+export { BianSemanticApiReader } from './BianSemanticApiReader.js';
+export { LevelSchema } from './LevelSchema.js';
+export { LevelMapping } from './LevelMapping.js';
+export { DataModelFileFormat } from './DataModelFileFormat.js';
+export { SqlDdl } from './SqlDdl.js';
+export { SqlDdlFileFormat } from './SqlDdlFileFormat.js';
+export { LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared } from './DataModelCompared.js';

package/src/charting/datamodel/naming/CamelCaseStyle.js

@@ -0,0 +1,13 @@
+import { NameStyle } from './NameStyle.js';
+
+/** camelCase: words run together, each but the first capitalised ('partyId'). */
+export class CamelCaseStyle extends NameStyle {
+    static key = 'camel';
+    static label = 'camelCase';
+
+    format(words) {
+        return words.map((w, i) => (i === 0 ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())).join('');
+    }
+}
+
+NameStyle.register(CamelCaseStyle);

package/src/charting/datamodel/naming/LowerWordsStyle.js

@@ -0,0 +1,13 @@
+import { NameStyle } from './NameStyle.js';
+
+/** lower case words apart ('party id'). */
+export class LowerWordsStyle extends NameStyle {
+    static key = 'lower';
+    static label = 'lower case words';
+
+    format(words) {
+        return words.map(w => w.toLowerCase()).join(' ');
+    }
+}
+
+NameStyle.register(LowerWordsStyle);

package/src/charting/datamodel/naming/NameStyle.js

@@ -0,0 +1,57 @@
+/**
+ * NameStyle — one way names are written (Title Case, snake_case, ...): whether
+ * a name is written so (`matches`), and how it would be (`suggest`). A name is
+ * read as its words whatever its style (spaces, underscores, hyphens, camel
+ * humps), so any name can be suggested in any style. A subclass per style
+ * (`format(words)`, and `matches` where it allows more than its own format);
+ * `NameStyle.register` makes one known by its `key`.
+ */
+export class NameStyle {
+    /** What a spec calls it ('title'), and what a menu does ('Title Case'). */
+    static key = '';
+    static label = '';
+
+    /** Name styles by key. */
+    static STYLES = new Map();
+
+    static register(StyleClass) {
+        NameStyle.STYLES.set(StyleClass.key, new StyleClass());
+    }
+
+    /** A style by key, or null (none: any name will do). */
+    static get(key) {
+        return NameStyle.STYLES.get(key) ?? null;
+    }
+
+    /** Every style, in the order registered. */
+    static all() {
+        return [...NameStyle.STYLES.values()];
+    }
+
+    /** A name's words: split at spaces, underscores, hyphens and camel humps ('partyID' is party, ID). */
+    static words(name) {
+        return String(name ?? '')
+            .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+            .split(/[\s_-]+/)
+            .filter(Boolean);
+    }
+
+    get key() { return this.constructor.key; }
+    get label() { return this.constructor.label; }
+
+    /** Words written in this style. @abstract */
+    format(words) {
+        throw new Error(`${this.constructor.name} must implement format()`);
+    }
+
+    /** Whether a name is written in this style. */
+    matches(name) {
+        return this.suggest(name) === name;
+    }
+
+    /** The name written in this style. */
+    suggest(name) {
+        return this.format(NameStyle.words(name));
+    }
+}

package/src/charting/datamodel/naming/NamingStandard.js

@@ -0,0 +1,132 @@
+import { NameStyle } from './NameStyle.js';
+import './TitleCaseStyle.js';
+import './LowerWordsStyle.js';
+import './SnakeCaseStyle.js';
+import './UpperSnakeStyle.js';
+import './CamelCaseStyle.js';
+import './PascalCaseStyle.js';
+
+/** What a standard says of names, by level, then of entities and of attributes. */
+const KINDS = Object.freeze({
+    conceptual: ['entities'],
+    logical: ['entities', 'attributes'],
+    physical: ['entities', 'attributes'],
+});
+
+/**
+ * NamingStandard — how a model's names are written, level by level (DMBOK2's
+ * naming standards): for its entities, and its attributes, a rule each —
+ * `style` (a NameStyle key; none: any), `classWords` (the words an attribute
+ * name must end with: Amount, Date, Code, Identifier...), `maxLength`,
+ * `abbreviations` (`{ word: abbreviation }`, as a physical name must use them).
+ * A model keeps its own (`model.namingStandard`, null: no standard), so the
+ * standard is the organisation's to choose; CONVENTIONAL is one to start from.
+ */
+export class NamingStandard {
+    static KINDS = KINDS;
+
+    /** A common standard: concepts and logical entities in Title Case, logical attributes in words ending in a class word, tables and columns in snake_case, abbreviated. */
+    static CONVENTIONAL = Object.freeze({
+        conceptual: { entities: { style: 'title' } },
+        logical: {
+            entities: { style: 'title' },
+            attributes: { style: 'lower', classWords: ['identifier', 'id', 'name', 'code', 'date', 'time', 'amount', 'number', 'count', 'rate', 'percentage', 'indicator', 'flag', 'text', 'description', 'type', 'status', 'quantity', 'value'] },
+        },
+        physical: {
+            entities: { style: 'snake', maxLength: 30 },
+            attributes: { style: 'snake', maxLength: 30, abbreviations: { number: 'num', identifier: 'id', amount: 'amt', quantity: 'qty', description: 'desc' } },
+        },
+    });
+
+    /** @param {Object} [spec] - `{ level: { entities?: rule, attributes?: rule } }` */
+    constructor(spec = {}) {
+        this.rules = Object.fromEntries(Object.entries(KINDS).map(([level, kinds]) => [level, Object.fromEntries(kinds.map(kind => {
+            const rule = spec?.[level]?.[kind] ?? {};
+            return [kind, {
+                style: rule.style ?? '',
+                classWords: (rule.classWords ?? []).map(w => String(w).toLowerCase()),
+                maxLength: Number(rule.maxLength) || 0,
+                abbreviations: Object.fromEntries(Object.entries(rule.abbreviations ?? {}).map(([w, a]) => [w.toLowerCase(), a])),
+            }];
+        }))]));
+    }
+
+    /** The rule for a level's entities or attributes. */
+    rule(level, kind) {
+        return this.rules[level]?.[kind] ?? null;
+    }
+
+    /**
+     * What a name breaks of the rule for its level and kind: a reason each,
+     * none when it keeps it.
+     * @param {string} level
+     * @param {'entities'|'attributes'} kind
+     * @param {string} name
+     * @returns {string[]}
+     */
+    check(level, kind, name) {
+        const rule = this.rule(level, kind);
+        if (!rule || !name) return [];
+        const reasons = [];
+        const style = NameStyle.get(rule.style);
+        if (style && !style.matches(name)) reasons.push(`is not ${style.label} (${style.suggest(name)})`);
+        const words = NameStyle.words(name).map(w => w.toLowerCase());
+        if (rule.classWords.length && !rule.classWords.includes(words[words.length - 1])) {
+            reasons.push(`does not end in a class word (${rule.classWords.slice(0, 5).join(', ')}…)`);
+        }
+        if (rule.maxLength && name.length > rule.maxLength) reasons.push(`is longer than ${rule.maxLength}`);
+        for (const word of words) {
+            if (rule.abbreviations[word]) reasons.push(`has "${word}" where the standard writes "${rule.abbreviations[word]}"`);
+        }
+        return reasons;
+    }
+
+    toJSON() {
+        return Object.fromEntries(Object.entries(this.rules).map(([level, kinds]) => [level, Object.fromEntries(Object.entries(kinds).map(([kind, rule]) => [kind, {
+            ...(rule.style && { style: rule.style }),
+            ...(rule.classWords.length && { classWords: [...rule.classWords] }),
+            ...(rule.maxLength && { maxLength: rule.maxLength }),
+            ...(Object.keys(rule.abbreviations).length && { abbreviations: { ...rule.abbreviations } }),
+        }]))]));
+    }
+
+    /**
+     * Its dialog's fields: a heading per level, and for its entities and
+     * attributes the style (any, or one of NameStyle's), the class words, the
+     * longest a name may be, and abbreviations (`word = abbreviation` a line).
+     * @param {NamingStandard|null} standard
+     */
+    static fields(standard) {
+        const styles = [['', 'Any'], ...NameStyle.all().map(s => [s.key, s.label])];
+        return Object.entries(KINDS).flatMap(([level, kinds]) => [
+            { type: 'heading', label: `${level.charAt(0).toUpperCase()}${level.slice(1)} level` },
+            ...kinds.flatMap(kind => {
+                const rule = standard?.rule(level, kind);
+                const key = (what) => `${level}.${kind}.${what}`;
+                return [
+                    { key: key('style'), label: `${kind === 'entities' ? 'Entity' : 'Attribute'} names`, type: 'select', value: rule?.style ?? '', choices: styles },
+                    ...(kind === 'attributes' ? [{ key: key('classWords'), label: 'Class words', type: 'text', value: (rule?.classWords ?? []).join(', '), placeholder: 'id, name, date, amount, code…' }] : []),
+                    { key: key('maxLength'), label: 'At most (characters)', type: 'number', value: rule?.maxLength || '', min: 0 },
+                    ...(level === 'physical' ? [{
+                        key: key('abbreviations'), label: 'Abbreviations', type: 'textarea', rows: 2,
+                        value: Object.entries(rule?.abbreviations ?? {}).map(([w, a]) => `${w} = ${a}`).join('\n'), placeholder: 'number = num',
+                    }] : []),
+                ];
+            }),
+        ]);
+    }
+
+    /** A standard's spec from those fields. */
+    static specFrom(values) {
+        return Object.fromEntries(Object.entries(KINDS).map(([level, kinds]) => [level, Object.fromEntries(kinds.map(kind => {
+            const v = (what) => values[`${level}.${kind}.${what}`];
+            return [kind, {
+                style: v('style') || '',
+                classWords: String(v('classWords') ?? '').split(/[,\s]+/).filter(Boolean),
+                maxLength: Number(v('maxLength')) || 0,
+                abbreviations: Object.fromEntries(String(v('abbreviations') ?? '').split('\n')
+                    .map(l => l.split('=').map(x => x.trim())).filter(([w, a]) => w && a)),
+            }];
+        }))]));
+    }
+}

package/src/charting/datamodel/naming/PascalCaseStyle.js

@@ -0,0 +1,13 @@
+import { NameStyle } from './NameStyle.js';
+
+/** PascalCase: words run together, each capitalised ('PartyId'), as BIAN names its schemas. */
+export class PascalCaseStyle extends NameStyle {
+    static key = 'pascal';
+    static label = 'PascalCase';
+
+    format(words) {
+        return words.map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+    }
+}
+
+NameStyle.register(PascalCaseStyle);

package/src/charting/datamodel/naming/SnakeCaseStyle.js

@@ -0,0 +1,13 @@
+import { NameStyle } from './NameStyle.js';
+
+/** snake_case: lower case words joined by underscores ('party_id'). */
+export class SnakeCaseStyle extends NameStyle {
+    static key = 'snake';
+    static label = 'snake_case';
+
+    format(words) {
+        return words.map(w => w.toLowerCase()).join('_');
+    }
+}
+
+NameStyle.register(SnakeCaseStyle);

package/src/charting/datamodel/naming/TitleCaseStyle.js

@@ -0,0 +1,25 @@
+import { NameStyle } from './NameStyle.js';
+
+/** Words that stay small inside a title. */
+const MINOR = new Set(['a', 'an', 'and', 'as', 'at', 'by', 'for', 'in', 'of', 'on', 'or', 'the', 'to', 'with']);
+
+/**
+ * Title Case: words apart, each capitalised ('Party Reference Data'), small
+ * words inside it may stay small ('Terms of Use'), and an acronym stays as it is
+ * ('ECM And DCM').
+ */
+export class TitleCaseStyle extends NameStyle {
+    static key = 'title';
+    static label = 'Title Case';
+
+    format(words) {
+        return words.map((w, i) => (i > 0 && MINOR.has(w.toLowerCase()) ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1))).join(' ');
+    }
+
+    matches(name) {
+        const words = String(name ?? '').split(' ');
+        return words.every(Boolean) && words.every((w, i) => /^[A-Z0-9]/.test(w) || (i > 0 && MINOR.has(w)));
+    }
+}
+
+NameStyle.register(TitleCaseStyle);

package/src/charting/datamodel/naming/UpperSnakeStyle.js

@@ -0,0 +1,13 @@
+import { NameStyle } from './NameStyle.js';
+
+/** UPPER_SNAKE_CASE: upper case words joined by underscores ('PARTY_ID'). */
+export class UpperSnakeStyle extends NameStyle {
+    static key = 'upper-snake';
+    static label = 'UPPER_SNAKE_CASE';
+
+    format(words) {
+        return words.map(w => w.toUpperCase()).join('_');
+    }
+}
+
+NameStyle.register(UpperSnakeStyle);

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

@@ -0,0 +1,8 @@
+export { NameStyle } from './NameStyle.js';
+export { TitleCaseStyle } from './TitleCaseStyle.js';
+export { LowerWordsStyle } from './LowerWordsStyle.js';
+export { SnakeCaseStyle } from './SnakeCaseStyle.js';
+export { UpperSnakeStyle } from './UpperSnakeStyle.js';
+export { CamelCaseStyle } from './CamelCaseStyle.js';
+export { PascalCaseStyle } from './PascalCaseStyle.js';
+export { NamingStandard } from './NamingStandard.js';

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

@@ -0,0 +1,30 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+
+/**
+ * Completeness: is what the model should carry there? Measured as the share,
+ * averaged, of entities with a definition, of concepts realised at the logical
+ * level, of logical entities realised by a table, and of logical entities with
+ * someone answering for them (an owner or a steward). A share with nothing to
+ * count is left out.
+ */
+export class CompletenessCategory extends MeasuredCategory {
+    constructor() {
+        super('completeness', 'Completeness', 'Does the model have what it should: definitions, every level realised, stewards?');
+    }
+
+    measure(model) {
+        const all = model.constructor.LEVELS.flatMap(level => model.level(level).entities);
+        const concepts = model.level('conceptual').entities;
+        const logical = model.level('logical').entities;
+        const realised = (from, to) => (id) => model.mapping(from, to).targetsOf(id).length > 0;
+        const shares = [
+            ['have a definition', all.filter(e => String(e.description ?? '').trim()).length, all.length],
+            ['concepts realised at the logical level', concepts.filter(c => realised('conceptual', 'logical')(c.id)).length, concepts.length],
+            ['logical entities realised by a table', logical.filter(e => realised('logical', 'physical')(e.id)).length, logical.length],
+            ['logical entities with an owner or steward', logical.filter(e => e.stewardship?.owner || e.stewardship?.steward).length, logical.length],
+        ].filter(([, , whole]) => whole);
+        if (!shares.length) return { score: null, notes: ['nothing to measure'] };
+        const score = Math.round(shares.reduce((sum, [, part, whole]) => sum + percent(part, whole), 0) / shares.length);
+        return { score, notes: shares.map(([what, part, whole]) => `${part} of ${whole} ${what}`) };
+    }
+}

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

@@ -0,0 +1,33 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+
+/** The model check's findings about consistency. */
+const INCONSISTENT = new Set(['type-conflict', 'classification-lost', 'rule-attribute-missing', 'mapping-dangling']);
+
+/**
+ * Consistency: does the model agree with itself? Measured as the share of
+ * logical entities and tables the model check finds nothing inconsistent on
+ * (one name with two types, a classification lost down the mappings, a rule on
+ * an attribute not there, a mapping to nothing).
+ */
+export class ConsistencyCategory extends MeasuredCategory {
+    static INCONSISTENT = INCONSISTENT;
+
+    constructor() {
+        super('consistency', 'Consistency', 'Does it agree with itself: one name one type, classifications kept across levels?');
+    }
+
+    measure(model, findings) {
+        const entities = ['logical', 'physical'].flatMap(level => model.level(level).entities.map(e => `${level}:${e.id}`));
+        const found = findings.filter(f => INCONSISTENT.has(f.code));
+        if (!entities.length) return { score: null, notes: ['no logical entities or tables'] };
+        const touched = new Set(found.flatMap(f => (f.ids ?? []).map(id => `${f.level}:${id}`)).filter(k => entities.includes(k)));
+        // A finding on no entity (a rule, a mapping) counts as one entity's worth.
+        const elsewhere = found.filter(f => !(f.ids ?? []).some(id => entities.includes(`${f.level}:${id}`))).length;
+        const counts = found.reduce((m, f) => ((m[f.code] = (m[f.code] ?? 0) + 1), m), {});
+        const sound = Math.max(0, entities.length - touched.size - elsewhere);
+        return {
+            score: percent(sound, entities.length),
+            notes: [`${sound} of ${entities.length} logical entities and tables consistent`, ...Object.entries(counts).map(([code, n]) => `${n} ${code}`)],
+        };
+    }
+}

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

@@ -0,0 +1,33 @@
+import { MeasuredCategory, percent } from './ScorecardCategory.js';
+
+/** Words a definition has at least, to say more than a label would. */
+const ENOUGH_WORDS = 4;
+
+/**
+ * Definitions: do the definitions there say something? Measured as the share
+ * of definitions (of entities, at every level) that do more than restate the
+ * name and run to at least a few words. How many are missing is Completeness's.
+ */
+export class DefinitionsCategory extends MeasuredCategory {
+    static ENOUGH_WORDS = ENOUGH_WORDS;
+
+    constructor() {
+        super('definitions', 'Definitions', 'Are the definitions clear: more than the name, in a sentence?');
+    }
+
+    measure(model) {
+        const plain = (s) => String(s ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+        const defined = model.constructor.LEVELS.flatMap(level => model.level(level).entities).filter(e => String(e.description ?? '').trim());
+        if (!defined.length) return { score: null, notes: ['no definitions to judge (see Completeness)'] };
+        const restating = defined.filter(e => plain(e.description) === plain(e.name));
+        const short = defined.filter(e => !restating.includes(e) && String(e.description).trim().split(/\s+/).length < ENOUGH_WORDS);
+        return {
+            score: percent(defined.length - restating.length - short.length, defined.length),
+            notes: [
+                `${defined.length - restating.length - short.length} of ${defined.length} definitions say something`,
+                ...(restating.length ? [`${restating.length} only restate the name`] : []),
+                ...(short.length ? [`${short.length} fewer than ${ENOUGH_WORDS} words`] : []),
+            ],
+        };
+    }
+}

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