feat(demo): add Mermaid demo package and generator script

DKFuH · DKFuH · commit 651104221e69 · 2026-03-29T11:10:11.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -12,6 +12,7 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 - Added `orgscript check <file> --json` for machine-readable combined quality diagnostics.
 - Added `npm run check:all` and switched CI to the combined quality path.
 - Added `orgscript export mermaid <file>` for first-pass Mermaid exports of processes and stateflows.
+- Added `npm run demo:generate` plus a Mermaid demo package with generated Markdown and `.mmd` artifacts.
 - Added a canonical master language spec and lightweight governance guidance.
 - Added an example catalog and an initial VS Code syntax-highlighting scaffold.
 
diff --git a/README.md b/README.md
@@ -71,6 +71,21 @@ process CraftBusinessLeadToOrder
 
 See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/craft-business-lead-to-order.orgs).
 
+## From Source To Diagram
+
+OrgScript already generates visible downstream artifacts.
+
+Minimal Mermaid demos live in [`docs/demos/mermaid/README.md`](docs/demos/mermaid/README.md):
+
+- process demo from [`examples/lead-qualification.orgs`](examples/lead-qualification.orgs) to [`docs/demos/mermaid/lead-qualification.mermaid.md`](docs/demos/mermaid/lead-qualification.mermaid.md)
+- stateflow demo from [`examples/order-approval.orgs`](examples/order-approval.orgs) to [`docs/demos/mermaid/order-approval.mermaid.md`](docs/demos/mermaid/order-approval.mermaid.md)
+
+Generate the demo artifacts with:
+
+```text
+npm run demo:generate
+```
+
 ## Why this matters
 
 - Teams get a shared source of truth for operational logic.
@@ -126,6 +141,7 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
 - [`docs/repository-structure.md`](docs/repository-structure.md)
 - [`docs/syntax.md`](docs/syntax.md)
 - [`docs/semantics.md`](docs/semantics.md)
+- [`docs/demos/mermaid/README.md`](docs/demos/mermaid/README.md)
 - [`examples/README.md`](examples/README.md)
 - [`spec/grammar.ebnf`](spec/grammar.ebnf)
 - [`spec/language-spec.md`](spec/language-spec.md)
