@peter.prib/renderengine 0.2.7 → 0.2.11

package/src/charting/datamodel/SqlDdl.js

@@ -0,0 +1,85 @@
+/** Words SQL keeps for itself that a name may not be left bare as. */
+const RESERVED = new Set(['user', 'order', 'group', 'table', 'select', 'from', 'where', 'by', 'to', 'key', 'check', 'default', 'index', 'primary', 'foreign', 'references', 'unique', 'column', 'constraint', 'value', 'values', 'date', 'time', 'timestamp', 'level', 'position', 'role']);
+
+/**
+ * SqlDdl — a model's physical level as SQL DDL (DMBOK2's data integration: the
+ * design handed to a database): a CREATE TABLE per table, its columns with
+ * their types (`defaultType` where a column has none) and NOT NULL where
+ * required, its primary key and UNIQUE columns; a FOREIGN KEY per column that
+ * references another (`references`: a table, or `table.column`, by id or name;
+ * a table alone: its primary key); and COMMENT ONs for definitions. Names are
+ * quoted where SQL would not take them bare. ANSI SQL, as PostgreSQL reads it.
+ */
+export class SqlDdl {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.defaultType] - A column's type when it names none
+     * @param {boolean} [options.comments] - Whether definitions become COMMENT ONs
+     */
+    constructor({ defaultType = 'VARCHAR(255)', comments = true } = {}) {
+        this.defaultType = defaultType;
+        this.comments = comments;
+    }
+
+    /** A name as SQL takes it: bare when it can be, else double-quoted. */
+    static name(text) {
+        const s = String(text);
+        return /^[a-z_][a-z0-9_]*$/.test(s) && !RESERVED.has(s) ? s : `"${s.replace(/"/g, '""')}"`;
+    }
+
+    /**
+     * A table's name as SQL takes it: a schema-qualified one (`sales.customer`)
+     * each part as name() has it, so it names the table in its schema rather
+     * than one table called "sales.customer".
+     */
+    static tableName(text) {
+        return String(text).split('.').map(SqlDdl.name).join('.');
+    }
+
+    /** A text as an SQL string literal. */
+    static literal(text) {
+        return `'${String(text).replace(/'/g, "''")}'`;
+    }
+
+    /** The DDL for a model's physical level. @returns {string} */
+    write(model) {
+        const schema = model.level('physical');
+        const tables = schema.entities;
+        const table = SqlDdl.tableName;
+        const out = [`-- ${model.name || 'Data model'}: the physical level, ${tables.length} table${tables.length === 1 ? '' : 's'}`, ''];
+        for (const t of tables) {
+            const columns = t.attributes ?? [];
+            const keys = columns.filter(c => c.isPK).map(c => SqlDdl.name(c.name));
+            const lines = [
+                ...columns.map(c => `    ${SqlDdl.name(c.name)} ${c.type || this.defaultType}${c.required || c.isPK ? ' NOT NULL' : ''}`),
+                ...(keys.length ? [`    PRIMARY KEY (${keys.join(', ')})`] : []),
+                ...columns.filter(c => c.isUnique && !c.isPK).map(c => `    UNIQUE (${SqlDdl.name(c.name)})`),
+            ];
+            out.push(`CREATE TABLE ${table(t.name)} (`, lines.join(',\n'), ');', '');
+        }
+        for (const t of tables) {
+            for (const c of (t.attributes ?? []).filter(a => a.isFK && a.references)) {
+                const ref = schema.resolveReference(c.references);
+                if (!ref) {
+                    out.push(`-- ${t.name}.${c.name} references ${c.references}, which is not a table here`);
+                    continue;
+                }
+                const theirs = ref.column ? [ref.column] : (ref.entity.attributes ?? []).filter(a => a.isPK).map(a => a.name);
+                if (!theirs.length) {
+                    out.push(`-- ${t.name}.${c.name} references ${ref.entity.name}, which has no primary key`);
+                    continue;
+                }
+                out.push(`ALTER TABLE ${table(t.name)} ADD CONSTRAINT ${SqlDdl.name(`fk_${t.name}_${c.name}`.toLowerCase().replace(/[^a-z0-9_]+/g, '_'))}`
+                    + ` FOREIGN KEY (${SqlDdl.name(c.name)}) REFERENCES ${table(ref.entity.name)} (${theirs.map(SqlDdl.name).join(', ')});`);
+            }
+        }
+        if (this.comments) {
+            const notes = tables.flatMap(t => [
+                ...(t.description ? [`COMMENT ON TABLE ${table(t.name)} IS ${SqlDdl.literal(t.description)};`] : []),
+                ...(t.attributes ?? []).filter(c => c.description).map(c => `COMMENT ON COLUMN ${table(t.name)}.${SqlDdl.name(c.name)} IS ${SqlDdl.literal(c.description)};`),
+            ]);
+            if (notes.length) out.push('', ...notes);
+        }
+        return `${out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`;
+    }
+}

package/src/charting/datamodel/SqlDdlFileFormat.js

@@ -0,0 +1,23 @@
+import { ModelFileFormat } from '../ModelFileFormat.js';
+import { SqlDdl } from './SqlDdl.js';
+
+/**
+ * SqlDdlFileFormat — a data model's physical level as SQL DDL (SqlDdl), a file
+ * to export; DDL is not read back.
+ */
+export class SqlDdlFileFormat extends ModelFileFormat {
+    /** @param {Object} [options] - SqlDdl's */
+    constructor(options = {}) {
+        super();
+        this.ddl = new SqlDdl(options);
+    }
+
+    get label() { return 'SQL DDL'; }
+    get accept() { return '.sql'; }
+    get fileName() { return 'model.sql'; }
+    get imports() { return false; }
+
+    export(model) {
+        return { data: this.ddl.write(model), mimeType: 'application/sql' };
+    }
+}

package/src/charting/datamodel/index.js

@@ -1,15 +1,21 @@
-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 { 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 { LevelEntitiesCompared, LevelRelationshipsCompared, MappingsCompared, ContextsCompared, PerspectivesCompared, DataTypesCompared } from './DataModelCompared.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`] : []),
+            ],
+        };
+    }
+}