feat(cli): add --export-diagrams flag to render mermaid diagrams via local browser (finos#2634)

* feat(cli): add --export-diagrams flag to render mermaid diagrams via local browser

Adds --export-diagrams <svg|png> to docify, which post-processes generated
markdown to render mermaid code blocks into SVG/PNG images using a local
Chromium-based browser (playwright-core), with chrome/msedge auto-detection
and a --browser-path escape hatch. Rendering is opt-in and recoverable on
failure -- diagrams remain as mermaid blocks if no browser is found or a
diagram fails to render. playwright-core, mermaid, and @mermaid-js/layout-elk
are marked external in tsup configs and only loaded lazily when the flag is
used.

* docs(cli): document --export-diagrams, --browser-path, --diagram-render-timeout

Adds the new docify diagram-export options to the CLI README docify help
output and usage section, and to the working-with-calm CLI reference docs.

* fix(shared): resolve strict TS error in Docifier.renderDiagrams

this.exportDiagrams is DiagramExportFormat | undefined, and TS cannot
narrow it across the docify -> renderDiagrams call. renderDiagrams is
only invoked when exportDiagrams is set, so assert non-null.

* fix(shared): center exported diagrams and match export font to IDE rendering

Rewrite exported mermaid diagrams as centered <p align="center"><img/></p> blocks instead of plain markdown image references, and ensure the standalone SVG/PNG output uses the same font stack and sizing that calm-widgets/VS Code use for live rendering, fixing visual mismatches and oversized/clipped exports.

* fix(shared): address Copilot review feedback on diagram export

Use an explicit .md/.mdx regex (MARKDOWN_FILE_REGEX, now shared with
processDiagramsInDirectory) to decide whether --output is a file or a
directory, instead of path.extname which misclassified directories
with a dot in their name (e.g. docs/v1.2) as files.

Make MERMAID_BLOCK_REGEX tolerate CRLF line endings around mermaid
code fences, and switch the per-diagram mkdirp call to its async form
so it no longer blocks the event loop inside the render loop.

Also clarifies the MermaidBrowserRendererOptions.browser doc comment:
dispose() does close the passed-in browser.

* fix(shared): respect --verbose for diagram export logger

Docifier.renderDiagrams hardcoded initLogger(false, ...), so its debug-level logs (e.g. MermaidBrowserRenderer cleanup diagnostics) were always suppressed even when --verbose was passed. Align it with the process.env.DEBUG === 'true' pattern used by every other initLogger call in shared/src.

* test(shared): extract createMockLogger test helper

Dedupe the repeated mock Logger object literal across the docify and template-strategy specs into a shared createMockLogger() helper, and fix the loading-helpers.spec.ts mock from any to the proper Logger type. Also rename PNG_MAGIC_BYTES to PNG_SIGNATURE with a clarifying comment in the diagram-export e2e spec.

---------

Co-authored-by: Matthew Bain <66839492+rocketstack-matt@users.noreply.github.com>
Co-authored-by: LeighF <167173740+LeighFinegold@users.noreply.github.com>

Author: 3 people

calm-plugins/vscode/tsup.config.ts

@@ -12,8 +12,11 @@ export default defineConfig([
         dts: false,
         // Bundle runtime dependencies into the extension so the installed VSIX does
         // not rely on node_modules being present in the target environment.
-        // Keep 'vscode' external (provided by the host).
-        external: ['vscode'],
+        // Keep 'vscode' external (provided by the host). 'playwright-core' is also
+        // external: it's only required lazily by Docifier's --export-diagrams path
+        // (never used by the extension), and bundling it fails (esbuild can't
+        // resolve playwright-core's chromium-bidi subpath imports).
+        external: ['vscode', 'playwright-core'],
         noExternal: [
             'yaml',
             'lodash',

calm-server/tsup.config.ts

@@ -5,7 +5,7 @@ export default defineConfig({
     format: ['cjs'],
     sourcemap: false,
     clean: true,
-    external: ['canvas', 'fsevents', '@apidevtools/json-schema-ref-parser', /node_modules/, 'ts-node'],
+    external: ['canvas', 'fsevents', '@apidevtools/json-schema-ref-parser', /node_modules/, 'ts-node', 'playwright-core', 'mermaid', '@mermaid-js/layout-elk'],
     noExternal: ['@finos/calm-shared', '@finos/calm-widgets', '@finos/calm-models', /tsup/],
     bundle: true,
     splitting: false,

cli/README.md

@@ -452,6 +452,9 @@ Options:
   -t, --template <path>                   Path to a single .hbs or .md template file
   -d, --template-dir <path>               Path to a directory of .hbs/.md templates
   -u, --url-to-local-file-mapping <path>  Path to mapping file which maps URLs to local paths.
+      --export-diagrams <svg|png>         Render mermaid diagrams to image files using a local Chromium-based browser (adds roughly 10-40s depending on diagram count).
+      --browser-path <path>               Path to a Chromium-based browser executable, only needed if automatic detection fails.
+      --diagram-render-timeout <ms>       Per-diagram render timeout in milliseconds, only used with --export-diagrams (default: 30000).
   -v, --verbose                           Enable verbose logging. (default: false)
   -h, --help                              display help for command
 ```
@@ -487,6 +490,32 @@ Sample usage for you to try is as follows (assuming at root of project)
 calm docify -a ./cli/test_fixtures/template/model/document-system.json -o ./output/documentation -u ./cli/test_fixtures/template/model/url-to-file-directory.json
 ```
 
+### Exporting Diagrams as Images
+
+By default, generated documentation contains Mermaid diagrams as ` ```mermaid ` code
+blocks. The `--export-diagrams <svg|png>` option renders these diagrams to image
+files using a local Chromium-based browser, replacing each code block with a
+centered image reference (e.g. `<p align="center"><img src="_diagrams/my-page-1.svg" alt="Diagram 1" /></p>`).
+
+```shell
+calm docify -a ./architecture.json -o ./output/documentation --export-diagrams svg
+```
+
+This requires Google Chrome or Microsoft Edge to be installed locally (both are
+detected automatically). If neither is found, the command prints guidance for
+locating another Chromium-based browser, and the documentation is still generated
+with the Mermaid code blocks left as-is.
+
+- `--browser-path <path>`: use a specific Chromium-based browser (e.g. Brave,
+  Vivaldi, Chromium) instead of relying on automatic detection.
+- `--diagram-render-timeout <ms>`: per-diagram render timeout, useful for very
+  large or complex diagrams (default: `30000`).
+
+Rendering adds roughly 10-40 seconds to the command depending on the number of
+diagrams. If an individual diagram fails to render (e.g. a timeout or invalid
+syntax), it is left as a Mermaid code block and a warning is logged — the rest of
+the documentation is unaffected.
+
 ### Default options for widgets in templates
 
 Frontmatter can be used in templates to provide default options for any widgets used:

cli/package.json

@@ -39,11 +39,14 @@
     "dependencies": {
         "@apidevtools/json-schema-ref-parser": "^14.0.0",
         "@inquirer/prompts": "^7.4.1",
+        "@mermaid-js/layout-elk": "^0.2.1",
         "@stoplight/json": "^3.21.7",
         "commander": "^14.0.0",
         "copyfiles": "^2.4.1",
         "execa": "^9.6.0",
+        "mermaid": "^11.15.0",
         "mkdirp": "^3.0.1",
+        "playwright-core": "^1.56.0",
         "ts-node": "10.9.2"
     },
     "devDependencies": {

cli/src/cli.spec.ts

@@ -368,7 +368,10 @@ describe('CLI Commands', () => {
                 'bundle',
                 undefined,
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -388,7 +391,10 @@ describe('CLI Commands', () => {
                 'bundle',
                 undefined,
                 true,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -408,7 +414,10 @@ describe('CLI Commands', () => {
                 'template',
                 'template.hbs',
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -428,7 +437,10 @@ describe('CLI Commands', () => {
                 'template-directory',
                 'templateDir',
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -468,7 +480,10 @@ describe('CLI Commands', () => {
                 'bundle',
                 undefined,
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -488,7 +503,10 @@ describe('CLI Commands', () => {
                 'template',
                 'template.hbs',
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -514,7 +532,10 @@ describe('CLI Commands', () => {
                 'bundle',
                 undefined,
                 false,
-                false
+                false,
+                undefined,
+                undefined,
+                undefined
             );
         });
 
@@ -559,6 +580,159 @@ describe('CLI Commands', () => {
             exitSpy.mockRestore();
             errorSpy.mockRestore();
         });
+
+        it('should exit if --export-diagrams is combined with --scaffold', async () => {
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementationOnce(function () {
+                throw new Error('process.exit called');
+            });
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(function () { });
+
+            await expect(program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--scaffold',
+                '--export-diagrams', 'svg',
+            ])).rejects.toThrow('process.exit called');
+
+            expect(errorSpy).toHaveBeenCalledWith('❌ --export-diagrams cannot be combined with --scaffold (scaffold output is unrendered)');
+            expect(exitSpy).toHaveBeenCalledWith(1);
+
+            exitSpy.mockRestore();
+            errorSpy.mockRestore();
+        });
+
+        it('should pass --export-diagrams through to the Docifier', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--export-diagrams', 'svg',
+            ]);
+
+            expect(docifierConstructorSpy).toHaveBeenCalledWith(
+                'WEBSITE',
+                'model.json',
+                'outDir',
+                undefined,
+                'bundle',
+                undefined,
+                false,
+                false,
+                'svg',
+                undefined,
+                undefined
+            );
+        });
+
+        it('should pass --export-diagrams and --browser-path through to the Docifier', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--export-diagrams', 'png',
+                '--browser-path', '/path/to/chrome',
+            ]);
+
+            expect(docifierConstructorSpy).toHaveBeenCalledWith(
+                'WEBSITE',
+                'model.json',
+                'outDir',
+                undefined,
+                'bundle',
+                undefined,
+                false,
+                false,
+                'png',
+                '/path/to/chrome',
+                undefined
+            );
+        });
+
+        it('should pass --diagram-render-timeout through to the Docifier', async () => {
+            await program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--export-diagrams', 'svg',
+                '--diagram-render-timeout', '30000',
+            ]);
+
+            expect(docifierConstructorSpy).toHaveBeenCalledWith(
+                'WEBSITE',
+                'model.json',
+                'outDir',
+                undefined,
+                'bundle',
+                undefined,
+                false,
+                false,
+                'svg',
+                undefined,
+                30000
+            );
+        });
+
+        it('should exit if --diagram-render-timeout is specified without --export-diagrams', async () => {
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementationOnce(function () {
+                throw new Error('process.exit called');
+            });
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(function () { });
+
+            await expect(program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--diagram-render-timeout', '30000',
+            ])).rejects.toThrow('process.exit called');
+
+            expect(errorSpy).toHaveBeenCalledWith('❌ --diagram-render-timeout requires --export-diagrams <svg|png>');
+            expect(exitSpy).toHaveBeenCalledWith(1);
+
+            exitSpy.mockRestore();
+            errorSpy.mockRestore();
+        });
+
+        it('should exit if --diagram-render-timeout is not a positive number', async () => {
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementationOnce(function () {
+                throw new Error('process.exit called');
+            });
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(function () { });
+
+            await expect(program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--export-diagrams', 'svg',
+                '--diagram-render-timeout', '0',
+            ])).rejects.toThrow('process.exit called');
+
+            expect(errorSpy).toHaveBeenCalledWith('❌ --diagram-render-timeout must be a positive number of milliseconds');
+            expect(exitSpy).toHaveBeenCalledWith(1);
+
+            exitSpy.mockRestore();
+            errorSpy.mockRestore();
+        });
+
+        it('should exit if --browser-path is specified without --export-diagrams', async () => {
+            const exitSpy = vi.spyOn(process, 'exit').mockImplementationOnce(function () {
+                throw new Error('process.exit called');
+            });
+            const errorSpy = vi.spyOn(console, 'error').mockImplementation(function () { });
+
+            await expect(program.parseAsync([
+                'node', 'cli.js', 'docify',
+                '--architecture', 'model.json',
+                '--output', 'outDir',
+                '--browser-path', '/path/to/chrome',
+            ])).rejects.toThrow('process.exit called');
+
+            expect(errorSpy).toHaveBeenCalledWith('❌ --browser-path requires --export-diagrams <svg|png>');
+            expect(exitSpy).toHaveBeenCalledWith(1);
+
+            exitSpy.mockRestore();
+            errorSpy.mockRestore();
+        });
     });
 
     describe('push architecture command', () => {

cli/src/cli.ts

@@ -1,4 +1,4 @@
-import { CALM_META_SCHEMA_DIRECTORY, DocifyMode, initLogger, runGenerate, SchemaDirectory, TemplateProcessingMode, CalmChoice, buildDocumentLoader, DocumentLoader, DocumentLoaderOptions } from '@finos/calm-shared';
+import { CALM_META_SCHEMA_DIRECTORY, DocifyMode, DiagramExportFormat, initLogger, runGenerate, SchemaDirectory, TemplateProcessingMode, CalmChoice, buildDocumentLoader, DocumentLoader, DocumentLoaderOptions } from '@finos/calm-shared';
 import { Option, Command } from 'commander';
 import { version } from '../package.json';
 import { promptUserForOptions, loadChoicesFromInput } from './command-helpers/generate-options';
@@ -212,6 +212,14 @@ Validation requires:
         .option(URL_MAPPING_OPTION, 'Path to mapping file which maps URLs to local paths')
         .option('--scaffold', 'Copy template files without processing (for customization/live docify)', false)
         .addOption(new Option('--ants').default(false).hideHelp())
+        .addOption(new Option('--export-diagrams <format>',
+            'Render mermaid diagrams to image files using a local Chromium-based browser ' +
+            '(adds roughly 10-40s depending on diagram count)').choices(['svg', 'png']))
+        .option('--browser-path <path>',
+            'Path to a Chromium-based browser executable, only needed if automatic detection fails (run with --export-diagrams to see guidance)')
+        .option('--diagram-render-timeout <ms>',
+            'Per-diagram render timeout in milliseconds, only used with --export-diagrams (default: 30000). ' +
+            'Increase this for large/complex diagrams that time out during rendering.')
         .option(VERBOSE_OPTION, 'Enable verbose logging.', false)
         .action(async (options) => {
             const { Docifier } = await import('@finos/calm-shared');
@@ -232,6 +240,30 @@ Validation requires:
                 process.exit(1);
             }
 
+            if (options.exportDiagrams && options.scaffold) {
+                console.error('❌ --export-diagrams cannot be combined with --scaffold (scaffold output is unrendered)');
+                process.exit(1);
+            }
+
+            if (options.browserPath && !options.exportDiagrams) {
+                console.error('❌ --browser-path requires --export-diagrams <svg|png>');
+                process.exit(1);
+            }
+
+            if (options.diagramRenderTimeout && !options.exportDiagrams) {
+                console.error('❌ --diagram-render-timeout requires --export-diagrams <svg|png>');
+                process.exit(1);
+            }
+
+            let diagramRenderTimeoutMs: number | undefined;
+            if (options.diagramRenderTimeout) {
+                diagramRenderTimeoutMs = Number(options.diagramRenderTimeout);
+                if (!Number.isFinite(diagramRenderTimeoutMs) || diagramRenderTimeoutMs <= 0) {
+                    console.error('❌ --diagram-render-timeout must be a positive number of milliseconds');
+                    process.exit(1);
+                }
+            }
+
             let docifyMode: DocifyMode = 'WEBSITE';
             let templateProcessingMode: TemplateProcessingMode = 'bundle';
             let templatePath: string | undefined = undefined;
@@ -256,7 +288,10 @@ Validation requires:
                 templateProcessingMode,
                 templatePath,
                 options.clearOutputDirectory,
-                options.scaffold
+                options.scaffold,
+                options.exportDiagrams as DiagramExportFormat | undefined,
+                options.browserPath,
+                diagramRenderTimeoutMs
             );
 
             await docifier.docify();

cli/tsup.config.ts

@@ -7,7 +7,7 @@ export default defineConfig({
     format: ['cjs'],
     sourcemap: false,
     clean: true,
-    external: ['canvas', 'fsevents', '@apidevtools/json-schema-ref-parser', /node_modules/, 'ts-node'],
+    external: ['canvas', 'fsevents', '@apidevtools/json-schema-ref-parser', /node_modules/, 'ts-node', 'playwright-core', 'mermaid', '@mermaid-js/layout-elk'],
     noExternal: ['@finos/calm-shared', '@finos/calm-widgets','@finos/calm-models', /tsup/],
     bundle: true,
     splitting: false,