@@ -346,6 +362,7 @@ See [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md) for the implementation plan
 ```text
 npm test
 npm run export:mermaid
+npm run demo:generate
 npm run check
 npm run check:all
 npm run format:check:all
diff --git a/docs/demos/mermaid/README.md b/docs/demos/mermaid/README.md
@@ -0,0 +1,30 @@
+# Mermaid demos
+
+This folder shows the shortest useful path from OrgScript source to generated diagram artifacts.
+
+Each demo keeps the source file in `examples/` and generates two downstream artifacts here:
+
+- `*.mermaid.md`: a Markdown document ready for GitHub rendering
+- `*.mmd`: the first extracted Mermaid diagram block for direct Mermaid tooling use
+
+## Generate
+
+```text
+npm run demo:generate
+```
+
+## Demos
+
+| Demo | Source | Markdown artifact | Mermaid artifact |
+| --- | --- | --- | --- |
+| Lead qualification process | [lead-qualification.orgs](../../../examples/lead-qualification.orgs) | [lead-qualification.mermaid.md](./lead-qualification.mermaid.md) | [lead-qualification.mmd](./lead-qualification.mmd) |
+|  |  |  | A compact process example that shows trigger, branching, assignment, notification, and state transition. |
+| Order approval stateflow | [order-approval.orgs](../../../examples/order-approval.orgs) | [order-approval.mermaid.md](./order-approval.mermaid.md) | [order-approval.mmd](./order-approval.mmd) |
+|  |  |  | A stateflow-focused example that also demonstrates how Mermaid export skips unsupported blocks while still producing useful output. |
+
+## Notes
+
+- These artifacts are generated from the current exporter implementation.
+- `order-approval` intentionally demonstrates the current behavior where unsupported blocks are skipped and called out in the generated Markdown.
+- If you change Mermaid export behavior, regenerate this folder with `npm run demo:generate` and review the diffs.
+
diff --git a/docs/demos/mermaid/lead-qualification.mermaid.md b/docs/demos/mermaid/lead-qualification.mermaid.md
@@ -0,0 +1,38 @@
+# OrgScript Mermaid Export
+
+## Process: LeadQualification
+
+```mermaid
+flowchart TD
+  p1_start_1(["LeadQualification"])
+  p1_action_2["when lead.created"]
+  p1_decision_3{"if lead.source = &quot;referral&quot;"}
+  p1_action_4["assign lead.priority = &quot;high&quot;"]
+  p1_action_5["assign lead.path = &quot;premium&quot;"]
+  p1_action_6["notify sales with &quot;New referral lead&quot;"]
+  p1_decision_7{"if lead.source = &quot;ads&quot;"}
+  p1_action_8["assign lead.priority = &quot;normal&quot;"]
+  p1_action_9["assign lead.path = &quot;standard&quot;"]
+  p1_decision_10{"if lead.budget < 10000"}
+  p1_action_11["transition lead.status to &quot;disqualified&quot;"]
+  p1_action_12["notify sales with &quot;Budget below threshold&quot;"]
+  p1_stop_13(["stop"])
+  p1_action_14["transition lead.status to &quot;qualified&quot;"]
+  p1_end_15(["done"])
+  p1_start_1 --> p1_action_2
+  p1_action_2 --> p1_decision_3
+  p1_decision_3 -->|yes| p1_action_4
+  p1_action_4 --> p1_action_5
+  p1_action_5 --> p1_action_6
+  p1_decision_3 -->|no| p1_decision_7
+  p1_decision_7 -->|yes| p1_action_8
+  p1_action_8 --> p1_action_9
+  p1_action_6 --> p1_decision_10
+  p1_action_9 --> p1_decision_10
+  p1_decision_7 -->|no| p1_decision_10
+  p1_decision_10 -->|yes| p1_action_11
+  p1_action_11 --> p1_action_12
+  p1_action_12 --> p1_stop_13
+  p1_decision_10 -->|no| p1_action_14
+  p1_action_14 --> p1_end_15
+```
diff --git a/docs/demos/mermaid/lead-qualification.mmd b/docs/demos/mermaid/lead-qualification.mmd
@@ -0,0 +1,32 @@
+flowchart TD
+  p1_start_1(["LeadQualification"])
+  p1_action_2["when lead.created"]
+  p1_decision_3{"if lead.source = &quot;referral&quot;"}
+  p1_action_4["assign lead.priority = &quot;high&quot;"]
+  p1_action_5["assign lead.path = &quot;premium&quot;"]
+  p1_action_6["notify sales with &quot;New referral lead&quot;"]
+  p1_decision_7{"if lead.source = &quot;ads&quot;"}
+  p1_action_8["assign lead.priority = &quot;normal&quot;"]
+  p1_action_9["assign lead.path = &quot;standard&quot;"]
+  p1_decision_10{"if lead.budget < 10000"}
+  p1_action_11["transition lead.status to &quot;disqualified&quot;"]
+  p1_action_12["notify sales with &quot;Budget below threshold&quot;"]
+  p1_stop_13(["stop"])
+  p1_action_14["transition lead.status to &quot;qualified&quot;"]
+  p1_end_15(["done"])
+  p1_start_1 --> p1_action_2
+  p1_action_2 --> p1_decision_3
+  p1_decision_3 -->|yes| p1_action_4
+  p1_action_4 --> p1_action_5
+  p1_action_5 --> p1_action_6
+  p1_decision_3 -->|no| p1_decision_7
+  p1_decision_7 -->|yes| p1_action_8
+  p1_action_8 --> p1_action_9
+  p1_action_6 --> p1_decision_10
+  p1_action_9 --> p1_decision_10
+  p1_decision_7 -->|no| p1_decision_10
+  p1_decision_10 -->|yes| p1_action_11
+  p1_action_11 --> p1_action_12
+  p1_action_12 --> p1_stop_13
+  p1_decision_10 -->|no| p1_action_14
+  p1_action_14 --> p1_end_15
diff --git a/docs/demos/mermaid/order-approval.mermaid.md b/docs/demos/mermaid/order-approval.mermaid.md
@@ -0,0 +1,21 @@
+# OrgScript Mermaid Export
+
+## Stateflow: OrderStatus
+
+```mermaid
+stateDiagram-v2
+  state "draft" as s1_state_1
+  state "pending_approval" as s1_state_2
+  state "approved" as s1_state_3
+  state "production" as s1_state_4
+  state "completed" as s1_state_5
+  state "cancelled" as s1_state_6
+  s1_state_1 --> s1_state_2
+  s1_state_2 --> s1_state_3
+  s1_state_3 --> s1_state_4
+  s1_state_4 --> s1_state_5
+  s1_state_1 --> s1_state_6
+  s1_state_2 --> s1_state_6
+```
+
+> Note: Mermaid export currently supports only process and stateflow blocks. Skipped: rule NoProductionWithoutApproval.
diff --git a/docs/demos/mermaid/order-approval.mmd b/docs/demos/mermaid/order-approval.mmd
@@ -0,0 +1,13 @@
+stateDiagram-v2
+  state "draft" as s1_state_1
+  state "pending_approval" as s1_state_2
+  state "approved" as s1_state_3
+  state "production" as s1_state_4
+  state "completed" as s1_state_5
+  state "cancelled" as s1_state_6
+  s1_state_1 --> s1_state_2
+  s1_state_2 --> s1_state_3
+  s1_state_3 --> s1_state_4
+  s1_state_4 --> s1_state_5
+  s1_state_1 --> s1_state_6
+  s1_state_2 --> s1_state_6
diff --git a/docs/repository-structure.md b/docs/repository-structure.md
@@ -16,6 +16,13 @@ spec/
 docs/
   governance.md
   cli-v0.1-plan.md
+  demos/
+    mermaid/
+      README.md
+      lead-qualification.mermaid.md
+      lead-qualification.mmd
+      order-approval.mermaid.md
+      order-approval.mmd
   language-principles.md
   manifesto.md
   repository-structure.md
diff --git a/docs/roadmaps/v0.4.0.md b/docs/roadmaps/v0.4.0.md
@@ -21,6 +21,7 @@ Make OrgScript easier to use in daily development, CI, and editor workflows with
 - JSON diagnostics examples in the README and diagnostics spec
 - canonical language spec and governance notes
 - initial VS Code syntax-highlighting scaffold
+- Mermaid demo package with generated Markdown and `.mmd` artifacts
 
 ## Non-goals
 
diff --git a/examples/README.md b/examples/README.md
@@ -32,3 +32,5 @@ node ./bin/orgscript.js validate ./examples/lead-qualification.orgs
 node ./bin/orgscript.js check ./examples/craft-business-lead-to-order.orgs
 node ./bin/orgscript.js export mermaid ./examples/order-approval.orgs
 ```
