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

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;

package/dist/coverage.js

@@ -0,0 +1,152 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { BPMN_NAMESPACE, BPMNDI_NAMESPACE } from "./namespace.js";
+import { declaredClasses, declaredProperties, domainAlternatives, loadOntology, superClasses } from "./ontology.js";
+import { loadXsdTypes } from "./coverage-xsd.js";
+import { REAL_SCOPE } from "./coverage-scope.js";
+import { BUILT_IN_PROPERTIES, CLASS_ALIASES, PROPERTY_ALIASES } from "./coverage-mappings.js";
+const PREFIXES = [
+    [BPMN_NAMESPACE, "bpmn:"],
+    [BPMNDI_NAMESPACE, "bpmndi:"],
+];
+const compact = (iri) => {
+    for (const [namespace, prefix] of PREFIXES)
+        if (iri.startsWith(namespace))
+            return prefix + iri.slice(namespace.length);
+    return iri;
+};
+const semantic = (type) => type.file === "Semantic.xsd";
+const stripPrefix = (name) => name.replace(/^t(?=[A-Z])/, "");
+const idName = (type) => (semantic(type) ? stripPrefix(type.name) : type.name);
+const localClassName = (type) => CLASS_ALIASES[type.name] ?? idName(type);
+const namespaceOf = (type) => (semantic(type) ? BPMN_NAMESPACE : BPMNDI_NAMESPACE);
+const groupOf = (groups, name) => Object.entries(groups).find(([, members]) => members.includes(name))?.[0];
+const emptyCounts = () => ({ covered: 0, gap: 0, "out-of-scope": 0 });
+const propertyCovered = (store, classIri, property) => {
+    const ancestors = new Set([classIri, ...superClasses(store, classIri)]);
+    const statements = domainAlternatives(store, property);
+    return statements.length === 0 || statements.some((alternatives) => alternatives.some((c) => ancestors.has(c)));
+};
+const reasonOf = (scope, group) => {
+    const reason = scope.outOfScopeReasons?.[group];
+    return reason ? { reason } : {};
+};
+export const checkCoverage = (store, types, scope) => {
+    const classes = declaredClasses(store);
+    const properties = declaredProperties(store);
+    const items = [];
+    const unclassified = [];
+    for (const type of types) {
+        const local = idName(type);
+        const classIri = namespaceOf(type) + localClassName(type);
+        const xsd = `${type.file}#${type.name}`;
+        if (!scope.inScope.includes(type.name)) {
+            const group = groupOf(scope.outOfScopeTypes, type.name);
+            if (group)
+                items.push({ id: local, kind: "class", xsd, ontology: null, status: "out-of-scope", group, ...reasonOf(scope, group) });
+            else
+                unclassified.push(xsd);
+            continue;
+        }
+        const covered = classes.has(classIri);
+        items.push({ id: local, kind: "class", xsd, ontology: compact(classIri), status: covered ? "covered" : "gap" });
+        for (const member of type.members) {
+            const memberXsd = `${xsd}/${member.kind === "attribute" ? "@" : ""}${member.name}`;
+            const id = `${local}.${member.name}`;
+            const builtIn = BUILT_IN_PROPERTIES[member.name];
+            if (builtIn) {
+                items.push({ id, kind: "property", xsd: memberXsd, ontology: builtIn, status: "covered" });
+                continue;
+            }
+            const alias = PROPERTY_ALIASES[`${local}.${member.name}`] ?? PROPERTY_ALIASES[member.name] ?? member.name;
+            const candidates = [BPMN_NAMESPACE + alias, BPMNDI_NAMESPACE + alias].filter((iri) => properties.has(iri));
+            const hit = candidates.find((iri) => propertyCovered(store, classIri, iri));
+            if (hit) {
+                items.push({ id, kind: "property", xsd: memberXsd, ontology: compact(hit), status: "covered" });
+                continue;
+            }
+            const group = groupOf(scope.outOfScopeProperties, member.name);
+            if (group)
+                items.push({ id, kind: "property", xsd: memberXsd, ontology: null, status: "out-of-scope", group, ...reasonOf(scope, group) });
+            else
+                items.push({ id, kind: "property", xsd: memberXsd, ontology: null, status: "gap" });
+        }
+    }
+    items.sort((a, b) => (a.kind === b.kind ? a.id.localeCompare(b.id) : a.kind === "class" ? -1 : 1));
+    unclassified.sort();
+    const summary = { classes: emptyCounts(), properties: emptyCounts(), total: emptyCounts() };
+    for (const item of items) {
+        summary[item.kind === "class" ? "classes" : "properties"][item.status]++;
+        summary.total[item.status]++;
+    }
+    return { summary, unclassified, items };
+};
+const table = (rows, columns, cell) => rows.length
+    ? [
+        `| ${columns.join(" | ")} |`,
+        `| ${columns.map(() => "---").join(" | ")} |`,
+        ...rows.map((item) => `| ${cell(item).join(" | ")} |`),
+    ].join("\n")
+    : "_None._";
+export const renderMarkdown = (report) => {
+    const { summary, items } = report;
+    const inScope = items.filter((i) => i.status !== "out-of-scope");
+    const gaps = items.filter((i) => i.status === "gap");
+    const covered = items.filter((i) => i.status === "covered");
+    const out = items.filter((i) => i.status === "out-of-scope");
+    const groups = [...new Set(out.map((i) => i.group))].sort();
+    const lines = [
+        "# BPMN coverage report",
+        "",
+        "Generated by `npm run coverage` from the normative BPMN 2.0.2 XSDs in `reference/bpmn-xsd/` and the ontology in `ontology/`. Do not edit by hand.",
+        "",
+        "## Summary",
+        "",
+        "| Kind | Covered | Gaps | Out of scope |",
+        "| --- | ---: | ---: | ---: |",
+        ...["classes", "properties", "total"].map((k) => `| ${k} | ${summary[k].covered} | ${summary[k].gap} | ${summary[k]["out-of-scope"]} |`),
+        "",
+        `In scope: ${inScope.length} items, ${summary.total.covered} covered and ${summary.total.gap} gaps.`,
+        "",
+        `## Gaps (${gaps.length})`,
+        "",
+        table(gaps, ["Kind", "Item", "XSD"], (i) => [i.kind, `\`${i.id}\``, `\`${i.xsd}\``]),
+        "",
+        `## Covered (${covered.length})`,
+        "",
+        table(covered, ["Kind", "Item", "XSD", "Ontology"], (i) => [i.kind, `\`${i.id}\``, `\`${i.xsd}\``, `\`${i.ontology}\``]),
+        "",
+        `## Out of scope (${out.length})`,
+        "",
+        ...groups.flatMap((group) => {
+            const members = out.filter((i) => i.group === group);
+            const reason = members.find((i) => i.reason)?.reason;
+            return [
+                `### ${group} (${members.length})`,
+                "",
+                ...(reason ? [reason, ""] : []),
+                members.map((i) => `\`${i.kind === "class" ? i.xsd : i.id}\``).join(", "),
+                "",
+            ];
+        }),
+    ];
+    if (report.unclassified.length) {
+        lines.push(`## Unclassified (${report.unclassified.length})`, "", report.unclassified.map((u) => `\`${u}\``).join(", "), "");
+    }
+    return lines.join("\n").replace(/\n+$/, "\n");
+};
+export const renderJson = (report) => `${JSON.stringify(report, null, 2)}\n`;
+export const generateReports = (root) => {
+    const report = checkCoverage(loadOntology(), loadXsdTypes(root), REAL_SCOPE);
+    return { report, markdown: renderMarkdown(report), json: renderJson(report) };
+};
+export const REPORT_MARKDOWN = "reports/coverage.md";
+export const REPORT_JSON = "reports/coverage.json";
+export const writeReports = (root) => {
+    const { report, markdown, json } = generateReports(root);
+    mkdirSync(join(root, "reports"), { recursive: true });
+    writeFileSync(join(root, REPORT_MARKDOWN), markdown);
+    writeFileSync(join(root, REPORT_JSON), json);
+    return report;
+};
+export const readReport = (root, file) => readFileSync(join(root, file), "utf8");

