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

package/dist/render.d.ts

@@ -0,0 +1,4 @@
+export * from "./render/renderer.ts";
+export * from "./render/geometry.ts";
+export * from "./render/text.ts";
+export * from "./render/symbols.ts";

package/dist/render.js

@@ -0,0 +1,4 @@
+export * from "./render/renderer.js";
+export * from "./render/geometry.js";
+export * from "./render/text.js";
+export * from "./render/symbols.js";

package/dist/schema-overrides.d.ts

@@ -0,0 +1,14 @@
+export type Schema = Record<string, any>;
+export interface OverrideContext {
+    schema: Schema;
+    classesUnder: (term: string) => string[];
+}
+export interface SchemaOverride {
+    name: string;
+    apply: (context: OverrideContext) => void;
+}
+export declare const requireIdOnFlowElements: SchemaOverride;
+export declare const waypointsNeedTwoPoints: SchemaOverride;
+export declare const requireTopLevelContext: SchemaOverride;
+export declare const diagramElementsReferenceTheirElement: SchemaOverride;
+export declare const schemaOverrides: SchemaOverride[];

package/dist/schema-overrides.js

@@ -0,0 +1,36 @@
+const addRequired = (target, ...names) => {
+    target.required = [...new Set([...(target.required ?? []), ...names])];
+};
+export const requireIdOnFlowElements = {
+    name: "require-id-on-flow-elements",
+    apply: ({ schema, classesUnder }) => {
+        for (const term of classesUnder("FlowElement"))
+            addRequired(schema.$defs[term], "id");
+    },
+};
+export const waypointsNeedTwoPoints = {
+    name: "waypoints-need-two-points",
+    apply: ({ schema }) => {
+        schema.$defs.BPMNEdge.properties.waypoints.minItems = 2;
+    },
+};
+export const requireTopLevelContext = {
+    name: "require-top-level-context",
+    apply: ({ schema }) => {
+        addRequired(schema.$defs.topLevelNode, "@context");
+        addRequired(schema.$defs.graphDocument, "@context");
+    },
+};
+export const diagramElementsReferenceTheirElement = {
+    name: "diagram-elements-reference-their-element",
+    apply: ({ schema }) => {
+        for (const term of ["BPMNShape", "BPMNEdge"])
+            addRequired(schema.$defs[term], "bpmnElement");
+    },
+};
+export const schemaOverrides = [
+    requireIdOnFlowElements,
+    waypointsNeedTwoPoints,
+    requireTopLevelContext,
+    diagramElementsReferenceTheirElement,
+];

package/dist/schema-validate.d.ts

@@ -0,0 +1,5 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import type { Schema } from "./schema-overrides.ts";
+export declare const loadSchema: () => Schema;
+export declare const compileSchema: (schema?: Schema) => Ajv2020.ValidateFunction<unknown>;
+export declare const validateWithSchema: (document: unknown, validate?: Ajv2020.ValidateFunction<unknown>) => string[];