+
+For generated Mermaid demo artifacts, see [`../docs/demos/mermaid/README.md`](../docs/demos/mermaid/README.md).
diff --git a/package.json b/package.json
@@ -18,6 +18,7 @@
     "lint:all": "node ./scripts/lint-all.js",
     "export:json": "node ./bin/orgscript.js export json ./examples/craft-business-lead-to-order.orgs",
     "export:mermaid": "node ./bin/orgscript.js export mermaid ./examples/craft-business-lead-to-order.orgs",
+    "demo:generate": "node ./scripts/generate-demo.js",
     "golden:generate": "node ./scripts/generate-golden.js",
     "test": "node ./tests/run.js"
   },
diff --git a/scripts/generate-demo.js b/scripts/generate-demo.js
@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { buildModel } = require("../src/validate");
+const { toCanonicalModel } = require("../src/export-json");
+const { toMermaidMarkdown } = require("../src/export-mermaid");
+
+const repoRoot = path.resolve(__dirname, "..");
+const outputDir = path.join(repoRoot, "docs", "demos", "mermaid");
+
+const demos = [
+  {
+    slug: "lead-qualification",
+    title: "Lead qualification process",
+    source: path.join(repoRoot, "examples", "lead-qualification.orgs"),
+    description:
+      "A compact process example that shows trigger, branching, assignment, notification, and state transition.",
+  },
+  {
+    slug: "order-approval",
+    title: "Order approval stateflow",
+    source: path.join(repoRoot, "examples", "order-approval.orgs"),
+    description:
+      "A stateflow-focused example that also demonstrates how Mermaid export skips unsupported blocks while still producing useful output.",
+  },
+];
+
+function main() {
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  for (const demo of demos) {
+    const result = buildModel(demo.source);
+
+    if (!result.ok) {
+      throw new Error(`Cannot generate demo for ${demo.slug}: source file is invalid.`);
+    }
+
+    const markdown = toMermaidMarkdown(toCanonicalModel(result.ast));
+    const rawMermaid = extractFirstMermaidBlock(markdown);
+
+    fs.writeFileSync(path.join(outputDir, `${demo.slug}.mermaid.md`), markdown, "utf8");
+    fs.writeFileSync(path.join(outputDir, `${demo.slug}.mmd`), `${rawMermaid}\n`, "utf8");
+  }
+
+  fs.writeFileSync(path.join(outputDir, "README.md"), renderReadme(), "utf8");
+}
+
+function extractFirstMermaidBlock(markdown) {
+  const match = markdown.match(/```mermaid\r?\n([\s\S]*?)\r?\n```/);
+
+  if (!match) {
+    throw new Error("Expected Mermaid export to contain at least one Mermaid code block.");
+  }
+
+  return match[1];
+}
+
+function renderReadme() {
+  const lines = [
+    "# Mermaid demos",
+    "",
+    "This folder shows the shortest useful path from OrgScript source to generated diagram artifacts.",
+    "",
+    "Each demo keeps the source file in `examples/` and generates two downstream artifacts here:",
+    "",
+    "- `*.mermaid.md`: a Markdown document ready for GitHub rendering",
+    "- `*.mmd`: the first extracted Mermaid diagram block for direct Mermaid tooling use",
+    "",
+    "## Generate",
+    "",
+    "```text",
+    "npm run demo:generate",
+    "```",
+    "",
+    "## Demos",
+    "",
+    "| Demo | Source | Markdown artifact | Mermaid artifact |",
+    "| --- | --- | --- | --- |",
+  ];
+
+  for (const demo of demos) {
+    const sourceRelative = path.relative(outputDir, demo.source).replace(/\\/g, "/");
+    lines.push(
+      `| ${demo.title} | [${path.basename(demo.source)}](${sourceRelative}) | [${demo.slug}.mermaid.md](./${demo.slug}.mermaid.md) | [${demo.slug}.mmd](./${demo.slug}.mmd) |`
+    );
+    lines.push(`|  |  |  | ${demo.description} |`);
+  }
+
+  lines.push("");
+  lines.push("## Notes");
+  lines.push("");
+  lines.push("- These artifacts are generated from the current exporter implementation.");
+  lines.push(
+    "- `order-approval` intentionally demonstrates the current behavior where unsupported blocks are skipped and called out in the generated Markdown."
+  );
+  lines.push(
+    "- If you change Mermaid export behavior, regenerate this folder with `npm run demo:generate` and review the diffs."
+  );
+  lines.push("");
+
+  return `${lines.join("\n")}\n`;
+}
+
+main();
