feat(export): add Mermaid exporter for processes and stateflows

Author: DKFuH

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on Keep a Changelog, and this project follows Semantic Versi
 - Added `orgscript format <file> --check` for canonical formatting checks without rewriting files.
 - Added `npm run format:check:all` and integrated formatting checks into CI.
 - Added `orgscript check <file>` as the combined quality command for validation, linting, and formatting checks.
+- Added `orgscript export mermaid <file>` for first-pass Mermaid exports of processes and stateflows.
 
 ## [0.3.0] - 2026-03-29
 

README.md

@@ -147,6 +147,7 @@ See the full example in [`examples/craft-business-lead-to-order.orgs`](examples/
 - AST-backed linting: `orgscript lint <file>`
 - Combined quality checks: `orgscript check <file>`
 - Canonical JSON export: `orgscript export json <file>`
+- Mermaid export for `process` and `stateflow`: `orgscript export mermaid <file>`
 - Machine-readable diagnostics: `orgscript validate <file> --json`, `orgscript lint <file> --json`
 - Golden snapshot tests for AST, canonical model, and formatter output
 - Stable lint severities: `error`, `warning`, `info`
@@ -163,6 +164,7 @@ node ./bin/orgscript.js format ./examples/craft-business-lead-to-order.orgs --ch
 node ./bin/orgscript.js lint ./tests/lint/process-missing-trigger.orgs
 node ./bin/orgscript.js lint ./tests/lint/process-missing-trigger.orgs --json
 node ./bin/orgscript.js export json ./examples/craft-business-lead-to-order.orgs
+node ./bin/orgscript.js export mermaid ./examples/craft-business-lead-to-order.orgs
 ```
 
 Exit codes are CI-friendly:
@@ -199,17 +201,21 @@ orgscript format file.orgs --check
 orgscript lint file.orgs
 orgscript lint file.orgs --json
 orgscript export json file.orgs
+orgscript export mermaid file.orgs
 orgscript check file.orgs
 ```
 
 `orgscript check` runs `validate`, `lint`, and `format --check` in that order and fails on validation errors, lint errors, or formatting drift. Warnings and info findings alone do not fail the command.
 
+`orgscript export mermaid` currently supports `process` and `stateflow` blocks and emits a Markdown document with Mermaid code blocks for direct use in GitHub or docs.
+
 See [`docs/cli-v0.1-plan.md`](docs/cli-v0.1-plan.md) for the implementation plan.
 
 ## Testing
 
 ```text
 npm test
+npm run export:mermaid
 npm run format:check:all
 npm run validate:all
 npm run lint:all

docs/cli-v0.1-plan.md

@@ -15,6 +15,7 @@ Implemented:
 - `format --check`
 - `lint`
 - `export json`
+- `export mermaid`
 - `validate --json`
 - `lint --json`
 - `check`
@@ -45,6 +46,20 @@ Output:
 
 Exports the parsed document into the canonical JSON model.
 
+### `orgscript export mermaid <file>`
+
+Exports supported blocks as a Markdown document with Mermaid code blocks.
+
+Current scope:
+
+- `process` -> `flowchart TD`
+- `stateflow` -> `stateDiagram-v2`
+
+Current limitations:
+
+- unsupported block types are skipped and called out in the export
+- files without any supported blocks fail with a clear error
+
 ### `orgscript format <file>`
 
 Normalizes:

package.json

@@ -16,6 +16,7 @@
     "validate:all": "node ./scripts/validate-all.js",
     "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",
     "golden:generate": "node ./scripts/generate-golden.js",
     "test": "node ./tests/run.js"
   },

scripts/generate-golden.js

@@ -5,6 +5,7 @@ const path = require("path");
 const { formatDocument } = require("../src/formatter");
 const { buildModel } = require("../src/validate");
 const { toCanonicalModel } = require("../src/export-json");
+const { toMermaidMarkdown } = require("../src/export-mermaid");
 
 const repoRoot = path.resolve(__dirname, "..");
 const examplesDir = path.join(repoRoot, "examples");
@@ -30,6 +31,8 @@ for (const file of files) {
   const astOutputPath = path.join(goldenDir, `${baseName}.ast.json`);
   const modelOutputPath = path.join(goldenDir, `${baseName}.model.json`);
   const formattedOutputPath = path.join(goldenDir, `${baseName}.formatted.orgs`);
+  const mermaidOutputPath = path.join(goldenDir, `${baseName}.mermaid.md`);
+  const canonicalModel = toCanonicalModel(result.ast);
 
   fs.writeFileSync(
     astOutputPath,
@@ -38,11 +41,19 @@ for (const file of files) {
   );
   fs.writeFileSync(
     modelOutputPath,
-    `${JSON.stringify(toCanonicalModel(result.ast), null, 2)}\n`,
+    `${JSON.stringify(canonicalModel, null, 2)}\n`,
     "utf8"
   );
   fs.writeFileSync(formattedOutputPath, formatDocument(result.ast), "utf8");
 
+  try {
+    fs.writeFileSync(mermaidOutputPath, toMermaidMarkdown(canonicalModel), "utf8");
+  } catch (error) {
+    if (fs.existsSync(mermaidOutputPath)) {
+      fs.unlinkSync(mermaidOutputPath);
+    }
+  }
+
   console.log(`Wrote golden files for ${file}`);
 }
 

src/cli.js

@@ -6,6 +6,7 @@ const {
   createValidateReport,
 } = require("./diagnostics");
 const { toCanonicalModel } = require("./export-json");
+const { toMermaidMarkdown } = require("./export-mermaid");
 const { formatDocument } = require("./formatter");
 const { lintDocument, renderLintReport, summarizeFindings } = require("./linter");
 const { buildModel, validateFile } = require("./validate");
@@ -19,6 +20,7 @@ Usage:
   orgscript format <file> [--check]
   orgscript lint <file> [--json]
   orgscript export json <file>
+  orgscript export mermaid <file>
 `);
 }
 
@@ -78,6 +80,29 @@ function run(args) {
     process.exit(0);
   }
 
+  if (command === "export" && maybeSubcommand === "mermaid") {
+    const absolutePath = resolveFile("export", maybeFile);
+    const result = buildModel(absolutePath);
+
+    if (!result.ok) {
+      printIssues(`Cannot export invalid OrgScript: ${absolutePath}`, [
+        ...result.syntaxIssues,
+        ...result.semanticIssues,
+      ]);
+      process.exit(1);
+    }
+
+    try {
+      const canonical = toCanonicalModel(result.ast);
+      const mermaid = toMermaidMarkdown(canonical);
+      process.stdout.write(mermaid);
+      process.exit(0);
+    } catch (error) {
+      console.error(`Cannot export Mermaid from ${absolutePath}: ${error.message}`);
+      process.exit(1);
+    }
+  }
+
   if (command === "format") {
     const absolutePath = resolveFile("format", maybeSubcommand);
     const result = buildModel(absolutePath);