@bpmn-ld/bpmn-ld 0.0.0-stage → 0.2.0

package/dist/check-xml-cli.js

@@ -0,0 +1,5 @@
+import { runCheckXml } from "./check-xml-run.js";
+const { exitCode, stdout, stderr } = await runCheckXml(process.argv.slice(2));
+process.stdout.write(stdout);
+process.stderr.write(stderr);
+process.exitCode = exitCode;

package/dist/check-xml-run.d.ts

@@ -0,0 +1,10 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_CHECK_FAILED = 1;
+export declare const EXIT_BAD_INPUT = 2;
+export interface CliResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare const USAGE = "Usage: check-xml <input.bpmn> [options]\n\nChecks a BPMN 2.0 XML file with tools independent of this project:\n  xsd     validation against the normative BPMN 2.0 XSD\n  moddle  import with bpmn-moddle\n  lint    bpmnlint with the generic recommended rule set\n\nOptions:\n      --json  Write the report as JSON to standard output\n  -h, --help  Show this help\n\nExit codes:\n  0  No check reported an error (warnings are allowed)\n  1  At least one check reported an error\n  2  Usage error or unreadable input\n";
+export declare const runCheckXml: (argv: string[]) => Promise<CliResult>;

package/dist/check-xml-run.js

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { checkXml } from "./check-xml/check.js";
+export const EXIT_OK = 0;
+export const EXIT_CHECK_FAILED = 1;
+export const EXIT_BAD_INPUT = 2;
+export const USAGE = `Usage: check-xml <input.bpmn> [options]
+
+Checks a BPMN 2.0 XML file with tools independent of this project:
+  xsd     validation against the normative BPMN 2.0 XSD
+  moddle  import with bpmn-moddle
+  lint    bpmnlint with the generic recommended rule set
+
+Options:
+      --json  Write the report as JSON to standard output
+  -h, --help  Show this help
+
+Exit codes:
+  0  No check reported an error (warnings are allowed)
+  1  At least one check reported an error
+  2  Usage error or unreadable input
+`;
+class UsageError extends Error {
+}
+const parseArgs = (argv) => {
+    let input;
+    let json = false;
+    for (const arg of argv) {
+        if (arg === "-h" || arg === "--help")
+            return "help";
+        else if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-"))
+            throw new UsageError(`unknown option ${arg}`);
+        else if (input !== undefined)
+            throw new UsageError(`unexpected extra argument ${arg}`);
+        else
+            input = arg;
+    }
+    if (input === undefined)
+        throw new UsageError("missing input file");
+    return { input, json };
+};
+const readText = (path) => {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        const reason = error.code === "ENOENT" ? "no such file" : (error.message ?? "cannot read");
+        throw new UsageError(`cannot read ${path}: ${reason}`);
+    }
+};
+const formatIssue = (issue) => {
+    const rule = issue.rule ? ` [${issue.rule}]` : "";
+    const location = issue.location ? ` (${issue.location})` : "";
+    return `  ${issue.severity}:${rule} ${issue.message}${location}`;
+};
+const formatText = (report) => Object.entries(report.checks)
+    .map(([name, check]) => [`${name}: ${check.status}`, ...check.issues.map(formatIssue)].join("\n"))
+    .join("\n") + "\n";
+export const runCheckXml = async (argv) => {
+    let options;
+    let xml;
+    try {
+        options = parseArgs(argv);
+        if (options === "help")
+            return { exitCode: EXIT_OK, stdout: USAGE, stderr: "" };
+        xml = readText(options.input);
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return { exitCode: EXIT_BAD_INPUT, stdout: "", stderr: `error: ${error.message}\n\n${USAGE}` };
+        throw error;
+    }
+    const report = await checkXml(xml);
+    const stdout = options.json ? `${JSON.stringify(report, null, 2)}\n` : formatText(report);
+    return { exitCode: report.ok ? EXIT_OK : EXIT_CHECK_FAILED, stdout, stderr: "" };
+};

