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

package/dist/convert/mapping.js

@@ -0,0 +1,273 @@
+export const MODEL_NAMESPACE = "http://www.omg.org/spec/BPMN/20100524/MODEL";
+export const DI_NAMESPACE = "http://www.omg.org/spec/BPMN/20100524/DI";
+export const DC_NAMESPACE = "http://www.omg.org/spec/DD/20100524/DC";
+export const DD_NAMESPACE = "http://www.omg.org/spec/DD/20100524/DI";
+export const XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance";
+export const BPMN_NAMESPACES = [MODEL_NAMESPACE, DI_NAMESPACE, DC_NAMESPACE, DD_NAMESPACE];
+export const REFERENCE_ATTRIBUTES = [
+    "sourceRef",
+    "targetRef",
+    "attachedToRef",
+    "processRef",
+    "default",
+    "errorRef",
+    "activityRef",
+    "escalationRef",
+    "messageRef",
+    "operationRef",
+    "itemRef",
+    "signalRef",
+    "structureRef",
+    "evaluatesToTypeRef",
+    "partitionElementRef",
+    "bpmnElement",
+    "sourceElement",
+    "targetElement",
+];
+export const REFERENCE_CHILDREN = ["flowNodeRef", "operationRef", "source", "target", "eventDefinitionRef"];
+const named = { id: "id", name: "name" };
+const withDefault = { ...named, default: "default" };
+const implementedTasks = ["businessRuleTask", "userTask"];
+const tasks = ["manualTask", "receiveTask", "scriptTask", "sendTask", "serviceTask", ...implementedTasks];
+const withImplementation = { ...withDefault, implementation: "implementation" };
+const gateways = ["exclusiveGateway", "parallelGateway", "inclusiveGateway", "eventBasedGateway", "complexGateway"];
+const defaultableGateways = ["exclusiveGateway", "inclusiveGateway", "complexGateway"];
+const events = ["startEvent", "endEvent", "intermediateCatchEvent", "intermediateThrowEvent", "implicitThrowEvent", "boundaryEvent"];
+const definitions = [
+    "message",
+    "timer",
+    "error",
+    "signal",
+    "escalation",
+    "conditional",
+    "link",
+    "compensate",
+    "cancel",
+    "terminate",
+].map((kind) => `${kind}EventDefinition`);
+const capitalize = (name) => name[0].toUpperCase() + name.slice(1);
+const typed = (names, attributes = named, type) => Object.fromEntries(names.map((name) => [name, { type: type ?? capitalize(name), attributes }]));
+const expression = {
+    type: "FormalExpression",
+    attributes: { language: "language", evaluatesToTypeRef: "evaluatesToTypeRef" },
+    consumed: [`{${XSI_NAMESPACE}}type`],
+    bodyTerm: "body",
+    anonymous: true,
+    requiresBody: true,
+};
+const eventReferences = { eventDefinitionRef: "eventDefinitionRef" };
+export const ELEMENT_MAPPINGS = {
+    process: {
+        type: "Process",
+        attributes: { ...named, isExecutable: "isExecutable", processType: "processType", isClosed: "isClosed" },
+        booleans: ["isExecutable", "isClosed"],
+    },
+    subProcess: {
+        type: "SubProcess",
+        attributes: { ...withDefault, triggeredByEvent: "triggeredByEvent" },
+        booleans: ["triggeredByEvent"],
+    },
+    adHocSubProcess: {
+        type: "AdHocSubProcess",
+        attributes: { ...withDefault, triggeredByEvent: "triggeredByEvent", ordering: "ordering", cancelRemainingInstances: "cancelRemainingInstances" },
+        booleans: ["triggeredByEvent", "cancelRemainingInstances"],
+        singles: { completionCondition: "completionCondition" },
+    },
+    transaction: {
+        type: "Transaction",
+        attributes: { ...withDefault, triggeredByEvent: "triggeredByEvent", method: "method" },
+        booleans: ["triggeredByEvent"],
+        hashPrefixed: ["method"],
+    },
+    ...typed(["laneSet", "childLaneSet"], { id: "id" }, "LaneSet"),
+    lane: {
+        type: "Lane",
+        attributes: { ...named, partitionElementRef: "partitionElementRef" },
+        textLists: { flowNodeRef: "flowNodeRef" },
+        singles: { childLaneSet: "childLaneSet", partitionElement: "partitionElement" },
+    },
+    collaboration: { type: "Collaboration", attributes: { ...named, isClosed: "isClosed" }, booleans: ["isClosed"] },
+    participant: { type: "Participant", attributes: { ...named, processRef: "processRef" } },
+    association: {
+        type: "Association",
+        attributes: { ...named, sourceRef: "sourceRef", targetRef: "targetRef", associationDirection: "associationDirection" },
+    },
+    messageFlow: {
+        type: "MessageFlow",
+        attributes: { ...named, sourceRef: "sourceRef", targetRef: "targetRef", messageRef: "messageRef" },
+    },
+    message: { type: "Message", attributes: { ...named, itemRef: "itemRef" } },
+    signal: { type: "Signal", attributes: { ...named, structureRef: "structureRef" } },
+    error: { type: "Error", attributes: { ...named, errorCode: "errorCode", structureRef: "structureRef" } },
+    escalation: { type: "Escalation", attributes: { ...named, escalationCode: "escalationCode", structureRef: "structureRef" } },
+    task: { type: "ManualTask", attributes: withDefault },
+    ...typed(["manualTask"], withDefault),
+    ...typed(implementedTasks, withImplementation),
+    scriptTask: {
+        type: "ScriptTask",
+        attributes: { ...withDefault, scriptFormat: "scriptFormat" },
+        textChildren: { script: "script" },
+    },
+    serviceTask: { type: "ServiceTask", attributes: { ...withImplementation, operationRef: "operationRef" } },
+    sendTask: { type: "SendTask", attributes: { ...withImplementation, messageRef: "messageRef", operationRef: "operationRef" } },
+    receiveTask: {
+        type: "ReceiveTask",
+        attributes: { ...withImplementation, instantiate: "instantiate", messageRef: "messageRef", operationRef: "operationRef" },
+        booleans: ["instantiate"],
+    },
+    ...typed(events),
+    startEvent: {
+        type: "StartEvent",
+        attributes: { ...named, isInterrupting: "isInterrupting", parallelMultiple: "parallelMultiple" },
+        booleans: ["isInterrupting", "parallelMultiple"],
+    },
+    intermediateCatchEvent: {
+        type: "IntermediateCatchEvent",
+        attributes: { ...named, parallelMultiple: "parallelMultiple" },
+        booleans: ["parallelMultiple"],
+    },
+    ...typed(gateways, { ...named, gatewayDirection: "gatewayDirection" }),
+    eventBasedGateway: {
+        type: "EventBasedGateway",
+        attributes: { ...named, gatewayDirection: "gatewayDirection", instantiate: "instantiate", eventGatewayType: "eventGatewayType" },
+        booleans: ["instantiate"],
+    },
+    ...typed(defaultableGateways, { ...named, gatewayDirection: "gatewayDirection", default: "default" }),
+    complexGateway: {
+        type: "ComplexGateway",
+        attributes: { ...named, gatewayDirection: "gatewayDirection", default: "default" },
+        singles: { activationCondition: "activationCondition" },
+    },
+    ...typed(definitions),
+    conditionalEventDefinition: {
+        type: "ConditionalEventDefinition",
+        attributes: named,
+        singles: { condition: "condition" },
+    },
+    messageEventDefinition: {
+        type: "MessageEventDefinition",
+        attributes: { ...named, messageRef: "messageRef" },
+        textChildren: { operationRef: "operationRef" },
+    },
+    linkEventDefinition: {
+        type: "LinkEventDefinition",
+        attributes: named,
+        textLists: { source: "source" },
+        textChildren: { target: "target" },
+    },
+    signalEventDefinition: { type: "SignalEventDefinition", attributes: { ...named, signalRef: "signalRef" } },
+    boundaryEvent: {
+        type: "BoundaryEvent",
+        attributes: { ...named, attachedToRef: "attachedToRef", cancelActivity: "cancelActivity", parallelMultiple: "parallelMultiple" },
+        booleans: ["cancelActivity", "parallelMultiple"],
+    },
+    timerEventDefinition: {
+        type: "TimerEventDefinition",
+        attributes: named,
+        textChildren: { timeDate: "timeDate", timeDuration: "timeDuration", timeCycle: "timeCycle" },
+    },
+    errorEventDefinition: {
+        type: "ErrorEventDefinition",
+        attributes: { ...named, errorRef: "errorRef" },
+        lookups: [{ attribute: "errorRef", root: "error", from: "errorCode", term: "errorCode", exportOnly: true }],
+    },
+    escalationEventDefinition: {
+        type: "EscalationEventDefinition",
+        attributes: { ...named, escalationRef: "escalationRef" },
+        lookups: [{ attribute: "escalationRef", root: "escalation", from: "escalationCode", term: "escalationCode", exportOnly: true }],
+    },
+    compensateEventDefinition: {
+        type: "CompensateEventDefinition",
+        attributes: { ...named, waitForCompletion: "waitForCompletion", activityRef: "activityRef" },
+        booleans: ["waitForCompletion"],
+    },
+    sequenceFlow: {
+        type: "SequenceFlow",
+        attributes: { ...named, sourceRef: "sourceRef", targetRef: "targetRef", isImmediate: "isImmediate" },
+        booleans: ["isImmediate"],
+        singles: { conditionExpression: "conditionExpression" },
+    },
+    conditionExpression: expression,
+    completionCondition: expression,
+    condition: expression,
+    activationCondition: expression,
+};
+const diagramInterchange = {
+    BPMNDiagram: { type: "BPMNDiagram", attributes: { id: "id", name: "name", resolution: "resolution" }, numbers: ["resolution"], singles: { BPMNPlane: "plane" }, derivedChildIds: { plane: "Plane_" } },
+    BPMNPlane: { type: "BPMNPlane", attributes: { id: "id", bpmnElement: "bpmnElement" } },
+    BPMNShape: {
+        type: "BPMNShape",
+        attributes: { id: "id", bpmnElement: "bpmnElement", isExpanded: "isExpanded", isHorizontal: "isHorizontal", isMarkerVisible: "isMarkerVisible", isMessageVisible: "isMessageVisible" },
+        booleans: ["isExpanded", "isHorizontal", "isMarkerVisible", "isMessageVisible"],
+        singles: { Bounds: "bounds", BPMNLabel: "label" },
+    },
+    BPMNEdge: {
+        type: "BPMNEdge",
+        attributes: { id: "id", bpmnElement: "bpmnElement", sourceElement: "sourceElement", targetElement: "targetElement", messageVisibleKind: "messageVisibleKind" },
+        singles: { BPMNLabel: "label" },
+    },
+    BPMNLabel: { type: "BPMNLabel", attributes: {}, singles: { Bounds: "bounds" }, anonymous: true, requiresChild: "Bounds" },
+    Bounds: {
+        type: "Bounds",
+        attributes: { x: "x", y: "y", width: "width", height: "height" },
+        numbers: ["x", "y", "width", "height"],
+    },
+    waypoint: { type: "Point", attributes: { x: "x", y: "y" }, numbers: ["x", "y"] },
+};
+Object.assign(ELEMENT_MAPPINGS, diagramInterchange);
+for (const name of events) {
+    const mapping = ELEMENT_MAPPINGS[name];
+    ELEMENT_MAPPINGS[name] = { ...mapping, textLists: { ...mapping.textLists, ...eventReferences } };
+}
+const activityAttributes = { isForCompensation: "isForCompensation", startQuantity: "startQuantity", completionQuantity: "completionQuantity" };
+for (const name of [...tasks, "task", "subProcess", "adHocSubProcess", "transaction"]) {
+    const mapping = ELEMENT_MAPPINGS[name];
+    ELEMENT_MAPPINGS[name] = {
+        ...mapping,
+        attributes: { ...mapping.attributes, ...activityAttributes },
+        booleans: [...(mapping.booleans ?? []), "isForCompensation"],
+        numbers: [...(mapping.numbers ?? []), "startQuantity", "completionQuantity"],
+    };
+}
+export const ELEMENT_NAMESPACES = {
+    BPMNDiagram: DI_NAMESPACE,
+    BPMNPlane: DI_NAMESPACE,
+    BPMNShape: DI_NAMESPACE,
+    BPMNEdge: DI_NAMESPACE,
+    BPMNLabel: DI_NAMESPACE,
+    Bounds: DC_NAMESPACE,
+    waypoint: DD_NAMESPACE,
+};
+export const isEmptyRequired = (element) => {
+    const mapping = ELEMENT_MAPPINGS[element.name];
+    return ((mapping?.requiresBody === true && element.text === "") ||
+        (mapping?.requiresChild !== undefined && !element.children.some((child) => child.name === mapping.requiresChild)));
+};
+const XSI_TYPE = `{${XSI_NAMESPACE}}type`;
+export const concreteElement = (element) => {
+    const declared = element.name === "partitionElement" && element.namespace === MODEL_NAMESPACE ? element.attributes[XSI_TYPE] : undefined;
+    const local = declared?.slice(declared.indexOf(":") + 1);
+    const name = local !== undefined && /^t[A-Z]/.test(local) ? local[1].toLowerCase() + local.slice(2) : undefined;
+    return name !== undefined && name in ELEMENT_MAPPINGS && ELEMENT_NAMESPACES[name] === undefined ? { ...element, name } : element;
+};
+export const isMapped = (element) => element.namespace === (ELEMENT_NAMESPACES[element.name] ?? MODEL_NAMESPACE) && element.name in ELEMENT_MAPPINGS;
+const eventContainment = Object.fromEntries(definitions.map((name) => [name, "eventDefinitions"]));
+const container = {
+    ...Object.fromEntries([...tasks, "task", ...events, ...gateways, "subProcess", "adHocSubProcess", "transaction", "sequenceFlow"].map((name) => [name, "flowElements"])),
+    laneSet: "laneSets",
+    association: "artifacts",
+};
+const planeContainment = { BPMNShape: "planeElements", BPMNEdge: "planeElements" };
+export const CONTAINMENT = {
+    process: container,
+    subProcess: container,
+    adHocSubProcess: container,
+    transaction: container,
+    collaboration: { participant: "participants", messageFlow: "messageFlows" },
+    BPMNPlane: planeContainment,
+    BPMNEdge: { waypoint: "waypoints" },
+    laneSet: { lane: "lanes" },
+    childLaneSet: { lane: "lanes" },
+    ...Object.fromEntries(events.map((event) => [event, eventContainment])),
+};
+export const ROOT_ELEMENTS = ["message", "signal", "error", "escalation", ...definitions, "collaboration", "process", "BPMNDiagram"];