package/dist/schema-validate.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import Ajv2020 from "ajv/dist/2020.js";
+import { ROOT } from "./paths.js";
+import { SCHEMA_PATH } from "./build.js";
+export const loadSchema = () => JSON.parse(readFileSync(join(ROOT, SCHEMA_PATH), "utf8"));
+export const compileSchema = (schema = loadSchema()) => new Ajv2020.default({ allErrors: false, logger: false }).compile(schema);
+export const validateWithSchema = (document, validate = compileSchema()) => validate(document) ? [] : (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message}`);

package/dist/schema.d.ts

@@ -0,0 +1,6 @@
+import type { Schema, SchemaOverride } from "./schema-overrides.ts";
+export interface GenerateOptions {
+    overrides?: SchemaOverride[];
+}
+export declare const generateSchema: ({ overrides }?: GenerateOptions) => Schema;
+export declare const renderSchema: (options?: GenerateOptions) => string;

package/dist/schema.js

@@ -0,0 +1,114 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ROOT } from "./paths.js";
+import { BPMN_NAMESPACE } from "./namespace.js";
+import { declaredClasses, declaredIndividuals, domainAlternatives, isSubClassOf, loadOntology, rangeAlternatives, typesOf, } from "./ontology.js";
+import { schemaOverrides } from "./schema-overrides.js";
+const CONTEXT_FILES = ["contexts/core.jsonld", "contexts/di.jsonld"];
+const XSD = "http://www.w3.org/2001/XMLSchema#";
+const KEYWORD_TERMS = new Set(["id", "type"]);
+const loadContextTerms = () => Object.assign({}, ...CONTEXT_FILES.map((file) => JSON.parse(readFileSync(join(ROOT, file), "utf8"))["@context"]));
+const readContext = (store) => {
+    const terms = loadContextTerms();
+    const prefixes = new Map(Object.entries(terms).filter(([key, value]) => !key.startsWith("@") && typeof value === "string" && value.endsWith("#")));
+    const expand = (value) => {
+        const [prefix, local] = value.split(":");
+        return prefixes.has(prefix) ? prefixes.get(prefix) + local : undefined;
+    };
+    const classes = declaredClasses(store);
+    const individuals = declaredIndividuals(store);
+    const model = { classTerms: new Map(), individualTerms: new Map(), properties: [] };
+    for (const [term, definition] of Object.entries(terms)) {
+        if (term.startsWith("@") || prefixes.has(term) || KEYWORD_TERMS.has(term))
+            continue;
+        const spec = typeof definition === "string" ? { "@id": definition } : definition;
+        const iri = expand(spec["@id"]);
+        if (!iri)
+            continue;
+        if (classes.has(iri))
+            model.classTerms.set(iri, term);
+        else if (individuals.has(iri))
+            model.individualTerms.set(iri, term);
+        else
+            model.properties.push({ term, iri, coerce: spec["@type"], container: spec["@container"] });
+    }
+    return model;
+};
+const ref = (name) => ({ $ref: `#/$defs/${name}` });
+const idReference = {
+    anyOf: [
+        { type: "string" },
+        { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
+    ],
+};
+const datatypeSchema = (datatype) => {
+    const local = datatype.slice(XSD.length);
+    if (local === "boolean")
+        return { type: "boolean" };
+    if (local === "string")
+        return { type: "string" };
+    if (local === "integer")
+        return { type: "integer" };
+    if (local === "nonNegativeInteger")
+        return { type: "integer", minimum: 0 };
+    return { type: "number" };
+};
+export const generateSchema = ({ overrides = schemaOverrides } = {}) => {
+    const store = loadOntology();
+    const model = readContext(store);
+    const concrete = [...model.classTerms.entries()];
+    const subclassTerms = (ancestor) => concrete.filter(([cls]) => isSubClassOf(store, cls, ancestor)).map(([, term]) => term);
+    const valueSchema = (property) => {
+        const [alternatives = []] = rangeAlternatives(store, property.iri);
+        const [range] = alternatives;
+        if (property.coerce === "@id")
+            return idReference;
+        if (property.coerce === "@vocab") {
+            const values = [...model.individualTerms].filter(([individual]) => typesOf(store, individual).includes(range)).map(([, term]) => term);
+            return { enum: values };
+        }
+        if (range.startsWith(XSD))
+            return datatypeSchema(range);
+        return { anyOf: [...new Set(alternatives.flatMap(subclassTerms))].map(ref) };
+    };
+    const propertySchema = (property) => {
+        const value = valueSchema(property);
+        const many = { type: "array", items: value };
+        return property.container === "@set" || property.container === "@list" ? many : { anyOf: [value, many] };
+    };
+    const appliesTo = (property, cls) => domainAlternatives(store, property.iri).every((group) => group.some((domain) => isSubClassOf(store, cls, domain)));
+    const defs = {};
+    for (const [cls, term] of concrete) {
+        const own = model.properties.filter((property) => appliesTo(property, cls));
+        const foreign = model.properties.filter((property) => !own.includes(property)).map((property) => property.term);
+        defs[term] = {
+            type: "object",
+            properties: {
+                id: { type: "string" },
+                type: { const: term },
+                ...Object.fromEntries(own.map((property) => [property.term, propertySchema(property)])),
+            },
+            required: ["type"],
+            propertyNames: { not: { enum: foreign } },
+        };
+    }
+    defs.node = { anyOf: concrete.map(([, term]) => ref(term)) };
+    defs.topLevelNode = { allOf: [ref("node")] };
+    defs.graphDocument = {
+        type: "object",
+        properties: { "@graph": { type: "array", items: ref("node") } },
+        required: ["@graph"],
+    };
+    defs.document = { anyOf: [ref("graphDocument"), ref("topLevelNode")] };
+    const schema = {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        title: "BPMN-LD document",
+        anyOf: [ref("document"), { type: "array", items: ref("document") }],
+        $defs: defs,
+    };
+    const classesUnder = (name) => subclassTerms(`${BPMN_NAMESPACE}${name}`);
+    for (const override of overrides)
+        override.apply({ schema, classesUnder });
+    return schema;
+};
+export const renderSchema = (options) => `${JSON.stringify(generateSchema(options), null, 2)}\n`;

package/dist/shacl.d.ts

@@ -0,0 +1,15 @@
+export declare const SHAPES_FILES: string[];
+export interface Violation {
+    sourceShape: string;
+    focusNode: string;
+}
+export interface ExpectedViolations {
+    violations: Violation[];
+}
+export interface ShaclResult {
+    conforms: boolean;
+    violations: Violation[];
+}
+export declare const resolveShape: (name: string) => string;
+export declare const validateShacl: (file: string) => Promise<ShaclResult>;
+export declare const sameViolations: (actual: Violation[], expected: Violation[]) => boolean;

package/dist/shacl.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Parser, Store } from "n3";
+import jsonld from "jsonld";
+import rdf from "@rdfjs/dataset";
+import SHACLValidator from "rdf-validate-shacl";
+import { ROOT } from "./paths.js";
+import { BPMN_SHAPES_NAMESPACE } from "./namespace.js";
+import { fileDocumentLoader } from "./loader.js";
+import { loadOntology, RDFS_SUBCLASS_OF } from "./ontology.js";
+export const SHAPES_FILES = ["shapes/core.shapes.ttl"];
+const loadShapes = () => rdf.dataset(new Parser().parse(SHAPES_FILES.map((file) => readFileSync(join(ROOT, file), "utf8")).join("\n")));
+export const resolveShape = (name) => (name.includes(":") ? name : `${BPMN_SHAPES_NAMESPACE}${name}`);
+export const validateShacl = async (file) => {
+    const nquads = (await jsonld.toRDF(JSON.parse(readFileSync(file, "utf8")), {
+        base: pathToFileURL(file).href,
+        documentLoader: fileDocumentLoader,
+        format: "application/n-quads",
+        safe: true,
+    }));
+    const data = rdf.dataset(new Parser().parse(nquads));
+    for (const quad of loadOntology().getQuads(null, RDFS_SUBCLASS_OF, null, null))
+        data.add(quad);
+    const report = await new SHACLValidator(loadShapes()).validate(data);
+    const violations = report.results.map((result) => ({
+        sourceShape: result.sourceShape?.value ?? "",
+        focusNode: result.focusNode?.value ?? "",
+    }));
+    return { conforms: report.conforms, violations };
+};
+export const sameViolations = (actual, expected) => {
+    const key = (v) => `${v.sourceShape} ${v.focusNode}`;
+    const a = actual.map(key).sort();
+    const e = expected.map((v) => key({ ...v, sourceShape: resolveShape(v.sourceShape) })).sort();
+    return a.length === e.length && a.every((value, i) => value === e[i]);
+};