package/dist/convert/analyze-output.d.ts

@@ -0,0 +1,3 @@
+import type { Finding } from "../analyze/findings.ts";
+import type { ConvertResult } from "./convert.ts";
+export declare const analyzeConverted: (document: ConvertResult["document"]) => Promise<Finding[]>;

package/dist/convert/analyze-output.js

@@ -0,0 +1,8 @@
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { analyze } from "../analyze/analyze.js";
+import { ROOT } from "../paths.js";
+export const analyzeConverted = (document) => {
+    const local = { ...document, "@context": [pathToFileURL(join(ROOT, "contexts/combined.jsonld")).href, document["@context"][1]] };
+    return analyze(local, document["@context"][1]["@base"]);
+};

package/dist/convert/convert.d.ts

@@ -0,0 +1,19 @@
+import { type Warning } from "./warnings.ts";
+export interface ConvertOptions {
+    base?: string;
+    fileName?: string;
+}
+export type { Warning };
+export type Node = Record<string, any>;
+export interface ConvertResult {
+    document: {
+        "@context": [string, {
+            "@base": string;
+        } & Record<string, unknown>];
+        "@graph": Node[];
+    };
+    warnings: Warning[];
+}
+export declare const COMBINED_CONTEXT_IRI: string;
+export declare const defaultBase: (fileName?: string) => string;
+export declare const convert: (xml: string, options?: ConvertOptions) => ConvertResult;

package/dist/convert/convert.js