package/dist/convert/namespaces.d.ts

@@ -0,0 +1,2 @@
+import type { XmlElement } from "./xml-reader.ts";
+export declare const assertSupportedNamespaces: (element: XmlElement) => void;

package/dist/convert/namespaces.js

@@ -0,0 +1,19 @@
+import { ConversionError } from "./errors.js";
+import { BPMN_NAMESPACES } from "./mapping.js";
+const BPMN_FAMILY = /^https?:\/\/(?:www\.|schema\.)?omg\.org\/(?:spec\/(?:BPMN|DD)\/\d|bpmn)/i;
+const ATTRIBUTE_NAMESPACE = /^\{(.*)\}(.*)$/;
+const isUnrecognisedBpmn = (namespace) => BPMN_FAMILY.test(namespace) && !BPMN_NAMESPACES.includes(namespace);
+const reject = (namespace, construct, location) => {
+    throw new ConversionError("unrecognised-bpmn-namespace", `unrecognised BPMN namespace ${namespace} on ${construct} at ${location}; supported namespaces are ${BPMN_NAMESPACES.join(", ")}`);
+};
+export const assertSupportedNamespaces = (element) => {
+    if (isUnrecognisedBpmn(element.namespace))
+        reject(element.namespace, element.name, element.location);
+    for (const key of Object.keys(element.attributes)) {
+        const match = ATTRIBUTE_NAMESPACE.exec(key);
+        if (match && isUnrecognisedBpmn(match[1]))
+            reject(match[1], `${element.name}@${match[2]}`, `${element.location}/@${match[2]}`);
+    }
+    for (const child of element.children)
+        assertSupportedNamespaces(child);
+};

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