package/dist/validate-cli.d.ts

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

package/dist/validate-cli.js

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

package/dist/validate-run.d.ts

@@ -0,0 +1,8 @@
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export interface CliResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export declare const runValidate: (argv: string[]) => Promise<CliResult>;

package/dist/validate-run.js

@@ -0,0 +1,58 @@
+import { relative } from "node:path";
+import { ROOT } from "./paths.js";
+import { existsSync, readFileSync } from "node:fs";
+import { findExamples, validateExample } from "./validate.js";
+import { sameViolations, validateShacl } from "./shacl.js";
+import { compileSchema, validateWithSchema } from "./schema-validate.js";
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+const lines = [];
+const log = (line) => lines.push(line);
+export const runValidate = async (argv) => {
+    lines.length = 0;
+    const examplesDir = argv.find((arg) => !arg.startsWith("-")) ?? `${ROOT}examples`;
+    const validateSchema = compileSchema();
+    const schemaErrors = (file) => validateWithSchema(JSON.parse(readFileSync(file, "utf8")), validateSchema);
+    const examplesIn = (kind) => (existsSync(`${examplesDir}/${kind}`) ? findExamples(`${examplesDir}/${kind}`) : []);
+    let failed = 0;
+    const report = (label, errors) => {
+        if (errors.length === 0)
+            log(`ok   ${label}`);
+        else {
+            failed++;
+            log(`FAIL ${label}`);
+            errors.forEach((e) => log(`     ${e}`));
+        }
+    };
+    for (const file of [...examplesIn("positive"), ...examplesIn("miwg")]) {
+        const structural = await validateExample(file);
+        const errors = [...structural.errors, ...schemaErrors(file).map((e) => `schema: ${e}`)];
+        if (structural.valid) {
+            const shacl = await validateShacl(file);
+            shacl.violations.forEach((v) => errors.push(`${v.focusNode} violates ${v.sourceShape}`));
+            if (!shacl.conforms && shacl.violations.length === 0)
+                errors.push("SHACL validation failed");
+        }
+        report(relative(examplesDir, file), errors);
+    }
+    for (const file of examplesIn("negative")) {
+        const errors = [];
+        const structural = await validateExample(file);
+        errors.push(...structural.errors, ...schemaErrors(file).map((e) => `schema: ${e}`));
+        if (structural.valid) {
+            const expected = JSON.parse(readFileSync(file.replace(/\.jsonld$/, ".expect.json"), "utf8"));
+            const shacl = await validateShacl(file);
+            if (shacl.conforms)
+                errors.push("expected SHACL violations but the example conforms");
+            else if (!sameViolations(shacl.violations, expected.violations)) {
+                errors.push(`violations differ from the stated intent`);
+                shacl.violations.forEach((v) => errors.push(`actual: ${v.focusNode} violates ${v.sourceShape}`));
+            }
+        }
+        report(relative(examplesDir, file), errors);
+    }
+    for (const file of examplesIn("schema-negative")) {
+        report(relative(examplesDir, file), schemaErrors(file).length > 0 ? [] : ["expected the schema to reject the example but it was accepted"]);
+    }
+    return { exitCode: failed ? EXIT_FAILED : EXIT_OK, stdout: `${lines.join("\n")}\n`, stderr: "" };
+};

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export type Node = Record<string, unknown>;
+export interface DocumentValidation extends ValidationResult {
+    expanded: Node[];
+}
+export declare const validateDocument: (document: unknown, base: string) => Promise<DocumentValidation>;
+export declare const validateExample: (file: string) => Promise<ValidationResult>;
+export declare const findExamples: (dir: string) => string[];

