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

package/dist/bpmn-ld-cli.js

@@ -0,0 +1,90 @@
+import { runAnalyze } from "./analyze-run.js";
+import { runCheckXml } from "./check-xml-run.js";
+import { runConvert } from "./convert-run.js";
+import { runExport } from "./export-run.js";
+import { runLayout } from "./layout-run.js";
+import { runRender } from "./render-run.js";
+import { runInstallSkill } from "./install-skill-run.js";
+import { runValidate } from "./validate-run.js";
+import { ROOT } from "./paths.js";
+const USAGE = `Usage: bpmn-ld <command> [args]
+
+Commands:
+  validate, analyze, convert, export, layout, check-xml, render
+  coverage, docs
+  root, install-skill
+
+Run "bpmn-ld <command> --help" for command help.
+`;
+const write = (r) => {
+    if (r.stdout)
+        process.stdout.write(r.stdout);
+    if (r.stderr)
+        process.stderr.write(r.stderr);
+};
+const run = async (argv) => {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === "-h" || command === "--help" || command === "help") {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    switch (command) {
+        case "validate": {
+            const r = await runValidate(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "analyze": {
+            const r = await runAnalyze(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "convert": {
+            const r = await runConvert(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "export": {
+            const r = await runExport(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "layout": {
+            const r = runLayout(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "check-xml": {
+            const r = await runCheckXml(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "render": {
+            const r = runRender(rest);
+            write(r);
+            return r.exitCode;
+        }
+        case "root": {
+            process.stdout.write(`${ROOT}\n`);
+            return 0;
+        }
+        case "coverage": {
+            process.stdout.write("coverage not implemented\n");
+            return 1;
+        }
+        case "docs": {
+            process.stdout.write("docs not implemented\n");
+            return 1;
+        }
+        case "install-skill": {
+            const r = await runInstallSkill(rest);
+            write(r);
+            return r.exitCode;
+        }
+        default:
+            process.stderr.write(`unknown command: ${command}\n\n${USAGE}`);
+            return 2;
+    }
+};
+const code = await run(process.argv.slice(2));
+process.exitCode = code;

package/dist/build-cli.d.ts

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

package/dist/build-cli.js

@@ -0,0 +1,2 @@
+import { build } from "./build.js";
+build();

package/dist/build.d.ts

@@ -0,0 +1,3 @@
+export declare const SCHEMA_PATH = "schema/bpmn-ld.schema.json";
+export declare const renderArtifacts: () => Record<string, string>;
+export declare const build: () => void;

package/dist/build.js

@@ -0,0 +1,38 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { renderSchema } from "./schema.js";
+import { ROOT } from "./paths.js";
+import { BPMN_NAMESPACE, BPMN_ONTOLOGY_IRI, BPMN_SHAPES_NAMESPACE, BPMNDI_NAMESPACE, BPMNDI_ONTOLOGY_IRI } from "./namespace.js";
+const values = {
+    BPMN_NAMESPACE,
+    BPMN_ONTOLOGY_IRI,
+    BPMN_SHAPES_NAMESPACE,
+    BPMNDI_NAMESPACE,
+    BPMNDI_ONTOLOGY_IRI,
+};
+const targets = {
+    "ontology/core.ttl": "templates/core.ttl",
+    "contexts/core.jsonld": "templates/core.jsonld",
+    "ontology/di.ttl": "templates/di.ttl",
+    "contexts/di.jsonld": "templates/di.jsonld",
+    "shapes/core.shapes.ttl": "templates/core.shapes.ttl",
+    "contexts/combined.jsonld": "templates/combined.jsonld",
+};
+const render = (template) => template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    const value = values[key];
+    if (value === undefined)
+        throw new Error(`Unknown template variable ${key}`);
+    return value;
+});
+export const SCHEMA_PATH = "schema/bpmn-ld.schema.json";
+const renderTemplates = () => Object.fromEntries(Object.entries(targets).map(([output, template]) => [output, render(readFileSync(join(ROOT, template), "utf8"))]));
+export const renderArtifacts = () => ({
+    ...renderTemplates(),
+    [SCHEMA_PATH]: renderSchema(),
+});
+export const build = () => {
+    for (const [path, content] of Object.entries(renderTemplates())) {
+        writeFileSync(join(ROOT, path), content);
+    }
+    writeFileSync(join(ROOT, SCHEMA_PATH), renderSchema());
+};

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

@@ -0,0 +1,3 @@
+import type { CheckReport } from "./types.ts";
+export type { CheckIssue, CheckReport, CheckResult, CheckStatus, Severity } from "./types.ts";
+export declare const checkXml: (xml: string) => Promise<CheckReport>;

package/dist/check-xml/check.js

@@ -0,0 +1,11 @@
+import { checkLint } from "./lint.js";
+import { checkModdle } from "./moddle.js";
+import { checkXsd } from "./xsd.js";
+export const checkXml = async (xml) => {
+    const xsd = await checkXsd(xml);
+    const moddle = await checkModdle(xml);
+    const lint = moddle.rootElement ? await checkLint(moddle.rootElement) : { status: "skipped", issues: [] };
+    const checks = { xsd, moddle: moddle.result, lint };
+    const ok = Object.values(checks).every((check) => check.status !== "fail");
+    return { ok, checks };
+};

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

@@ -0,0 +1,2 @@
+import type { CheckResult } from "./types.ts";
+export declare const checkLint: (rootElement: unknown) => Promise<CheckResult>;

package/dist/check-xml/lint.js

@@ -0,0 +1,47 @@
+import { createRequire } from "node:module";
+import { Linter } from "bpmnlint";
+import StaticResolver from "bpmnlint/lib/resolver/static-resolver";
+const require = createRequire(import.meta.url);
+const config = require("bpmnlint/config/recommended");
+const cache = { "config:bpmnlint/recommended": config };
+for (const rule of Object.keys(config.rules))
+    cache[`rule:bpmnlint/${rule}`] = require(`bpmnlint/rules/${rule}`);
+const createLinter = () => new Linter({ config: { extends: "bpmnlint:recommended" }, resolver: new StaticResolver(cache) });
+const isInstantiating = (element) => (element.$type === "bpmn:EventBasedGateway" || element.$type === "bpmn:ReceiveTask") && element.instantiate === true;
+const instantiatingScopes = (root) => {
+    const elements = new Set();
+    const scopes = new Set();
+    const visit = (container) => {
+        for (const member of container.flowElements ?? []) {
+            if (isInstantiating(member) && member.id !== undefined) {
+                elements.add(member.id);
+                if (container.id !== undefined)
+                    scopes.add(container.id);
+            }
+            visit(member);
+        }
+    };
+    (root.rootElements ?? []).forEach(visit);
+    return { elements, scopes };
+};
+export const checkLint = async (rootElement) => {
+    const reports = await createLinter().lint(rootElement);
+    const { elements, scopes } = instantiatingScopes(rootElement);
+    for (const [rule, found] of Object.entries(reports)) {
+        reports[rule] = found.filter((report) => !(rule === "no-implicit-start" && report.id !== undefined && elements.has(report.id)) &&
+            !(rule === "start-event-required" && report.id !== undefined && scopes.has(report.id)));
+    }
+    const issues = [];
+    for (const [rule, found] of Object.entries(reports)) {
+        for (const report of found) {
+            issues.push({
+                severity: report.category === "warn" ? "warning" : "error",
+                message: report.message,
+                rule,
+                ...(report.id ? { location: report.id } : {}),
+            });
+        }
+    }
+    const failed = issues.some((issue) => issue.severity === "error");
+    return { status: failed ? "fail" : "pass", issues };
+};

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

@@ -0,0 +1,6 @@
+import type { CheckResult } from "./types.ts";
+export interface ModdleOutcome {
+    result: CheckResult;
+    rootElement?: unknown;
+}
+export declare const checkModdle: (xml: string) => Promise<ModdleOutcome>;

package/dist/check-xml/moddle.js

@@ -0,0 +1,23 @@
+import { BpmnModdle } from "bpmn-moddle";
+const issueFrom = (message) => {
+    const [first, ...details] = message.split("\n").map((line) => line.trim());
+    const detail = (key) => details.find((line) => line.startsWith(`${key}:`))?.slice(key.length + 1).trim();
+    const nested = detail("nested error");
+    const line = detail("line");
+    const column = detail("column");
+    return {
+        severity: "error",
+        message: nested ? `${first}: ${nested}` : first,
+        ...(line !== undefined && column !== undefined ? { location: `line ${Number(line) + 1}, column ${column}` } : {}),
+    };
+};
+export const checkModdle = async (xml) => {
+    try {
+        const { rootElement, warnings } = await new BpmnModdle().fromXML(xml);
+        const issues = warnings.map((warning) => issueFrom(warning.message));
+        return { result: { status: issues.length ? "fail" : "pass", issues }, rootElement };
+    }
+    catch (error) {
+        return { result: { status: "fail", issues: [issueFrom(error.message)] } };
+    }
+};

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

@@ -0,0 +1,20 @@
+export type Severity = "error" | "warning";
+export interface CheckIssue {
+    severity: Severity;
+    message: string;
+    location?: string;
+    rule?: string;
+}
+export type CheckStatus = "pass" | "fail" | "skipped";
+export interface CheckResult {
+    status: CheckStatus;
+    issues: CheckIssue[];
+}
+export interface CheckReport {
+    ok: boolean;
+    checks: {
+        xsd: CheckResult;
+        moddle: CheckResult;
+        lint: CheckResult;
+    };
+}

package/dist/check-xml/types.js

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

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

@@ -0,0 +1,2 @@
+import type { CheckResult } from "./types.ts";
+export declare const checkXsd: (xml: string) => Promise<CheckResult>;

package/dist/check-xml/xsd.js

@@ -0,0 +1,25 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { validateXML } from "xmllint-wasm";
+import { ROOT } from "../paths.js";
+const XSD_DIR = join(ROOT, "reference/bpmn-xsd");
+const ROOT_SCHEMA = "BPMN20.xsd";
+const IMPORTED_SCHEMAS = ["Semantic.xsd", "BPMNDI.xsd", "DI.xsd", "DC.xsd"];
+const load = (fileName) => ({ fileName, contents: readFileSync(join(XSD_DIR, fileName), "utf8") });
+const schema = load(ROOT_SCHEMA);
+const preload = IMPORTED_SCHEMAS.map(load);
+export const checkXsd = async (xml) => {
+    const result = await validateXML({
+        xml: { fileName: "input.bpmn", contents: xml },
+        schema: [schema],
+        preload,
+    });
+    if (result.valid)
+        return { status: "pass", issues: [] };
+    const issues = result.errors.map((error) => ({
+        severity: "error",
+        message: error.message,
+        ...(error.loc ? { location: `line ${error.loc.lineNumber}` } : {}),
+    }));
+    return { status: "fail", issues };
+};

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

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

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