@peter.prib/renderengine 0.2.5 → 0.2.7

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