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

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 {};

package/dist/coverage-cli.js

@@ -0,0 +1,8 @@
+import { ROOT } from "./paths.js";
+import { writeReports } from "./coverage.js";
+const { summary, unclassified } = writeReports(ROOT);
+console.log(`coverage: ${summary.total.covered} covered, ${summary.total.gap} gaps, ${summary.total["out-of-scope"]} out of scope`);
+if (unclassified.length) {
+    console.error(`unclassified XSD types: ${unclassified.join(", ")}`);
+    process.exitCode = 1;
+}

package/dist/coverage-mappings.d.ts

@@ -0,0 +1,3 @@
+export declare const BUILT_IN_PROPERTIES: Record<string, string>;
+export declare const CLASS_ALIASES: Record<string, string>;
+export declare const PROPERTY_ALIASES: Record<string, string>;

package/dist/coverage-mappings.js

@@ -0,0 +1,34 @@
+export const BUILT_IN_PROPERTIES = {
+    id: "@id",
+};
+export const CLASS_ALIASES = {
+    Diagram: "BPMNDiagram",
+    Plane: "BPMNPlane",
+    Node: "DiagramElement",
+    Shape: "BPMNShape",
+    LabeledShape: "BPMNShape",
+    Edge: "BPMNEdge",
+    LabeledEdge: "BPMNEdge",
+    Label: "BPMNLabel",
+};
+export const PROPERTY_ALIASES = {
+    flowElement: "flowElements",
+    laneSet: "laneSets",
+    artifact: "artifacts",
+    lane: "lanes",
+    eventDefinition: "eventDefinitions",
+    participant: "participants",
+    messageFlow: "messageFlows",
+    dataInput: "dataInputs",
+    dataOutput: "dataOutputs",
+    inputSet: "inputSets",
+    outputSet: "outputSets",
+    dataInputAssociation: "dataInputAssociations",
+    dataOutputAssociation: "dataOutputAssociations",
+    assignment: "assignments",
+    waypoint: "waypoints",
+    BPMNPlane: "plane",
+    BPMNLabel: "label",
+    Bounds: "bounds",
+    "Plane.DiagramElement": "planeElements",
+};

package/dist/coverage-scope.d.ts

@@ -0,0 +1,11 @@
+export type CoverageScope = {
+    inScope: string[];
+    outOfScopeTypes: Record<string, string[]>;
+    outOfScopeProperties: Record<string, string[]>;
+    outOfScopeReasons?: Record<string, string>;
+};
+export declare const IN_SCOPE_TYPES: string[];
+export declare const OUT_OF_SCOPE_TYPES: Record<string, string[]>;
+export declare const OUT_OF_SCOPE_PROPERTIES: Record<string, string[]>;
+export declare const OUT_OF_SCOPE_REASONS: Record<string, string>;
+export declare const REAL_SCOPE: CoverageScope;

package/dist/coverage-scope.js