package/dist/validate.js

@@ -0,0 +1,94 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import jsonld from "jsonld";
+import { domainAlternatives, rangeAlternatives, declaredClasses, declaredTerms, isOwnedIri, isSubClassOf, loadOntology, typesOf, } from "./ontology.js";
+import { fileDocumentLoader } from "./loader.js";
+const members = (value) => value.flatMap((v) => ("@list" in v ? v["@list"] : [v]));
+const nodesIn = (value) => members(value).filter((v) => !("@value" in v));
+const collectIris = (node, found) => {
+    for (const [key, value] of Object.entries(node)) {
+        if (key === "@type")
+            value.forEach((t) => found.add(t));
+        else if (!key.startsWith("@")) {
+            found.add(key);
+            nodesIn(value).forEach((v) => collectIris(v, found));
+        }
+    }
+};
+const indexTypes = (node, types) => {
+    const id = node["@id"];
+    if (id && node["@type"]) {
+        const known = types.get(id) ?? new Set();
+        node["@type"].forEach((t) => known.add(t));
+        types.set(id, known);
+    }
+    for (const [key, value] of Object.entries(node)) {
+        if (!key.startsWith("@"))
+            nodesIn(value).forEach((v) => indexTypes(v, types));
+    }
+};
+const checkDomainRange = (store, node, types, errors) => {
+    const classes = declaredClasses(store);
+    const subject = node["@id"] ?? "_:blank";
+    const subjectTypes = [...(node["@type"] ?? types.get(subject) ?? [])];
+    const conforms = (nodeTypes, required) => nodeTypes.some((t) => classes.has(t) && isSubClassOf(store, t, required));
+    for (const [key, value] of Object.entries(node)) {
+        if (key.startsWith("@"))
+            continue;
+        for (const alternatives of domainAlternatives(store, key)) {
+            if (!alternatives.some((domain) => conforms(subjectTypes, domain))) {
+                errors.push(`${subject} uses ${key} but is not typed as ${alternatives.join(" or ")}, which is the domain of ${key}`);
+            }
+        }
+        for (const range of rangeAlternatives(store, key).filter((alternatives) => alternatives.every((r) => classes.has(r)))) {
+            for (const object of members(value)) {
+                const objectId = object["@id"];
+                const objectTypes = [
+                    ...(object["@type"] ?? (objectId && types.get(objectId)) ?? (objectId ? typesOf(store, objectId) : [])),
+                ];
+                if (!range.some((alternative) => conforms(objectTypes, alternative))) {
+                    const shown = objectTypes.length ? objectTypes.join(", ") : "untyped";
+                    errors.push(`${subject} ${key} ${objectId ?? "_:blank"} has type ${shown}, which is not a ${range.join(" or ")}, the range of ${key}`);
+                }
+            }
+        }
+        nodesIn(value).forEach((v) => checkDomainRange(store, v, types, errors));
+    }
+};
+export const validateDocument = async (document, base) => {
+    const errors = [];
+    let expanded;
+    try {
+        expanded = await jsonld.expand(document, { base, documentLoader: fileDocumentLoader, safe: true });
+    }
+    catch (error) {
+        return { valid: false, errors: [error instanceof Error ? error.message : String(error)], expanded: [] };
+    }
+    const store = loadOntology();
+    const declared = declaredTerms(store);
+    const used = new Set();
+    expanded.forEach((node) => collectIris(node, used));
+    for (const iri of used) {
+        if (isOwnedIri(iri) && !declared.has(iri))
+            errors.push(`${iri} is not declared in the ontology`);
+    }
+    const types = new Map();
+    expanded.forEach((node) => indexTypes(node, types));
+    expanded.forEach((node) => checkDomainRange(store, node, types, errors));
+    if (expanded.length === 0)
+        errors.push("document expands to no nodes");
+    return { valid: errors.length === 0, errors, expanded };
+};
+export const validateExample = async (file) => {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return { valid: false, errors: [error instanceof Error ? error.message : String(error)] };
+    }
+    const { valid, errors } = await validateDocument(document, pathToFileURL(file).href);
+    return { valid, errors };
+};
+export const findExamples = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? findExamples(join(dir, entry.name)) : entry.name.endsWith(".jsonld") ? [join(dir, entry.name)] : []);

