@peter.prib/renderengine 0.2.6 → 0.2.7

package/src/charting/datamodel/BianLandscapeReader.js

@@ -0,0 +1,185 @@
+import { BianNotation } from '../../bian.js';
+import { ServiceDomain } from './ServiceDomain.js';
+import { parseArchiFile } from '../../archimateArchive.js';
+import { parseExchangeModel } from '../../archimateExchangeFormat.js';
+import { ZipArchive } from '../../zip/ZipArchive.js';
+
+/** A stereotype as compared: no case, no spaces ('Service Domain' is 'servicedomain'). */
+const plainWord = (text) => String(text ?? '').toLowerCase().replace(/[\s_-]+/g, '');
+
+/**
+ * BianLandscapeReader — service domains from BIAN's published service
+ * landscape, an ArchiMate model (an Archi file or the Exchange Format, as
+ * parseArchiFile / parseExchangeModel give it), rather than retyped.
+ *
+ * BIAN's own model (its v14 landscape) marks each element with a stereotype:
+ * a business area is a Grouping marked BusinessArea, composed of business
+ * domains (Capabilities marked BusinessDomain), each composed of service
+ * domains (Capabilities marked ServiceDomain); other Groupings aggregate
+ * service domains as overlays (a value chain, a release wave). Where the file
+ * keeps the stereotypes (an Archi specialization, or a "Stereotype" property:
+ * `stereotypeKeys`), they say which element is which: a service domain's
+ * business domain is the container marked so, its area the one that holds that.
+ * Without them it goes by structure: a service domain is a service-domain-type
+ * element nothing of those types sits inside, its nearest container its
+ * business domain and the outermost its area.
+ *
+ * What contains what: a composition from the container to what it holds before
+ * an aggregation (an overlay's), and failing both, a box drawn inside another's
+ * in a view. A service domain's functional pattern is the one realizing it (an
+ * element named as a BIAN pattern, as BIAN's model has them), else a property
+ * (`patternKeys`); its asset a property (`assetKeys`). A pattern BIAN lacks is
+ * left for the model check to report.
+ */
+export class BianLandscapeReader {
+    /**
+     * @param {Object} [options]
+     * @param {string[]} [options.serviceDomainTypes] - Element types a service domain may be
+     * @param {string[]} [options.containerTypes] - Element types a business area or domain may be
+     * @param {string[]} [options.containmentTypes] - Relationship types from a container to what it holds, the first preferred
+     * @param {{serviceDomain: string, businessDomain: string, businessArea: string}} [options.stereotypes] - BIAN's stereotypes for each
+     * @param {string[]} [options.stereotypeKeys] - Property keys a stereotype may be under
+     * @param {string[]} [options.patternKeys] - Property keys naming its functional pattern
+     * @param {string[]} [options.assetKeys] - Property keys naming the asset it manages
+     */
+    constructor({
+        serviceDomainTypes = ['Capability'],
+        containerTypes = ['Grouping', 'Capability'],
+        containmentTypes = ['CompositionRelationship', 'AggregationRelationship'],
+        stereotypes = { serviceDomain: 'ServiceDomain', businessDomain: 'BusinessDomain', businessArea: 'BusinessArea' },
+        stereotypeKeys = ['Stereotype', 'Stereotypes', 'stereotype', 'stereotypes'],
+        patternKeys = ['Functional Pattern', 'functional pattern', 'FunctionalPattern', 'pattern'],
+        assetKeys = ['Asset Type', 'asset type', 'Asset', 'asset'],
+    } = {}) {
+        Object.assign(this, { serviceDomainTypes, containerTypes, containmentTypes, stereotypes, stereotypeKeys, patternKeys, assetKeys });
+    }
+
+    /**
+     * An ArchiMate model from a file: an Archi file (XML or an archive) or the
+     * Exchange Format, as parseArchiFile / parseExchangeModel give it.
+     * @param {string|Uint8Array|ArrayBuffer} data
+     */
+    static parse(data) {
+        const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+        if (typeof bytes !== 'string' && ZipArchive.isZip(bytes)) return parseArchiFile(bytes);
+        const text = typeof bytes === 'string' ? bytes : new TextDecoder().decode(bytes);
+        return /opengroup\.org\/xsd\/archimate/.test(text.slice(0, 2000)) ? parseExchangeModel(text) : parseArchiFile(text);
+    }
+
+    /**
+     * Service domain specs (ServiceDomain's), one per service domain in the landscape.
+     * @param {{elements: Array, relationships?: Array, views?: Array}} parsed
+     * @returns {Array<Object>}
+     */
+    read(parsed) {
+        const elements = new Map((parsed.elements ?? []).map(e => [e.id, e]));
+        const containers = this.containers(parsed, elements);
+        const stereotypeOf = this._stereotypes(parsed);
+        const is = (id, which) => stereotypeOf(elements.get(id)).includes(plainWord(this.stereotypes[which]));
+        const name = (id) => elements.get(id)?.name ?? '';
+        const marked = [...elements.keys()].some(id => is(id, 'serviceDomain'));
+        let found;
+        if (marked) {
+            // Marked so, or (as some in BIAN's own model are not) a service-domain-type element in a business domain.
+            const isServiceDomain = (e) => is(e.id, 'serviceDomain') || (this.serviceDomainTypes.includes(e.type)
+                && !is(e.id, 'businessDomain') && !is(e.id, 'businessArea') && (containers.get(e.id) ?? []).some(c => is(c, 'businessDomain')));
+            found = [...elements.values()].filter(isServiceDomain).map(e => {
+                const domain = (containers.get(e.id) ?? []).find(c => is(c, 'businessDomain'));
+                const area = [...(containers.get(domain) ?? []), ...(containers.get(e.id) ?? [])].find(c => is(c, 'businessArea'));
+                return [e, area ? name(area) : '', domain ? name(domain) : ''];
+            });
+        } else {
+            const holdsAny = new Set([...containers.values()].flat());
+            found = [...elements.values()].filter(e => this.serviceDomainTypes.includes(e.type) && !holdsAny.has(e.id)).map(e => {
+                const chain = [];
+                for (let at = containers.get(e.id)?.[0]; at && !chain.includes(at); at = containers.get(at)?.[0]) chain.push(at);
+                return [e, chain.length ? name(chain[chain.length - 1]) : '', chain.length > 1 ? name(chain[0]) : ''];
+            });
+        }
+        // A model may hold copies of one service domain (BIAN's has some, for other diagrams): the placed one is it.
+        const placed = new Set(found.filter(([, , domain]) => domain).map(([e]) => plainWord(e.name)));
+        const seen = new Set();
+        found = found.filter(([e, , domain]) => {
+            const key = plainWord(e.name);
+            if (seen.has(key) || (!domain && placed.has(key))) return false;
+            if (domain || !placed.has(key)) seen.add(key);
+            return true;
+        });
+        const realizedBy = this._patternsRealizing(parsed, elements);
+        return found.map(([e, businessArea, businessDomain]) => {
+            const pattern = realizedBy.get(e.id) ?? this._property(e, this.patternKeys);
+            return {
+                kind: ServiceDomain.kind,
+                id: e.id,
+                name: e.name ?? '',
+                ...(e.documentation && { description: e.documentation }),
+                businessArea, businessDomain,
+                asset: this._property(e, this.assetKeys) ?? '',
+                pattern: BianNotation.findPattern(pattern)?.name ?? pattern ?? '',
+            };
+        });
+    }
+
+    /**
+     * What each element sits in (child id -> its containers, the likeliest
+     * first): by the containment relationships, a type's before the next's
+     * (composition before aggregation), then by being drawn inside a container
+     * in a view.
+     */
+    containers(parsed, elements = new Map((parsed.elements ?? []).map(e => [e.id, e]))) {
+        const isContainer = (id) => this.containerTypes.includes(elements.get(id)?.type);
+        const of = new Map();
+        const add = (child, container) => {
+            if (!elements.has(child) || child === container) return;
+            const list = of.get(child) ?? [];
+            if (!list.includes(container)) of.set(child, [...list, container]);
+        };
+        for (const type of this.containmentTypes) {
+            for (const r of parsed.relationships ?? []) if (r.type === type && isContainer(r.source)) add(r.target, r.source);
+        }
+        const walk = (visuals, container) => {
+            for (const v of visuals ?? []) {
+                const id = v.archimateElement;
+                if (id && container) add(id, container);
+                walk(v.children, id && isContainer(id) ? id : container);
+            }
+        };
+        for (const view of parsed.views ?? []) walk(view.children, null);
+        return of;
+    }
+
+    /** An element's stereotypes (compared plainly): its Archi specialization's name, and any stereotype property. @private */
+    _stereotypes(parsed) {
+        const profiles = new Map((parsed.archi?.elements ?? []).filter(e => e.tag === 'profile').map(p => [p.attributes?.id, p.attributes?.name]));
+        return (element) => {
+            if (!element) return [];
+            const profile = element.archi?.attributes?.profiles;
+            return [
+                ...(profile ? String(profile).split(/\s+/).map(id => profiles.get(id)).filter(Boolean) : []),
+                ...String(this._property(element, this.stereotypeKeys) ?? '').split(/[,;|]/),
+            ].map(plainWord).filter(Boolean);
+        };
+    }
+
+    /** Each service domain's pattern by what realizes it: an element named as a BIAN functional pattern. @private */
+    _patternsRealizing(parsed, elements) {
+        const patternOf = new Map();
+        for (const r of parsed.relationships ?? []) {
+            if (r.type !== 'RealizationRelationship' || patternOf.has(r.target)) continue;
+            const pattern = BianNotation.findPattern(elements.get(r.source)?.name);
+            if (pattern) patternOf.set(r.target, pattern.name);
+        }
+        return patternOf;
+    }
+
+    /** The first of some property keys an element has a value for. @private */
+    _property(element, keys) {
+        const props = element.properties ?? {};
+        const pairs = Array.isArray(props) ? props.map(p => [p.key, p.value]) : Object.entries(props);
+        for (const key of keys) {
+            const hit = pairs.find(([k, v]) => k === key && v);
+            if (hit) return String(hit[1]).trim();
+        }
+        return null;
+    }
+}

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