@@ -0,0 +1,187 @@
+export const IN_SCOPE_TYPES = [
+    "tBaseElement",
+    "tRootElement",
+    "tFlowElement",
+    "tFlowNode",
+    "tProcess",
+    "tSubProcess",
+    "tAdHocSubProcess",
+    "tTransaction",
+    "tActivity",
+    "tTask",
+    "tUserTask",
+    "tServiceTask",
+    "tScriptTask",
+    "tSendTask",
+    "tReceiveTask",
+    "tManualTask",
+    "tBusinessRuleTask",
+    "tGateway",
+    "tExclusiveGateway",
+    "tParallelGateway",
+    "tInclusiveGateway",
+    "tEventBasedGateway",
+    "tComplexGateway",
+    "tSequenceFlow",
+    "tArtifact",
+    "tAssociation",
+    "tEvent",
+    "tCatchEvent",
+    "tThrowEvent",
+    "tStartEvent",
+    "tEndEvent",
+    "tIntermediateCatchEvent",
+    "tIntermediateThrowEvent",
+    "tBoundaryEvent",
+    "tImplicitThrowEvent",
+    "tEventDefinition",
+    "tMessageEventDefinition",
+    "tTimerEventDefinition",
+    "tErrorEventDefinition",
+    "tSignalEventDefinition",
+    "tEscalationEventDefinition",
+    "tConditionalEventDefinition",
+    "tLinkEventDefinition",
+    "tCompensateEventDefinition",
+    "tCancelEventDefinition",
+    "tTerminateEventDefinition",
+    "tMessage",
+    "tSignal",
+    "tError",
+    "tEscalation",
+    "tExpression",
+    "tFormalExpression",
+    "tLaneSet",
+    "tLane",
+    "tCollaboration",
+    "tParticipant",
+    "tMessageFlow",
+    "tAssignment",
+    "tDataAssociation",
+    "tDataInput",
+    "tDataInputAssociation",
+    "tDataObject",
+    "tDataObjectReference",
+    "tDataOutput",
+    "tDataOutputAssociation",
+    "tDataStore",
+    "tDataStoreReference",
+    "tInputOutputSpecification",
+    "tInputSet",
+    "tOutputSet",
+    "BPMNDiagram",
+    "BPMNPlane",
+    "BPMNShape",
+    "BPMNEdge",
+    "BPMNLabel",
+    "Bounds",
+    "Point",
+    "DiagramElement",
+    "Diagram",
+    "Node",
+    "Edge",
+    "LabeledEdge",
+    "Shape",
+    "LabeledShape",
+    "Label",
+    "Plane",
+];
+export const OUT_OF_SCOPE_TYPES = {
+    data: [
+        "tDataState",
+        "tInputOutputBinding",
+        "tItemDefinition",
+        "tProperty",
+    ],
+    artifacts: ["tGroup", "tTextAnnotation", "tText"],
+    choreography: [
+        "tCallChoreography",
+        "tChoreography",
+        "tChoreographyActivity",
+        "tChoreographyTask",
+        "tGlobalChoreographyTask",
+        "tSubChoreography",
+    ],
+    conversation: [
+        "tCallConversation",
+        "tConversation",
+        "tConversationAssociation",
+        "tConversationLink",
+        "tConversationNode",
+        "tGlobalConversation",
+        "tSubConversation",
+        "tMessageFlowAssociation",
+        "tParticipantAssociation",
+        "tParticipantMultiplicity",
+    ],
+    correlation: [
+        "tCorrelationKey",
+        "tCorrelationProperty",
+        "tCorrelationPropertyBinding",
+        "tCorrelationPropertyRetrievalExpression",
+        "tCorrelationSubscription",
+    ],
+    services: ["tEndPoint", "tInterface", "tOperation", "tPartnerEntity", "tPartnerRole"],
+    resources: [
+        "tHumanPerformer",
+        "tPerformer",
+        "tPotentialOwner",
+        "tResource",
+        "tResourceAssignmentExpression",
+        "tResourceParameter",
+        "tResourceParameterBinding",
+        "tResourceRole",
+    ],
+    callable: [
+        "tCallableElement",
+        "tCallActivity",
+        "tGlobalBusinessRuleTask",
+        "tGlobalManualTask",
+        "tGlobalScriptTask",
+        "tGlobalTask",
+        "tGlobalUserTask",
+    ],
+    loops: ["tComplexBehaviorDefinition", "tLoopCharacteristics", "tMultiInstanceLoopCharacteristics", "tStandardLoopCharacteristics"],
+    "categories-and-monitoring": ["tAuditing", "tCategory", "tCategoryValue", "tMonitoring", "tRelationship"],
+    "documentation-and-extensions": [
+        "tBaseElementWithMixedContent",
+        "tDocumentation",
+        "tExtension",
+        "tExtensionElements",
+        "tRendering",
+        "tScript",
+    ],
+    "di-styling": ["BPMNLabelStyle", "Font", "Style"],
+};
+export const OUT_OF_SCOPE_PROPERTIES = {
+    data: ["property", "ioBinding", "dataState", "itemSubjectRef"],
+    artifacts: ["artifact"],
+    choreography: ["choreographyRef", "definitionalCollaborationRef"],
+    conversation: [
+        "conversationNode",
+        "conversationAssociation",
+        "conversationLink",
+        "participantAssociation",
+        "messageFlowAssociation",
+        "participantMultiplicity",
+        "choreographyActivityShape",
+        "participantBandKind",
+    ],
+    correlation: ["correlationKey", "correlationSubscription"],
+    services: ["supportedInterfaceRef", "interfaceRef", "endPointRef"],
+    resources: ["resourceRole"],
+    loops: ["loopCharacteristics"],
+    "categories-and-monitoring": ["auditing", "monitoring", "categoryValueRef", "supports"],
+    "documentation-and-extensions": ["documentation", "extensionElements", "extension", "rendering"],
+    "di-styling": ["BPMNLabelStyle", "labelStyle"],
+    derived: ["incoming", "outgoing"],
+};
+export const OUT_OF_SCOPE_REASONS = {
+    derived: "FlowNode.incoming and FlowNode.outgoing are derived from the sequence flows; storing them would duplicate the graph. The exporter computes them from the sequence flows.",
+};
+export const REAL_SCOPE = {
+    inScope: IN_SCOPE_TYPES,
+    outOfScopeTypes: OUT_OF_SCOPE_TYPES,
+    outOfScopeProperties: OUT_OF_SCOPE_PROPERTIES,
+    outOfScopeReasons: OUT_OF_SCOPE_REASONS,
+};