package/dist/versioning-cli.d.ts

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

package/dist/versioning-cli.js

@@ -0,0 +1,18 @@
+import { latestPointsTo, planPublication } from "./versioning.js";
+const args = process.argv.slice(2);
+const published = args
+    .filter((arg) => arg.startsWith("--published="))
+    .flatMap((arg) => arg.slice("--published=".length).split(",").filter(Boolean));
+const [version] = args.filter((arg) => !arg.startsWith("--"));
+if (!version) {
+    console.error("usage: npm run publish-layout -- <version> [--published=1.0.0,1.1.0]");
+    process.exit(2);
+}
+try {
+    const plan = planPublication(version, published);
+    console.log(JSON.stringify({ ...plan, updatesLatest: latestPointsTo(published, plan.version) }, null, 2));
+}
+catch (error) {
+    console.error(error.message);
+    process.exit(1);
+}

package/dist/versioning.d.ts

@@ -0,0 +1,17 @@
+export declare const PUBLISH_BASE: string;
+export declare const PUBLISHED_ARTIFACTS: readonly ["ontology/core.ttl", "ontology/di.ttl", "contexts/core.jsonld", "contexts/di.jsonld", "contexts/combined.jsonld", "shapes/core.shapes.ttl"];
+export interface PublishedFile {
+    source: string;
+    versioned: string;
+    latest: string;
+}
+export interface PublicationPlan {
+    version: string;
+    tag: string;
+    files: PublishedFile[];
+}
+export declare const normalizeVersion: (input: string) => string;
+export declare const compareVersions: (a: string, b: string) => number;
+export declare const latestVersion: (versions: string[]) => string | undefined;
+export declare const planPublication: (input: string, publishedVersions?: string[], artifacts?: readonly string[]) => PublicationPlan;
+export declare const latestPointsTo: (publishedVersions: string[], candidate: string) => boolean;

