@peter.prib/renderengine 0.2.6 → 0.2.10

package/src/charting/datamodel/BianSemanticApiReader.js

@@ -0,0 +1,183 @@
+import { BianNotation } from '../../bian.js';
+import { YamlReader } from '../../yaml/YamlReader.js';
+import { ServiceDomain } from './ServiceDomain.js';
+import { EnumerationType } from './EnumerationType.js';
+import { StructuredType } from './StructuredType.js';
+import { DataType } from './DataType.js';
+
+/** 'CurrentAccountFacility' → 'Current Account Facility'. */
+const spaced = (name) => String(name).replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2');
+/** 'Current Account Facility' → 'current-account-facility'. */
+const idOf = (name) => spaced(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+/** A schema's name from a `$ref` ('#/components/schemas/Amount' → 'Amount'), of an item's for an array. */
+const refName = (prop) => (prop?.$ref ?? prop?.items?.$ref)?.split('/').pop() ?? null;
+
+/**
+ * BianSemanticApiReader — a service domain from one of BIAN's semantic APIs
+ * (an OpenAPI file, YAML or JSON, one per service domain, as BIAN publishes
+ * them: the plain ones and those extended with ISO 20022), rather than retyped.
+ *
+ * Its operations' tags name its control record (`CR - CurrentAccountFacility`)
+ * and behaviour qualifiers (`BQ - Interest`); each becomes a logical entity
+ * with the attributes its schema has (BIAN's names), the qualifiers joined to
+ * the control record. The schemas those attributes are become data types, as
+ * deep as `depth` (1: those the attributes name): an `enum` an EnumerationType
+ * (each value's meaning from BIAN's description), an object a StructuredType,
+ * any other a DataType. A schema named as a logical entity the model already
+ * has (`entityNames`) stays a reference to it. Where the ISO 20022 version
+ * names an attribute's ISO 20022 type, the attribute (and its data type) keep it.
+ *
+ * The service domain is named by the API's title, its pattern by the artifact
+ * its control record's name ends with (BianNotation.patternOfControlRecord),
+ * its asset by the rest of that name.
+ */
+export class BianSemanticApiReader {
+    /**
+     * @param {Object} [options]
+     * @param {number} [options.depth] - How deep schemas become data types (0: none)
+     * @param {Iterable<string>} [options.entityNames] - Names of logical entities already there (any case)
+     */
+    constructor({ depth = 1, entityNames = [] } = {}) {
+        this.depth = depth;
+        this.entityNames = new Set([...entityNames].map(n => String(n).toLowerCase()));
+    }
+
+    /** A specification from a file's text: JSON, else YAML (YamlReader). */
+    static parse(text) {
+        const body = String(text).replace(/^/, '');
+        return /^\s*\{/.test(body) ? JSON.parse(body) : YamlReader.parse(body);
+    }
+
+    /**
+     * What a semantic API says, for DataModel#bringCommand.
+     * @param {Object} spec - An OpenAPI document (BianSemanticApiReader.parse)
+     * @returns {{ serviceDomains: Array<Object>, entities: Array<Object>, relationships: Array<Object>, dataTypes: Array<Object> }}
+     */
+    read(spec) {
+        const title = spec?.info?.title;
+        if (!title || !spec.paths) throw new Error('Not an OpenAPI specification (no info.title or paths)');
+        const schemas = spec.components?.schemas ?? {};
+        const { controlRecords, qualifiers } = BianSemanticApiReader.parts(spec);
+        // Some of BIAN's APIs have no control record operations (or none at all): what is there is read.
+        const [cr = null] = controlRecords;
+        const schemaOf = (name) => schemas[name] ?? ['Retrieve', 'Initiate', 'Update', 'Register', 'Create', 'Evaluate', 'Provide']
+            .map(verb => schemas[`${verb}${name}`]).find(Boolean) ?? null;
+
+        const used = new Map();   // schema name -> depth first reached
+        const attributesOf = (schema, depth) => Object.entries(schema?.properties ?? {}).map(([name, prop]) => {
+            const ref = refName(prop);
+            const iso20022 = BianSemanticApiReader.iso20022Of(prop.description);
+            if (ref && !used.has(ref)) used.set(ref, depth);
+            return {
+                name,
+                ...(ref ? { type: ref } : (prop.format || prop.type) && { type: prop.format || prop.type }),
+                ...(BianSemanticApiReader.cleanDescription(prop.description) && { description: BianSemanticApiReader.cleanDescription(prop.description) }),
+                ...(iso20022 && { iso20022 }),
+            };
+        });
+        const entity = (name) => ({
+            id: idOf(name), name: spaced(name),
+            ...(BianSemanticApiReader.cleanDescription(schemaOf(name)?.description) && { description: BianSemanticApiReader.cleanDescription(schemaOf(name)?.description) }),
+            attributes: attributesOf(schemaOf(name), 1),
+        });
+        const entities = [...(cr ? [cr] : []), ...qualifiers].map(entity);
+        const relationships = !cr ? [] : qualifiers.map(q => ({ id: `${idOf(cr)}-has-${idOf(q)}`, source: idOf(cr), target: idOf(q), name: 'has', sourceCardinality: '1', targetCardinality: '0..*' }));
+
+        // The schemas the attributes are, then theirs, as deep as asked: data types, unless entities already.
+        const dataTypes = [];
+        const isoOf = new Map();
+        for (const a of entities.flatMap(e => e.attributes)) if (a.iso20022 && a.type && !isoOf.has(a.type)) isoOf.set(a.type, a.iso20022);
+        const done = new Set();
+        for (let level = 1; level <= this.depth; level++) {
+            for (const [name, at] of [...used]) {
+                if (at !== level || done.has(name)) continue;
+                done.add(name);
+                if (this.entityNames.has(name.toLowerCase()) || this.entityNames.has(spaced(name).toLowerCase())) continue;
+                const schema = schemas[name];
+                if (!schema) continue;
+                const type = this.dataType(name, schema, level + 1, attributesOf);
+                if (isoOf.has(name) && !type.iso20022) type.iso20022 = isoOf.get(name);
+                dataTypes.push(type);
+            }
+        }
+
+        // Its pattern by its control record's artifact; with none, by its own name's ('Operations Log').
+        const crName = spaced(cr ?? title);
+        const pattern = BianNotation.patternOfControlRecord(crName);
+        const ending = pattern ? [pattern.artifact, ...pattern.formerArtifacts].find(a => crName.toLowerCase().endsWith(a.toLowerCase())) : null;
+        const serviceDomain = {
+            kind: ServiceDomain.kind,
+            id: `sd-${idOf(title)}`,
+            name: title,
+            description: BianSemanticApiReader.cleanDescription(spec.info.description),
+            asset: ending ? crName.slice(0, -ending.length).trim() : crName,
+            pattern: pattern?.name ?? '',
+            controlRecord: cr ? idOf(cr) : null,
+            qualifiers: qualifiers.map(q => ({ name: spaced(q), entity: idOf(q) })),
+        };
+        return { serviceDomains: [serviceDomain], entities, relationships, dataTypes };
+    }
+
+    /** A data type spec for a schema: an enumeration, a structure, or a plain type. */
+    dataType(name, schema, depth, attributesOf) {
+        const base = { id: `bian-${idOf(name)}`, name, ...(BianSemanticApiReader.enumerationMeanings(schema.description).size === 0 && BianSemanticApiReader.cleanDescription(schema.description) && { description: BianSemanticApiReader.cleanDescription(schema.description) }) };
+        if (Array.isArray(schema.enum)) {
+            const meanings = BianSemanticApiReader.enumerationMeanings(schema.description);
+            return { kind: EnumerationType.kind, ...base, values: schema.enum.map(v => ({ name: String(v), ...(meanings.get(String(v)) && { description: meanings.get(String(v)) }) })) };
+        }
+        if (schema.properties) {
+            return { kind: StructuredType.kind, ...base, fields: attributesOf(schema, depth) };
+        }
+        return { kind: DataType.kind, ...base, ...((schema.format || schema.type) && { basedOn: schema.format || schema.type }) };
+    }
+
+    /** The control records and behaviour qualifiers its operations' tags name, in order. */
+    static parts(spec) {
+        const controlRecords = [], qualifiers = [];
+        for (const path of Object.values(spec.paths ?? {})) {
+            for (const op of Object.values(path ?? {})) {
+                for (const tag of op?.tags ?? []) {
+                    const m = /^(CR|BQ)\b[^-]*-\s*(\S+)\s*$/.exec(String(tag));
+                    if (!m) continue;
+                    const list = m[1] === 'CR' ? controlRecords : qualifiers;
+                    if (!list.includes(m[2])) list.push(m[2]);
+                }
+            }
+        }
+        return { controlRecords, qualifiers };
+    }
+
+    /** The ISO 20022 type a description links to (`…/standardsrepository/type/CurrencyCode`), or null. */
+    static iso20022Of(description) {
+        return /iso20022\.org\/standardsrepository\/type\/([A-Za-z0-9_]+)/.exec(String(description ?? ''))?.[1] ?? null;
+    }
+
+    /** What an enumeration's description says each value means: lines "* `Value` - meaning". */
+    static enumerationMeanings(description) {
+        const meanings = new Map();
+        for (const m of String(description ?? '').matchAll(/\*\s*`([^`]+)`\s*-\s*([^\r\n]*)/g)) {
+            if (m[2].trim()) meanings.set(m[1], m[2].trim());
+        }
+        return meanings;
+    }
+
+    /**
+     * A description as said: without the ISO 20022 version's "(DDD Entity) - "
+     * and "BIAN Service Domain (…) | … |" prefixes, or its trailing
+     * "Type|Type ([link])|Standard|ISO20022" reference.
+     */
+    static cleanDescription(description) {
+        let text = String(description ?? '').replace(/\r/g, '').trim();
+        if (!text || text.startsWith('>')) return '';
+        text = text.replace(/^\(DDD [^)]*\)\s*-\s*/, '');
+        if (/^BIAN Service Domain/.test(text)) text = text.slice(text.lastIndexOf('|') + 1).trim();
+        const bar = text.indexOf('|');
+        if (bar >= 0) {
+            // "… instance CashAccountContract|CashAccountContract (link)|Standard|ISO20022": the type named twice goes too.
+            const repeated = text.slice(bar + 1).trim().split(/[\s(|]/)[0];
+            text = text.slice(0, bar).trim();
+            if (repeated && text.endsWith(repeated)) text = text.slice(0, -repeated.length).trim();
+        }
+        return text.replace(/\s+/g, ' ').trim();
+    }
+}

package/src/charting/datamodel/ClassificationLens.js

@@ -0,0 +1,33 @@
+import { DataModelPerspective } from './DataModelPerspective.js';
+import { ClassificationScheme } from './ClassificationScheme.js';
+
+/** How an entity with no classification is drawn through the lens. */
+const UNCLASSIFIED = '#f3f4f6';
+
+/**
+ * ClassificationLens — a perspective that colours what it shows by its
+ * classification (DMBOK2's data security): each entity in its sensitivity's
+ * colour (the model's ClassificationScheme), at its effective classification
+ * (the highest of its own and its attributes'), unclassified ones grey, and
+ * the classification on hover. It sees the concepts any perspective does.
+ */
+export class ClassificationLens extends DataModelPerspective {
+    static kind = 'classification';
+    static kindLabel = 'Classification lens';
+
+    decorate(entity, level, model) {
+        const scheme = model?.classificationScheme ?? new ClassificationScheme();
+        const effective = scheme.effective(entity);
+        return {
+            color: scheme.colorOf(effective.sensitivity) ?? UNCLASSIFIED,
+            details: { classification: ClassificationScheme.describe(effective) || 'unclassified' },
+        };
+    }
+
+    /** As a perspective's, its kind kept. */
+    static specFrom(values, model) {
+        return { ...DataModelPerspective.specFrom(values, model), kind: ClassificationLens.kind };
+    }
+}
+
+DataModelPerspective.register(ClassificationLens);

package/src/charting/datamodel/ClassificationScheme.js

@@ -0,0 +1,98 @@
+/** The colours sensitivity levels are drawn in, lowest first, when a scheme names none. */
+const LEVEL_COLORS = ['#dcfce7', '#e0f2fe', '#fef3c7', '#fecaca', '#e9d5ff', '#fed7aa'];
+
+/**
+ * ClassificationScheme — how a model's data is classified (DMBOK2's data
+ * security): sensitivity `levels` in order, lowest first, each with the colour
+ * a classification lens draws it in, and `categories` a piece of data may fall
+ * in (PII, PCI...). The default is the common four levels and categories; a
+ * model may keep its own.
+ *
+ * A classification, on an entity or an attribute, is its `sensitivity` (a
+ * level's name) and its `categories`; an entity's effective one is the highest
+ * of its own and its attributes', with all their categories.
+ */
+export class ClassificationScheme {
+    static DEFAULT = Object.freeze({
+        levels: [
+            { name: 'Public', color: LEVEL_COLORS[0] },
+            { name: 'Internal', color: LEVEL_COLORS[1] },
+            { name: 'Confidential', color: LEVEL_COLORS[2] },
+            { name: 'Restricted', color: LEVEL_COLORS[3] },
+        ],
+        categories: ['PII', 'PCI', 'PHI', 'Financial'],
+    });
+
+    /** @param {{levels?: Array<{name: string, color?: string}|string>, categories?: string[]}} [spec] */
+    constructor({ levels = ClassificationScheme.DEFAULT.levels, categories = ClassificationScheme.DEFAULT.categories } = {}) {
+        this.levels = levels.map((l, i) => {
+            const level = typeof l === 'string' ? { name: l } : l;
+            return { name: String(level.name), color: level.color || LEVEL_COLORS[i % LEVEL_COLORS.length] };
+        });
+        this.categories = [...categories].map(String);
+    }
+
+    /** A sensitivity's rank (0 the lowest), or -1 for none or one the scheme lacks. */
+    rank(sensitivity) {
+        return this.levels.findIndex(l => l.name.toLowerCase() === String(sensitivity ?? '').toLowerCase());
+    }
+
+    /** The colour a sensitivity is drawn in, or null. */
+    colorOf(sensitivity) {
+        return this.levels[this.rank(sensitivity)]?.color ?? null;
+    }
+
+    /** Categories as written ('PII, PCI' or a list) as a list. */
+    static categoriesOf(value) {
+        return (Array.isArray(value) ? value : String(value ?? '').split(/[,;]/)).map(c => String(c).trim()).filter(Boolean);
+    }
+
+    /**
+     * An entity's effective classification: the highest sensitivity of its own
+     * and its attributes', and all their categories.
+     * @returns {{sensitivity: string|null, categories: string[]}}
+     */
+    effective(entity) {
+        const parts = [entity, ...(entity?.attributes ?? [])];
+        let best = null;
+        for (const p of parts) if (this.rank(p?.sensitivity) > this.rank(best)) best = this.levels[this.rank(p.sensitivity)].name;
+        const categories = [...new Set(parts.flatMap(p => ClassificationScheme.categoriesOf(p?.categories)))];
+        return { sensitivity: best, categories };
+    }
+
+    /** A classification in words: 'Confidential (PII, PCI)', or '' for none. */
+    static describe({ sensitivity, categories = [] } = {}) {
+        if (!sensitivity && !categories.length) return '';
+        return [sensitivity || 'Unclassified', categories.length ? `(${categories.join(', ')})` : ''].filter(Boolean).join(' ');
+    }
+
+    toJSON() {
+        return { levels: this.levels.map(l => ({ ...l })), categories: [...this.categories] };
+    }
+
+    /** Whether it is the default (so a model need not keep it). */
+    get isDefault() {
+        return JSON.stringify(this.toJSON()) === JSON.stringify(new ClassificationScheme().toJSON());
+    }
+
+    /** Its dialog's fields: its levels a line each, lowest first (`name | colour`), its categories. */
+    static fields(scheme) {
+        return [
+            {
+                key: 'levels', label: 'Sensitivity levels', type: 'textarea', rows: 5,
+                value: scheme.levels.map(l => `${l.name} | ${l.color}`).join('\n'),
+                hint: 'Lowest first, one a line: name | colour',
+            },
+            { key: 'categories', label: 'Categories', type: 'text', value: scheme.categories.join(', '), placeholder: 'PII, PCI, PHI' },
+        ];
+    }
+
+    /** A scheme's spec from those fields. */
+    static specFrom(values) {
+        return {
+            levels: String(values.levels ?? '').split('\n').map(l => l.split('|').map(p => p.trim())).filter(([name]) => name)
+                .map(([name, color]) => ({ name, ...(color && { color }) })),
+            categories: ClassificationScheme.categoriesOf(values.categories),
+        };
+    }
+}