@@ -0,0 +1,96 @@
+import { basename, extname } from "node:path";
+import { BPMN_NAMESPACE } from "../namespace.js";
+import { PUBLISH_BASE } from "../versioning.js";
+import { ConversionError } from "./errors.js";
+import { CONTAINMENT, concreteElement, ELEMENT_MAPPINGS, isEmptyRequired, isMapped, MODEL_NAMESPACE, ROOT_ELEMENTS } from "./mapping.js";
+import { extensionProperties, Prefixes } from "./extensions.js";
+import { assertSupportedNamespaces } from "./namespaces.js";
+import { collectWarnings } from "./warnings.js";
+import { readXml } from "./xml-reader.js";
+export const COMBINED_CONTEXT_IRI = `${PUBLISH_BASE}/latest/contexts/combined.jsonld`;
+const DEFAULT_MODEL_NAME = "model";
+export const defaultBase = (fileName) => {
+    const name = fileName ? basename(fileName, extname(fileName)) : "";
+    return `${new URL(BPMN_NAMESPACE).origin}/models/${encodeURIComponent(name || DEFAULT_MODEL_NAME)}/`;
+};
+const mapElement = (element, root, prefixes) => {
+    const mapping = ELEMENT_MAPPINGS[element.name];
+    const node = {};
+    if (!mapping.anonymous && element.attributes.id !== undefined)
+        node.id = element.attributes.id;
+    node.type = mapping.type;
+    for (const [attribute, term] of Object.entries(mapping.attributes)) {
+        if (attribute !== "id" && element.attributes[attribute] !== undefined && element.attributes[attribute] !== "")
+            node[term] = element.attributes[attribute];
+    }
+    for (const attribute of mapping.booleans ?? []) {
+        if (node[attribute] !== undefined)
+            node[attribute] = node[attribute] === "true";
+    }
+    for (const attribute of mapping.hashPrefixed ?? []) {
+        const value = node[attribute];
+        if (typeof value === "string" && value.startsWith("##"))
+            node[attribute] = value.slice(2);
+    }
+    for (const child of element.children) {
+        const textTerm = mapping.textChildren?.[child.name];
+        if (child.namespace === MODEL_NAMESPACE && textTerm !== undefined)
+            node[textTerm] = child.text;
+    }
+    for (const child of element.children) {
+        const listTerm = mapping.textLists?.[child.name];
+        if (child.namespace === MODEL_NAMESPACE && listTerm !== undefined)
+            (node[listTerm] ??= []).push(child.text);
+    }
+    for (const lookup of (mapping.lookups ?? []).filter((candidate) => candidate.exportOnly !== true)) {
+        const reference = element.attributes[lookup.attribute];
+        const target = root.children.find((candidate) => candidate.namespace === MODEL_NAMESPACE && candidate.name === lookup.root && candidate.attributes.id === reference);
+        if (target?.attributes[lookup.from] !== undefined)
+            node[lookup.term] = target.attributes[lookup.from];
+    }
+    if (mapping.bodyTerm !== undefined && element.text !== "")
+        node[mapping.bodyTerm] = element.text;
+    for (const attribute of mapping.numbers ?? []) {
+        if (node[attribute] !== undefined)
+            node[attribute] = Number(node[attribute]);
+    }
+    for (const declared of element.children) {
+        const single = mapping.singles?.[declared.name];
+        const child = concreteElement(declared);
+        if (!isMapped(child) || single === undefined || isEmptyRequired(child))
+            continue;
+        const mapped = mapElement(child, root, prefixes);
+        const prefix = mapping.derivedChildIds?.[single];
+        if (prefix !== undefined && mapped.id === undefined && node.id !== undefined)
+            mapped.id = `${prefix}${node.id}`;
+        node[single] = mapped;
+    }
+    for (const child of element.children) {
+        const property = CONTAINMENT[element.name]?.[child.name];
+        if (!isMapped(child) || property === undefined)
+            continue;
+        const members = (node[property] ??= []);
+        members.push(mapElement(child, root, prefixes));
+    }
+    Object.assign(node, extensionProperties(element, prefixes));
+    return node;
+};
+export const convert = (xml, options = {}) => {
+    const root = readXml(xml);
+    assertSupportedNamespaces(root);
+    if (root.name !== "definitions" || root.namespace !== MODEL_NAMESPACE) {
+        const found = root.namespace ? `{${root.namespace}}${root.name}` : root.name;
+        throw new ConversionError("not-bpmn-definitions", `root element is ${found}, expected a definitions element in the BPMN 2.0 model namespace ${MODEL_NAMESPACE}`);
+    }
+    const prefixes = new Prefixes(root);
+    const graph = root.children
+        .filter((child) => isMapped(child) && ROOT_ELEMENTS.includes(child.name))
+        .map((child) => mapElement(child, root, prefixes));
+    return {
+        document: {
+            "@context": [COMBINED_CONTEXT_IRI, { "@base": options.base ?? defaultBase(options.fileName), ...prefixes.context() }],
+            "@graph": graph,
+        },
+        warnings: collectWarnings(root),
+    };
+};

package/dist/convert/errors.d.ts

@@ -0,0 +1,5 @@
+export type ConversionErrorCode = "malformed-xml" | "not-bpmn-definitions" | "unrecognised-bpmn-namespace";
+export declare class ConversionError extends Error {
+    readonly code: ConversionErrorCode;
+    constructor(code: ConversionErrorCode, message: string);
+}

package/dist/convert/errors.js

@@ -0,0 +1,8 @@
+export class ConversionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ConversionError";
+        this.code = code;
+    }
+}

package/dist/convert/extensions.d.ts

@@ -0,0 +1,23 @@
+import type { Warning } from "./warnings.ts";
+import type { XmlElement } from "./xml-reader.ts";
+export type ExtensionValue = string | {
+    [property: string]: ExtensionValue | ExtensionValue[];
+};
+type ExtensionProperties = Record<string, ExtensionValue | ExtensionValue[]>;
+export declare const isExtensionNamespace: (namespace: string) => boolean;
+export declare const isExtensionAttribute: (key: string) => boolean;
+export declare class Prefixes {
+    private readonly hints;
+    private readonly declared;
+    private readonly terms;
+    private readonly byNamespace;
+    private readonly byPrefix;
+    private generated;
+    constructor(root: XmlElement);
+    private available;
+    prefixFor(namespace: string): string;
+    context(): Record<string, unknown>;
+}
+export declare const extensionProperties: (element: XmlElement, prefixes: Prefixes) => ExtensionProperties;
+export declare const extensionWarnings: (container: XmlElement) => Warning[];
+export {};