package/dist/versioning.js

@@ -0,0 +1,45 @@
+import { BPMN_NAMESPACE } from "./namespace.js";
+export const PUBLISH_BASE = new URL(BPMN_NAMESPACE).origin;
+export const PUBLISHED_ARTIFACTS = [
+    "ontology/core.ttl",
+    "ontology/di.ttl",
+    "contexts/core.jsonld",
+    "contexts/di.jsonld",
+    "contexts/combined.jsonld",
+    "shapes/core.shapes.ttl",
+];
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+export const normalizeVersion = (input) => {
+    const version = input.startsWith("v") ? input.slice(1) : input;
+    if (!SEMVER.test(version))
+        throw new Error(`invalid semantic version: ${input}`);
+    return version;
+};
+export const compareVersions = (a, b) => {
+    const left = normalizeVersion(a).split(".").map(Number);
+    const right = normalizeVersion(b).split(".").map(Number);
+    for (let i = 0; i < 3; i++)
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    return 0;
+};
+export const latestVersion = (versions) => versions.length === 0 ? undefined : versions.map(normalizeVersion).sort(compareVersions).at(-1);
+export const planPublication = (input, publishedVersions = [], artifacts = PUBLISHED_ARTIFACTS) => {
+    const version = normalizeVersion(input);
+    if (publishedVersions.some((published) => normalizeVersion(published) === version)) {
+        throw new Error(`version ${version} is already published and immutable`);
+    }
+    return {
+        version,
+        tag: `v${version}`,
+        files: artifacts.map((source) => ({
+            source,
+            versioned: `${PUBLISH_BASE}/v${version}/${source}`,
+            latest: `${PUBLISH_BASE}/latest/${source}`,
+        })),
+    };
+};
+export const latestPointsTo = (publishedVersions, candidate) => {
+    const newest = latestVersion([...publishedVersions, candidate]);
+    return newest === normalizeVersion(candidate);
+};