@@ -0,0 +1,2 @@
+import type { ConvertResult } from "./convert.ts";
+export declare const validateConverted: (document: ConvertResult["document"]) => Promise<string[]>;

package/dist/convert/validate-output.js

@@ -0,0 +1,28 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ROOT } from "../paths.js";
+import { compileSchema, validateWithSchema } from "../schema-validate.js";
+import { validateShacl } from "../shacl.js";
+import { validateExample } from "../validate.js";
+export const validateConverted = async (document) => {
+    const errors = validateWithSchema(document, compileSchema()).map((e) => `schema: ${e}`);
+    const local = { ...document, "@context": [join(ROOT, "contexts/combined.jsonld"), document["@context"][1]] };
+    const directory = mkdtempSync(join(tmpdir(), "convert-"));
+    try {
+        const file = join(directory, "out.jsonld");
+        writeFileSync(file, JSON.stringify(local));
+        const structural = await validateExample(file);
+        errors.push(...structural.errors);
+        if (structural.valid) {
+            const shacl = await validateShacl(file);
+            shacl.violations.forEach((v) => errors.push(`shacl: ${v.focusNode} violates ${v.sourceShape}`));
+            if (!shacl.conforms && shacl.violations.length === 0)
+                errors.push("shacl: validation failed");
+        }
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+    return errors;
+};

package/dist/convert/warnings.d.ts

@@ -0,0 +1,9 @@
+import { type XmlElement } from "./xml-reader.ts";
+export type WarningKind = "foreign-namespace" | "unsupported" | "dangling-reference";
+export interface Warning {
+    kind: WarningKind;
+    construct: string;
+    location: string;
+    message?: string;
+}
+export declare const collectWarnings: (root: XmlElement) => Warning[];

package/dist/convert/warnings.js

@@ -0,0 +1,67 @@
+import { BPMN_NAMESPACES, CONTAINMENT, concreteElement, ELEMENT_MAPPINGS, isEmptyRequired, isMapped, MODEL_NAMESPACE, REFERENCE_ATTRIBUTES, REFERENCE_CHILDREN, ROOT_ELEMENTS, XSI_NAMESPACE, } from "./mapping.js";
+import { extensionWarnings, isExtensionAttribute } from "./extensions.js";
+import { collectIds } from "./xml-reader.js";
+const ATTRIBUTE_NAMESPACE = /^\{(.*)\}(.*)$/;
+const XML_NAMESPACES = [XSI_NAMESPACE, "xml", "http://www.w3.org/XML/1998/namespace"];
+const mappedAttributes = (element) => {
+    const mapping = isMapped(element) ? ELEMENT_MAPPINGS[element.name] : undefined;
+    return new Set([...Object.keys(mapping?.attributes ?? {}), ...(mapping?.consumed ?? []), ...(mapping?.lookups ?? []).map((lookup) => lookup.attribute)]);
+};
+const consumedRoots = new Set(Object.values(ELEMENT_MAPPINGS).flatMap((mapping) => (mapping.lookups ?? []).map((lookup) => lookup.root)));
+const isHandledChild = (parent, child) => {
+    if (parent.name === "definitions")
+        return (isMapped(child) && ROOT_ELEMENTS.includes(child.name)) || (child.namespace === MODEL_NAMESPACE && consumedRoots.has(child.name));
+    const mapping = ELEMENT_MAPPINGS[parent.name];
+    if (child.namespace === MODEL_NAMESPACE && child.name === "extensionElements")
+        return true;
+    if (child.namespace === MODEL_NAMESPACE && (child.name in (mapping.textChildren ?? {}) || child.name in (mapping.textLists ?? {})))
+        return true;
+    return isMapped(concreteElement(child)) && (child.name in (mapping.singles ?? {}) || child.name in (CONTAINMENT[parent.name] ?? {}));
+};
+const attributeWarnings = (element, ids) => {
+    const allowed = mappedAttributes(element);
+    return Object.keys(element.attributes).flatMap((key) => {
+        if (allowed.has(key)) {
+            const dangling = REFERENCE_ATTRIBUTES.includes(key) && !ids.has(element.attributes[key]);
+            return dangling ? [{ kind: "dangling-reference", construct: `${element.name}@${key}`, location: `${element.location}/@${key}` }] : [];
+        }
+        if (isMapped(element) && isExtensionAttribute(key))
+            return [];
+        const foreign = ATTRIBUTE_NAMESPACE.exec(key);
+        if (foreign && XML_NAMESPACES.includes(foreign[1]))
+            return [];
+        const location = `${element.location}/@${foreign ? foreign[2] : key}`;
+        if (foreign)
+            return [{ kind: "foreign-namespace", construct: `${element.name}@${foreign[2]}`, location }];
+        return [{ kind: "unsupported", construct: `${element.name}@${key}`, location }];
+    });
+};
+const dropped = (element) => element.name === "extensionElements" && element.namespace === MODEL_NAMESPACE
+    ? element.children.map((child) => ({ kind: "foreign-namespace", construct: child.name, location: child.location }))
+    : [
+        {
+            kind: BPMN_NAMESPACES.includes(element.namespace) ? "unsupported" : "foreign-namespace",
+            construct: element.name,
+            location: element.location,
+        },
+    ];
+const childWarnings = (parent, child, ids) => {
+    if (!isHandledChild(parent, child))
+        return dropped(child);
+    if (isMapped(concreteElement(child)))
+        return walk(concreteElement(child), ids);
+    if (child.name === "extensionElements")
+        return extensionWarnings(child);
+    const dangling = REFERENCE_CHILDREN.includes(child.name) && !ids.has(child.text);
+    return dangling ? [{ kind: "dangling-reference", construct: child.name, location: child.location }] : [];
+};
+const lossyWarnings = (element) => {
+    const lossy = isMapped(element) && (element.name === "task" || isEmptyRequired(element));
+    return lossy ? [{ kind: "unsupported", construct: element.name, location: element.location }] : [];
+};
+const walk = (element, ids) => [
+    ...lossyWarnings(element),
+    ...attributeWarnings(element, ids),
+    ...element.children.flatMap((child) => childWarnings(element, child, ids)),
+];
+export const collectWarnings = (root) => walk(root, collectIds(root));

package/dist/convert/xml-reader.d.ts

@@ -0,0 +1,11 @@
+export interface XmlElement {
+    namespace: string;
+    name: string;
+    attributes: Record<string, string>;
+    declarations: [string, string][];
+    children: XmlElement[];
+    text: string;
+    location: string;
+}
+export declare const readXml: (xml: string) => XmlElement;
+export declare const collectIds: (element: XmlElement, ids?: Set<string>) => Set<string>;

package/dist/convert/xml-reader.js

@@ -0,0 +1,84 @@
+import { XMLParser } from "fast-xml-parser";
+import { ConversionError } from "./errors.js";
+const XMLNS = "xmlns";
+const parser = new XMLParser({
+    preserveOrder: true,
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    attributesGroupName: ":@",
+    trimValues: true,
+    parseTagValue: false,
+    parseAttributeValue: false,
+    htmlEntities: true,
+});
+const splitName = (qualified) => {
+    const index = qualified.indexOf(":");
+    return index < 0 ? ["", qualified] : [qualified.slice(0, index), qualified.slice(index + 1)];
+};
+const tagOf = (node) => Object.keys(node).find((key) => key !== ":@" && key !== "#text");
+const resolve = (nodes, scope, parent) => {
+    const seen = new Map();
+    return nodes.flatMap((node) => {
+        const tag = tagOf(node);
+        if (tag === undefined)
+            return [];
+        const raw = (node[":@"] ?? {});
+        const local = new Map(scope);
+        const declarations = [];
+        for (const [key, value] of Object.entries(raw)) {
+            const name = key.slice(2);
+            const declared = name === XMLNS ? "" : name.startsWith(`${XMLNS}:`) ? name.slice(XMLNS.length + 1) : undefined;
+            if (declared === undefined)
+                continue;
+            local.set(declared, value);
+            declarations.push([declared, value]);
+        }
+        const attributes = {};
+        for (const [key, value] of Object.entries(raw)) {
+            const name = key.slice(2);
+            if (name === XMLNS || name.startsWith(`${XMLNS}:`))
+                continue;
+            const [prefix, localName] = splitName(name);
+            attributes[prefix ? `{${local.get(prefix) ?? prefix}}${localName}` : localName] = value;
+        }
+        const content = node[tag];
+        const [prefix, name] = splitName(tag);
+        const index = (seen.get(name) ?? 0) + 1;
+        seen.set(name, index);
+        const location = parent === null ? `/${name}` : `${parent}/${name}[${index}]`;
+        return [
+            {
+                namespace: local.get(prefix) ?? "",
+                name,
+                attributes,
+                declarations,
+                children: resolve(content, local, location),
+                text: content
+                    .filter((child) => "#text" in child)
+                    .map((child) => String(child["#text"]))
+                    .join(""),
+                location,
+            },
+        ];
+    });
+};
+export const readXml = (xml) => {
+    let parsed;
+    try {
+        parsed = parser.parse(xml, true);
+    }
+    catch (error) {
+        throw new ConversionError("malformed-xml", `input is not well-formed XML: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const [root] = resolve(parsed.filter((node) => !("?xml" in node)), new Map(), null);
+    if (!root)
+        throw new ConversionError("malformed-xml", "input is not well-formed XML: no root element");
+    return root;
+};
+export const collectIds = (element, ids = new Set()) => {
+    if (element.attributes.id !== undefined)
+        ids.add(element.attributes.id);
+    for (const child of element.children)
+        collectIds(child, ids);
+    return ids;
+};

package/dist/convert-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/convert-cli.js

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

package/dist/convert-run.d.ts

@@ -0,0 +1,10 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_CHECK_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export interface CliResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare const USAGE = "Usage: convert <input.bpmn> [options]\n\nConverts a BPMN 2.0 XML file to BPMN-LD JSON-LD.\n\nOptions:\n  -o, --output <file>  Write JSON-LD to <file> instead of standard output\n      --base <iri>     Document base IRI (default: derived from the input file name)\n      --strict         Exit with code 1 if the conversion produced any warning\n      --validate       Validate the output against the JSON Schema and SHACL shapes\n  -h, --help           Show this help\n\nWarnings and errors are written to standard error.\n\nExit codes:\n  0  Converted successfully\n  1  Strict mode found warnings, or validation failed\n  2  Usage error or unusable input (missing file, malformed XML, not BPMN)\n";
+export declare const runConvert: (argv: string[]) => Promise<CliResult>;

package/dist/convert-run.js

@@ -0,0 +1,125 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { convert } from "./convert/convert.js";
+import { ConversionError } from "./convert/errors.js";
+import { validateConverted } from "./convert/validate-output.js";
+export const EXIT_OK = 0;
+export const EXIT_CHECK_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const USAGE = `Usage: convert <input.bpmn> [options]
+
+Converts a BPMN 2.0 XML file to BPMN-LD JSON-LD.
+
+Options:
+  -o, --output <file>  Write JSON-LD to <file> instead of standard output
+      --base <iri>     Document base IRI (default: derived from the input file name)
+      --strict         Exit with code 1 if the conversion produced any warning
+      --validate       Validate the output against the JSON Schema and SHACL shapes
+  -h, --help           Show this help
+
+Warnings and errors are written to standard error.
+
+Exit codes:
+  0  Converted successfully
+  1  Strict mode found warnings, or validation failed
+  2  Usage error or unusable input (missing file, malformed XML, not BPMN)
+`;
+class UsageError extends Error {
+}
+const parseArgs = (argv) => {
+    const options = { input: "", strict: false, validate: false };
+    let input;
+    const valueOf = (flag, index) => {
+        const value = argv[index];
+        if (value === undefined || value.startsWith("-"))
+            throw new UsageError(`${flag} requires a value`);
+        return value;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-h" || arg === "--help")
+            return "help";
+        else if (arg === "-o" || arg === "--output")
+            options.output = valueOf(arg, ++i);
+        else if (arg === "--base")
+            options.base = valueOf(arg, ++i);
+        else if (arg === "--strict")
+            options.strict = true;
+        else if (arg === "--validate")
+            options.validate = 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");
+    options.input = input;
+    return options;
+};
+const usageFailure = (message) => ({ exitCode: EXIT_USAGE, stdout: "", stderr: `error: ${message}\n\n${USAGE}` });
+const readInput = (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}`);
+    }
+};
+export const runConvert = async (argv) => {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        if (error instanceof UsageError)
+            return usageFailure(error.message);
+        throw error;
+    }
+    if (options === "help")
+        return { exitCode: EXIT_OK, stdout: USAGE, stderr: "" };
+    let xml;
+    try {
+        xml = readInput(options.input);
+    }
+    catch (error) {
+        return { exitCode: EXIT_USAGE, stdout: "", stderr: `error: ${error.message}\n` };
+    }
+    let result;
+    try {
+        result = convert(xml, { base: options.base, fileName: options.input });
+    }
+    catch (error) {
+        if (error instanceof ConversionError)
+            return { exitCode: EXIT_USAGE, stdout: "", stderr: `error: ${options.input}: ${error.message} (${error.code})\n` };
+        throw error;
+    }
+    const lines = result.warnings.map((w) => `warning: ${w.kind} ${w.construct} at ${w.location}${w.message ? `: ${w.message}` : ""}`);
+    let exitCode = EXIT_OK;
+    if (options.strict && result.warnings.length > 0) {
+        lines.push(`error: strict mode: ${result.warnings.length} warning(s)`);
+        exitCode = EXIT_CHECK_FAILED;
+    }
+    if (options.validate) {
+        const errors = await validateConverted(result.document);
+        if (errors.length > 0) {
+            lines.push(...errors.map((e) => `error: validation: ${e}`));
+            exitCode = EXIT_CHECK_FAILED;
+        }
+    }
+    const json = `${JSON.stringify(result.document, null, 2)}\n`;
+    let stdout = "";
+    if (options.output === undefined)
+        stdout = json;
+    else {
+        try {
+            writeFileSync(options.output, json);
+        }
+        catch (error) {
+            return { exitCode: EXIT_USAGE, stdout: "", stderr: [...lines, `error: cannot write ${options.output}: ${error.message}`].join("\n") + "\n" };
+        }
+    }
+    return { exitCode, stdout, stderr: lines.length ? `${lines.join("\n")}\n` : "" };
+};

package/dist/coverage-cli.d.ts

@@ -0,0 +1 @@
+export {};