package/dist/convert/extensions.js

@@ -0,0 +1,103 @@
+import { BPMN_NAMESPACES, MODEL_NAMESPACE, XSI_NAMESPACE } from "./mapping.js";
+import { loadContextTerms } from "./mapping-check.js";
+const ATTRIBUTE_NAMESPACE = /^\{(.*)\}(.*)$/;
+const ABSOLUTE_NAMESPACE = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const GENERAL_DELIMITER = /[:/?#[\]@]$/;
+const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+const RESERVED_PREFIXES = ["xml", "xmlns", "xsi"];
+const MIXED_CONTENT = "text content cannot be represented next to attributes or child elements";
+export const isExtensionNamespace = (namespace) => ABSOLUTE_NAMESPACE.test(namespace) && !BPMN_NAMESPACES.includes(namespace) && namespace !== XSI_NAMESPACE && namespace !== XML_NAMESPACE;
+const isIgnoredNamespace = (namespace) => namespace === XSI_NAMESPACE || namespace === XML_NAMESPACE;
+export const isExtensionAttribute = (key) => {
+    const match = ATTRIBUTE_NAMESPACE.exec(key);
+    return match !== null && isExtensionNamespace(match[1]);
+};
+const walkDeclarations = (element, visit) => {
+    element.declarations.forEach(([prefix, namespace]) => visit(prefix, namespace));
+    element.children.forEach((child) => walkDeclarations(child, visit));
+};
+export class Prefixes {
+    hints = new Map();
+    declared = new Set();
+    terms = new Set(Object.keys(loadContextTerms()));
+    byNamespace = new Map();
+    byPrefix = new Map();
+    generated = 0;
+    constructor(root) {
+        walkDeclarations(root, (prefix, namespace) => {
+            this.declared.add(prefix);
+            if (prefix !== "")
+                this.hints.set(namespace, [...(this.hints.get(namespace) ?? []), prefix]);
+        });
+    }
+    available(prefix) {
+        return !RESERVED_PREFIXES.includes(prefix) && !this.terms.has(prefix) && !this.byPrefix.has(prefix);
+    }
+    prefixFor(namespace) {
+        const known = this.byNamespace.get(namespace);
+        if (known !== undefined)
+            return known;
+        let prefix = (this.hints.get(namespace) ?? []).find((hint) => this.available(hint));
+        while (prefix === undefined) {
+            const candidate = `ns${++this.generated}`;
+            if (this.available(candidate) && !this.declared.has(candidate))
+                prefix = candidate;
+        }
+        this.byNamespace.set(namespace, prefix);
+        this.byPrefix.set(prefix, namespace);
+        return prefix;
+    }
+    context() {
+        return Object.fromEntries([...this.byPrefix].map(([prefix, namespace]) => [prefix, GENERAL_DELIMITER.test(namespace) ? namespace : { "@id": namespace, "@prefix": true }]));
+    }
+}
+const add = (target, name, value) => {
+    const existing = target[name];
+    target[name] = existing === undefined ? value : [...(Array.isArray(existing) ? existing : [existing]), value];
+};
+const addAttributes = (target, element, prefixes, unqualified) => {
+    for (const [key, value] of Object.entries(element.attributes)) {
+        const match = ATTRIBUTE_NAMESPACE.exec(key);
+        if (match) {
+            if (isExtensionNamespace(match[1]))
+                add(target, `${prefixes.prefixFor(match[1])}:${match[2]}`, value);
+        }
+        else if (unqualified)
+            add(target, `${prefixes.prefixFor(element.namespace)}:${key}`, value);
+    }
+};
+const addChildren = (target, element, prefixes) => {
+    for (const child of element.children) {
+        if (isExtensionNamespace(child.namespace))
+            add(target, `${prefixes.prefixFor(child.namespace)}:${child.name}`, valueOf(child, prefixes));
+    }
+};
+const valueOf = (element, prefixes) => {
+    const properties = {};
+    addAttributes(properties, element, prefixes, true);
+    addChildren(properties, element, prefixes);
+    return Object.keys(properties).length === 0 ? element.text : properties;
+};
+const containers = (element) => element.children.filter((child) => child.namespace === MODEL_NAMESPACE && child.name === "extensionElements");
+export const extensionProperties = (element, prefixes) => {
+    const properties = {};
+    addAttributes(properties, element, prefixes, false);
+    for (const container of containers(element))
+        addChildren(properties, container, prefixes);
+    return properties;
+};
+const rejected = (child) => ({ kind: "foreign-namespace", construct: child.name, location: child.location });
+const unrepresentable = (element) => {
+    const warnings = [];
+    const hasProperties = Object.keys(element.attributes).some((key) => !ATTRIBUTE_NAMESPACE.test(key) || isExtensionAttribute(key)) || element.children.some((child) => isExtensionNamespace(child.namespace));
+    if (hasProperties && element.text !== "")
+        warnings.push({ ...rejected(element), message: MIXED_CONTENT });
+    for (const key of Object.keys(element.attributes)) {
+        const match = ATTRIBUTE_NAMESPACE.exec(key);
+        if (match && !isExtensionNamespace(match[1]) && !isIgnoredNamespace(match[1])) {
+            warnings.push({ kind: "foreign-namespace", construct: `${element.name}@${match[2]}`, location: `${element.location}/@${match[2]}` });
+        }
+    }
+    return [...warnings, ...element.children.flatMap((child) => (isExtensionNamespace(child.namespace) ? unrepresentable(child) : [rejected(child)]))];
+};
+export const extensionWarnings = (container) => container.children.flatMap((child) => (isExtensionNamespace(child.namespace) ? unrepresentable(child) : [rejected(child)]));

package/dist/convert/mapping-check.d.ts

@@ -0,0 +1,15 @@
+import type { Store } from "n3";
+import type { ElementMapping } from "./mapping.ts";
+export interface MappingTables {
+    elements: Record<string, ElementMapping>;
+    containment: Record<string, Record<string, string>>;
+}
+export interface MappingProblem {
+    term: string;
+    kind: "class" | "property";
+    where: string;
+    reason: "not-in-context" | "not-in-ontology";
+}
+export declare const CONTEXT_FILES: string[];
+export declare const loadContextTerms: () => Record<string, string>;
+export declare const checkMapping: (tables: MappingTables, store: Store, context: Record<string, string>) => MappingProblem[];

package/dist/convert/mapping-check.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ROOT } from "../paths.js";
+import { declaredClasses, declaredProperties } from "../ontology.js";
+export const CONTEXT_FILES = ["contexts/core.jsonld", "contexts/di.jsonld"];
+export const loadContextTerms = () => {
+    const raw = {};
+    for (const file of CONTEXT_FILES) {
+        Object.assign(raw, JSON.parse(readFileSync(join(ROOT, file), "utf8"))["@context"]);
+    }
+    const expand = (value) => {
+        const [prefix, local] = value.split(":");
+        const base = raw[prefix];
+        return typeof base === "string" && local !== undefined ? `${base}${local}` : value;
+    };
+    const terms = {};
+    for (const [term, entry] of Object.entries(raw)) {
+        const id = typeof entry === "string" ? entry : entry["@id"];
+        if (id !== undefined && !id.startsWith("@"))
+            terms[term] = expand(id);
+    }
+    return terms;
+};
+const usedTerms = (tables) => {
+    const used = [];
+    const property = (term, where) => used.push({ term, kind: "property", where });
+    for (const [element, mapping] of Object.entries(tables.elements)) {
+        used.push({ term: mapping.type, kind: "class", where: `${element}.type` });
+        for (const [attribute, term] of Object.entries(mapping.attributes)) {
+            if (attribute !== "id")
+                property(term, `${element}.attributes.${attribute}`);
+        }
+        for (const field of ["singles", "textChildren", "textLists"]) {
+            for (const [child, term] of Object.entries(mapping[field] ?? {}))
+                property(term, `${element}.${field}.${child}`);
+        }
+        for (const lookup of mapping.lookups ?? [])
+            property(lookup.term, `${element}.lookups.${lookup.attribute}`);
+        for (const term of mapping.booleans ?? [])
+            property(term, `${element}.booleans`);
+        for (const term of mapping.numbers ?? [])
+            property(term, `${element}.numbers`);
+        if (mapping.bodyTerm !== undefined)
+            property(mapping.bodyTerm, `${element}.bodyTerm`);
+    }
+    for (const [element, children] of Object.entries(tables.containment)) {
+        for (const [child, term] of Object.entries(children))
+            property(term, `containment.${element}.${child}`);
+    }
+    return used;
+};
+export const checkMapping = (tables, store, context) => {
+    const classes = declaredClasses(store);
+    const properties = declaredProperties(store);
+    const problems = [];
+    for (const { term, kind, where } of usedTerms(tables)) {
+        const iri = context[term];
+        if (iri === undefined) {
+            problems.push({ term, kind, where, reason: "not-in-context" });
+        }
+        else if (!(kind === "class" ? classes : properties).has(iri)) {
+            problems.push({ term, kind, where, reason: "not-in-ontology" });
+        }
+    }
+    return problems;
+};