package/dist/coverage-xsd.d.ts

@@ -0,0 +1,15 @@
+export type XsdMember = {
+    name: string;
+    kind: "attribute" | "element";
+};
+export type XsdType = {
+    file: string;
+    name: string;
+    base: string | null;
+    abstract: boolean;
+    members: XsdMember[];
+};
+export declare const parseXsd: (file: string, xml: string) => XsdType[];
+export declare const XSD_FILES: string[];
+export declare const XSD_DIR = "reference/bpmn-xsd";
+export declare const loadXsdTypes: (root: string) => XsdType[];

package/dist/coverage-xsd.js

@@ -0,0 +1,55 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { XMLParser } from "fast-xml-parser";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    removeNSPrefix: true,
+    isArray: (name) => ["complexType", "element", "attribute", "sequence", "choice", "all", "complexContent", "extension"].includes(name),
+});
+const asList = (value) => (Array.isArray(value) ? value : value ? [value] : []);
+const localName = (qname) => qname.replace(/^.*:/, "");
+const collectMembers = (node, members) => {
+    for (const attribute of asList(node.attribute)) {
+        const name = (attribute["@_name"] ?? attribute["@_ref"]);
+        if (name)
+            members.push({ name: localName(name), kind: "attribute" });
+    }
+    for (const element of asList(node.element)) {
+        const name = (element["@_name"] ?? element["@_ref"]);
+        if (name)
+            members.push({ name: localName(name), kind: "element" });
+    }
+    for (const group of ["sequence", "choice", "all", "complexContent", "extension"]) {
+        for (const child of asList(node[group]))
+            collectMembers(child, members);
+    }
+};
+const baseOf = (node) => {
+    for (const content of asList(node.complexContent)) {
+        for (const extension of asList(content.extension)) {
+            const base = extension["@_base"];
+            if (base)
+                return localName(base);
+        }
+    }
+    return null;
+};
+export const parseXsd = (file, xml) => {
+    const schema = parser.parse(xml).schema;
+    return asList(schema.complexType).map((type) => {
+        const members = [];
+        collectMembers(type, members);
+        const seen = new Set();
+        return {
+            file,
+            name: type["@_name"],
+            base: baseOf(type),
+            abstract: type["@_abstract"] === "true",
+            members: members.filter((m) => !seen.has(`${m.kind}:${m.name}`) && seen.add(`${m.kind}:${m.name}`)),
+        };
+    });
+};
+export const XSD_FILES = ["Semantic.xsd", "BPMNDI.xsd", "DC.xsd", "DI.xsd"];
+export const XSD_DIR = "reference/bpmn-xsd";
+export const loadXsdTypes = (root) => XSD_FILES.flatMap((file) => parseXsd(file, readFileSync(join(root, XSD_DIR, file), "utf8")));

package/dist/coverage.d.ts

@@ -0,0 +1,35 @@
+import type { Store } from "n3";
+import type { XsdType } from "./coverage-xsd.ts";
+import type { CoverageScope } from "./coverage-scope.ts";
+export type Status = "covered" | "gap" | "out-of-scope";
+export type CoverageItem = {
+    id: string;
+    kind: "class" | "property";
+    xsd: string;
+    ontology: string | null;
+    status: Status;
+    group?: string;
+    reason?: string;
+};
+export type Counts = Record<Status, number>;
+export type CoverageReport = {
+    summary: {
+        classes: Counts;
+        properties: Counts;
+        total: Counts;
+    };
+    unclassified: string[];
+    items: CoverageItem[];
+};
+export declare const checkCoverage: (store: Store, types: XsdType[], scope: CoverageScope) => CoverageReport;
+export declare const renderMarkdown: (report: CoverageReport) => string;
+export declare const renderJson: (report: CoverageReport) => string;
+export declare const generateReports: (root: string) => {
+    report: CoverageReport;
+    markdown: string;
+    json: string;
+};
+export declare const REPORT_MARKDOWN = "reports/coverage.md";
+export declare const REPORT_JSON = "reports/coverage.json";
+export declare const writeReports: (root: string) => CoverageReport;
+export declare const readReport: (root: string, file: string) => string;