sysprom 1.22.1 → 1.23.1

package/dist/src/cli/commands/sync.js

@@ -1,10 +1,10 @@
 import * as z from "zod";
-import { readFileSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync, } from "node:fs";
+import { resolve, extname } from "node:path";
 import { syncDocumentsOp, } from "../../operations/index.js";
 import { detectChanges } from "../../sync.js";
 import { markdownToJson } from "../../md-to-json.js";
-import { jsonToMarkdownSingle } from "../../json-to-md.js";
+import { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, } from "../../json-to-md.js";
 import { canonicalise } from "../../canonical-json.js";
 import { SysProMDocument } from "../../schema.js";
 /**
@@ -22,8 +22,10 @@ export function syncCommand(input) {
     if (!SysProMDocument.is(jsonDoc)) {
         throw new Error("JSON file is not a valid SysProM document");
     }
-    // Parse Markdown to document
-    const mdDoc = markdownToJson(mdPath);
+    // Parse Markdown to document, or create empty doc if it doesn't exist yet
+    const mdDoc = existsSync(mdPath)
+        ? markdownToJson(mdPath)
+        : { nodes: [], relationships: [] };
     // Detect which side changed
     const changes = detectChanges(jsonPath, mdPath);
     // Perform sync operation
@@ -34,6 +36,8 @@ export function syncCommand(input) {
         mdChanged: changes.mdChanged,
         strategy,
     });
+    // Track if markdown file existed before sync
+    const mdExistedBefore = existsSync(mdPath);
     // Write results if not dry-run
     if (!dryRun) {
         // Write synced document back to both formats
@@ -41,10 +45,26 @@ export function syncCommand(input) {
             // Update JSON
             writeFileSync(jsonPath, canonicalise(result.synced, { indent: "\t" }) + "\n");
             // Update Markdown
-            const mdContent = jsonToMarkdownSingle(result.synced);
-            writeFileSync(mdPath, mdContent);
+            // If output path is an existing directory or doesn't look like a .md file,
+            // write multi-doc output into the directory. Otherwise write single-file MD.
+            if (mdExistedBefore && statSync(mdPath).isDirectory()) {
+                jsonToMarkdownMultiDoc(result.synced, mdPath);
+            }
+            else if (extname(mdPath) === ".md") {
+                const mdContent = jsonToMarkdownSingle(result.synced);
+                writeFileSync(mdPath, mdContent);
+            }
+            else {
+                // Treat as directory: ensure it exists and write multi-doc
+                mkdirSync(mdPath, { recursive: true });
+                jsonToMarkdownMultiDoc(result.synced, mdPath);
+            }
         }
     }
+    // If markdown file didn't exist before but does now (we created it), mark mdChanged as true
+    if (!mdExistedBefore && existsSync(mdPath) && !dryRun) {
+        result.mdChanged = true;
+    }
     return result;
 }
 const syncOpts = z
@@ -97,5 +117,9 @@ export const syncCommandDef = {
         if (result.changedNodes.length > 0) {
             console.log(`  Changed nodes: ${result.changedNodes.join(", ")}`);
         }
+        const hasDrift = result.jsonChanged || result.mdChanged || result.conflict;
+        if ((opts.dryRun || opts.report) && hasDrift) {
+            process.exitCode = 1;
+        }
     },
 };

package/dist/src/operations/graph-shared.js

@@ -105,6 +105,24 @@ const NODE_TYPE_SHAPES = {
 export function mermaidShapeForNode(node) {
     return NODE_TYPE_SHAPES[node.type] ?? "rectangle";
 }
+/**
+ * Escape a Mermaid label by wrapping in quotes if it contains special characters.
+ * Mermaid shape delimiters and other special chars need escaping: ( ) { } [ ] / \
+ * Wrapping in double quotes allows these characters to be rendered as-is.
+ * @param label - The label text to escape
+ * @returns The label, quoted if it contains special characters
+ * @example
+ * escapeMermaidLabel("Firebase (Tenant)") // returns '"Firebase (Tenant)"'
+ */
+function escapeMermaidLabel(label) {
+    // Check if label contains any Mermaid special characters that need escaping
+    const specialChars = ["(", ")", "{", "}", "[", "]", "/", "\\"];
+    if (specialChars.some((char) => label.includes(char))) {
+        // Wrap in double quotes to escape
+        return `"${label}"`;
+    }
+    return label;
+}
 /**
  * Render a Mermaid node definition for a node id/name/shape.
  * @param id - Node id
@@ -116,16 +134,17 @@ export function mermaidShapeForNode(node) {
 export function renderMermaidNode(id, name, shape, mode = "friendly") {
     const safeId = sanitiseMermaidId(id);
     const label = mode === "compact" ? id : `${id}: ${name}`;
+    const escapedLabel = escapeMermaidLabel(label);
     switch (shape) {
         case "rounded":
-            return `${safeId}([${label}])`;
+            return `${safeId}([${escapedLabel}])`;
         case "rhombus":
-            return `${safeId}{{${label}}}`;
+            return `${safeId}{{${escapedLabel}}}`;
         case "parallelogram":
-            return `${safeId}[/${label}/]`;
+            return `${safeId}[/${escapedLabel}/]`;
         case "rectangle":
         default:
-            return `${safeId}[${label}]`;
+            return `${safeId}[${escapedLabel}]`;
     }
 }
 /**

package/dist/src/sync.js

@@ -1,4 +1,4 @@
-import { readFileSync, statSync } from "node:fs";
+import { readFileSync, statSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { markdownToJson } from "./md-to-json.js";
 import { SysProMDocument } from "./schema.js";
@@ -42,8 +42,10 @@ export function detectChanges(jsonPath, mdPath) {
     if (!SysProMDocument.is(jsonDoc)) {
         throw new Error("JSON file is not a valid SysProM document");
     }
-    // Parse Markdown to document
-    const mdDoc = markdownToJson(mdPath);
+    // Parse Markdown to document (or treat as empty if it doesn't exist)
+    const mdDoc = existsSync(mdPath)
+        ? markdownToJson(mdPath)
+        : { nodes: [], relationships: [] };
     // Compare parsed documents
     const jsonHash = normaliseHash(jsonDoc);
     const mdHash = normaliseHash(mdDoc);
@@ -55,6 +57,14 @@ export function detectChanges(jsonPath, mdPath) {
             conflict: false,
         };
     }
+    // If markdown file doesn't exist, treat as if JSON changed (JSON is the source)
+    if (!existsSync(mdPath)) {
+        return {
+            jsonChanged: true,
+            mdChanged: false,
+            conflict: false,
+        };
+    }
     // Parsed documents differ. Use file modification times to determine which changed.
     // The file that was modified more recently is the one that diverged.
     const jsonStats = statSync(jsonPath);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "sysprom",
-	"version": "1.22.1",
+	"version": "1.23.1",
 	"description": "SysProM — System Provenance Model CLI and library",
 	"author": "ExaDev",
 	"homepage": "https://exadev.github.io/SysProM",