package/dist/convert/mapping.d.ts

@@ -0,0 +1,52 @@
+export declare const MODEL_NAMESPACE = "http://www.omg.org/spec/BPMN/20100524/MODEL";
+export declare const DI_NAMESPACE = "http://www.omg.org/spec/BPMN/20100524/DI";
+export declare const DC_NAMESPACE = "http://www.omg.org/spec/DD/20100524/DC";
+export declare const DD_NAMESPACE = "http://www.omg.org/spec/DD/20100524/DI";
+export declare const XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance";
+export declare const BPMN_NAMESPACES: string[];
+export declare const REFERENCE_ATTRIBUTES: string[];
+export declare const REFERENCE_CHILDREN: string[];
+export interface ElementMapping {
+    consumed?: string[];
+    type: string;
+    attributes: Record<string, string>;
+    booleans?: string[];
+    hashPrefixed?: string[];
+    numbers?: string[];
+    textChildren?: Record<string, string>;
+    textLists?: Record<string, string>;
+    lookups?: Lookup[];
+    bodyTerm?: string;
+    singles?: Record<string, string>;
+    anonymous?: boolean;
+    requiresBody?: boolean;
+    requiresChild?: string;
+    derivedChildIds?: Record<string, string>;
+}
+export interface Lookup {
+    attribute: string;
+    root: string;
+    from: string;
+    term: string;
+    exportOnly?: boolean;
+}
+export declare const ELEMENT_MAPPINGS: Record<string, ElementMapping>;
+export declare const ELEMENT_NAMESPACES: Record<string, string>;
+export declare const isEmptyRequired: (element: {
+    name: string;
+    text: string;
+    children: {
+        name: string;
+    }[];
+}) => boolean;
+export declare const concreteElement: <T extends {
+    namespace: string;
+    name: string;
+    attributes: Record<string, string>;
+}>(element: T) => T;
+export declare const isMapped: (element: {
+    namespace: string;
+    name: string;
+}) => boolean;
+export declare const CONTAINMENT: Record<string, Record<string, string>>;
+export declare const ROOT_ELEMENTS: string[];