package/dist/docs-cli.d.ts

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

package/dist/docs-cli.js

@@ -0,0 +1,18 @@
+import { checkVocabulary, writeVocabulary } from "./docs.js";
+const args = process.argv.slice(2);
+const check = args.includes("--check");
+const path = args.find((arg) => !arg.startsWith("--"));
+if (check) {
+    const result = checkVocabulary(path);
+    if (result.ok) {
+        console.log(result.message);
+    }
+    else {
+        console.error(result.message);
+        process.exitCode = 1;
+    }
+}
+else {
+    writeVocabulary(path);
+    console.log(`wrote ${path ?? "docs/reference/vocabulary.md"}`);
+}

package/dist/docs.d.ts

@@ -0,0 +1,8 @@
+import type { Store } from "n3";
+export declare const VOCABULARY_PATH = "docs/reference/vocabulary.md";
+export declare const renderVocabulary: (store?: Store) => string;
+export declare const writeVocabulary: (path?: string, store?: Store) => void;
+export declare const checkVocabulary: (path?: string, store?: Store) => {
+    ok: boolean;
+    message: string;
+};

package/dist/docs.js

@@ -0,0 +1,136 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { BPMN_NAMESPACE, BPMNDI_NAMESPACE } from "./namespace.js";
+import { ROOT } from "./paths.js";
+import { rangeAlternatives, declaredClasses, declaredIndividuals, declaredProperties, domainAlternatives, isSubClassOf, loadOntology, typesOf, } from "./ontology.js";
+export const VOCABULARY_PATH = "docs/reference/vocabulary.md";
+const RDFS = "http://www.w3.org/2000/01/rdf-schema#";
+const OWL_OBJECT_PROPERTY = "http://www.w3.org/2002/07/owl#ObjectProperty";
+const XSD = "http://www.w3.org/2001/XMLSchema#";
+const MODULES = [
+    { title: "Core", prefix: "bpmn", namespace: BPMN_NAMESPACE },
+    { title: "Diagram interchange", prefix: "bpmndi", namespace: BPMNDI_NAMESPACE },
+];
+const compact = (iri) => {
+    const module = MODULES.find((m) => iri.startsWith(m.namespace));
+    if (module)
+        return `${module.prefix}:${iri.slice(module.namespace.length)}`;
+    return iri.startsWith(XSD) ? `xsd:${iri.slice(XSD.length)}` : iri;
+};
+const byCompact = (a, b) => compact(a).localeCompare(compact(b));
+const cell = (text) => text.replace(/\|/g, "\\|").replace(/\s+/g, " ").trim();
+const comment = (store, iri) => store.getObjects(iri, `${RDFS}comment`, null).map((o) => o.value).sort().join(" ") || "No definition.";
+const code = (iri) => `\`${compact(iri)}\``;
+const list = (iris) => (iris.length ? [...iris].sort(byCompact).map(code).join(", ") : "none");
+const directSuperClasses = (store, cls) => store.getObjects(cls, `${RDFS}subClassOf`, null).filter((o) => o.termType === "NamedNode").map((o) => o.value);
+const ancestorsOf = (store, cls) => {
+    const result = new Set();
+    const walk = (current) => {
+        for (const parent of directSuperClasses(store, current)) {
+            if (!result.has(parent)) {
+                result.add(parent);
+                walk(parent);
+            }
+        }
+    };
+    walk(cls);
+    return [...result];
+};
+const domainText = (store, property) => {
+    const alternatives = domainAlternatives(store, property);
+    return alternatives.length
+        ? alternatives.map((members) => [...members].sort(byCompact).map(code).join(" or ")).join("; and ")
+        : "unspecified";
+};
+const rangeText = (store, property) => {
+    const ranges = rangeAlternatives(store, property);
+    return ranges.length ? ranges.map((members) => [...members].sort(byCompact).map(code).join(" or ")).sort().join(", ") : "unspecified";
+};
+const appliesTo = (store, property, cls) => domainAlternatives(store, property).some((members) => members.some((member) => isSubClassOf(store, cls, member)));
+const renderClass = (store, cls, properties) => {
+    const subClasses = [...declaredClasses(store)].filter((c) => directSuperClasses(store, c).includes(cls));
+    const applicable = properties.filter((p) => appliesTo(store, p, cls));
+    const lines = [
+        `#### ${code(cls)}`,
+        "",
+        comment(store, cls),
+        "",
+        `- Superclasses: ${list(directSuperClasses(store, cls))}`,
+        `- All ancestors: ${list(ancestorsOf(store, cls))}`,
+        `- Subclasses: ${list(subClasses)}`,
+        "",
+    ];
+    if (applicable.length) {
+        lines.push("| Property | Range | Definition |", "| --- | --- | --- |");
+        for (const property of applicable) {
+            lines.push(`| ${code(property)} | ${rangeText(store, property)} | ${cell(comment(store, property))} |`);
+        }
+        lines.push("");
+    }
+    else {
+        lines.push("No properties apply.", "");
+    }
+    return lines;
+};
+const renderProperty = (store, property) => {
+    const kind = typesOf(store, property).includes(OWL_OBJECT_PROPERTY) ? "object" : "datatype";
+    return [
+        `#### ${code(property)}`,
+        "",
+        comment(store, property),
+        "",
+        `- Kind: ${kind}`,
+        `- Domain: ${domainText(store, property)}`,
+        `- Range: ${rangeText(store, property)}`,
+        "",
+    ];
+};
+const renderIndividual = (store, individual) => {
+    const classes = typesOf(store, individual).filter((t) => declaredClasses(store).has(t));
+    return [`#### ${code(individual)}`, "", comment(store, individual), "", `- Type: ${list(classes)}`, ""];
+};
+export const renderVocabulary = (store = loadOntology()) => {
+    const classes = declaredClasses(store);
+    const properties = declaredProperties(store);
+    const individuals = declaredIndividuals(store);
+    const lines = [
+        "# Vocabulary reference",
+        "",
+        "Generated from the ontology by `npm run docs`. Do not edit by hand.",
+        "",
+        ...MODULES.map((m) => `- \`${m.prefix}:\` expands to \`${m.namespace}\``),
+        "",
+    ];
+    for (const module of MODULES) {
+        const inModule = (iri) => iri.startsWith(module.namespace);
+        const moduleClasses = [...classes].filter(inModule).sort(byCompact);
+        const moduleProperties = [...properties].filter(inModule).sort(byCompact);
+        const moduleIndividuals = [...individuals].filter(inModule).sort(byCompact);
+        const applicableProperties = [...properties].sort(byCompact);
+        lines.push(`## ${module.title} module (\`${module.prefix}:\`)`, "");
+        lines.push("### Classes", "");
+        for (const cls of moduleClasses)
+            lines.push(...renderClass(store, cls, applicableProperties));
+        lines.push("### Properties", "");
+        for (const property of moduleProperties)
+            lines.push(...renderProperty(store, property));
+        if (moduleIndividuals.length) {
+            lines.push("### Named individuals", "");
+            for (const individual of moduleIndividuals)
+                lines.push(...renderIndividual(store, individual));
+        }
+    }
+    return `${lines.join("\n").replace(/\n+$/, "")}\n`;
+};
+export const writeVocabulary = (path = join(ROOT, VOCABULARY_PATH), store) => {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, renderVocabulary(store));
+};
+export const checkVocabulary = (path = join(ROOT, VOCABULARY_PATH), store) => {
+    const expected = renderVocabulary(store);
+    const actual = existsSync(path) ? readFileSync(path, "utf8") : null;
+    if (actual === expected)
+        return { ok: true, message: `${path} is up to date` };
+    const reason = actual === null ? "is missing" : "differs from the ontology";
+    return { ok: false, message: `${path} ${reason}; run npm run docs and commit the result` };
+};