sysprom 1.16.1 → 1.18.0

package/dist/src/json-to-md.js

@@ -1,6 +1,10 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { NODE_FILE_MAP, NODE_TYPE_LABELS, NodeType, RelationshipType, RELATIONSHIP_TYPE_LABELS, } from "./schema.js";
+import { graphOp } from "./operations/graph.js";
+import { graphRefinementOp } from "./operations/graph-refinement.js";
+import { graphDecisionOp } from "./operations/graph-decision.js";
+import { graphDependencyOp } from "./operations/graph-dependency.js";
 // ---------------------------------------------------------------------------
 // Text helpers
 // ---------------------------------------------------------------------------
@@ -25,7 +29,13 @@ function renderFrontMatter(fields) {
 // ---------------------------------------------------------------------------
 // Node location map (for hyperlinking)
 // ---------------------------------------------------------------------------
-/** GitHub-compatible heading anchor slug. */
+/**
+ * GitHub-compatible heading anchor slug.
+ * @param text
+ * @example
+ * // Convert a heading into a GitHub-style slug
+ * // slugify('ID — Name') // 'id---name'
+ */
 function slugify(text) {
     return text
         .toLowerCase()
@@ -64,6 +74,10 @@ function fileForNodeType(type) {
  * In single-file mode: `[ID](#anchor)`
  * In multi-doc mode: `[ID](./FILE.md#anchor)`
  * Falls back to plain ID if the node isn't in the map.
+ * @param id
+ * @param nodeMap
+ * @param currentFile
+ * @example
  */
 function linkNodeId(id, nodeMap, currentFile) {
     const loc = nodeMap.get(id);
@@ -412,9 +426,82 @@ function generateDocFile(doc, fileName, types, fromIdx, nodeMap) {
     lines.push(...renderNodesGrouped(doc.nodes, types, fromIdx, 2, nodeMap, `${fileName}.md`));
     return lines.join("\n") + "\n";
 }
+function generateDiagramsFile(doc, opts) {
+    const lines = [];
+    lines.push(renderFrontMatter({
+        title: "Diagrams",
+        doc_type: "diagrams",
+    }));
+    lines.push("");
+    lines.push("# Diagrams");
+    lines.push("");
+    lines.push("## Relationship Graph");
+    lines.push("");
+    lines.push("```mermaid");
+    lines.push(graphOp({
+        doc,
+        format: "mermaid",
+        layout: opts?.relationshipLayout ?? "TD",
+        labelMode: opts?.labelMode ?? "friendly",
+        cluster: true,
+        connectedOnly: false,
+    }));
+    lines.push("```");
+    lines.push("");
+    const refinement = graphRefinementOp({
+        doc,
+        format: "mermaid",
+        layout: opts?.refinementLayout ?? "TD",
+        labelMode: opts?.labelMode ?? "friendly",
+    });
+    if (refinement.includes("-->")) {
+        lines.push("## Refinement Chain");
+        lines.push("");
+        lines.push("```mermaid");
+        lines.push(refinement);
+        lines.push("```");
+        lines.push("");
+    }
+    const decisions = graphDecisionOp({
+        doc,
+        format: "mermaid",
+        layout: opts?.decisionLayout ?? "TD",
+        labelMode: opts?.labelMode ?? "friendly",
+    });
+    if (decisions.includes("-->")) {
+        lines.push("## Decision Map");
+        lines.push("");
+        lines.push("```mermaid");
+        lines.push(decisions);
+        lines.push("```");
+        lines.push("");
+    }
+    const dependencies = graphDependencyOp({
+        doc,
+        format: "mermaid",
+        layout: opts?.dependencyLayout ?? "LR",
+        labelMode: opts?.labelMode ?? "friendly",
+    });
+    if (dependencies.includes("-->") || dependencies.includes("-.->")) {
+        lines.push("## Dependency Graph");
+        lines.push("");
+        lines.push("```mermaid");
+        lines.push(dependencies);
+        lines.push("```");
+        lines.push("");
+    }
+    return lines.join("\n") + "\n";
+}
 /**
  * Convert a SysProM document to a single Markdown string.
  * @param doc - The SysProM document to convert.
+ * @param options
+ * @param options.embedDiagrams
+ * @param options.labelMode
+ * @param options.relationshipLayout
+ * @param options.refinementLayout
+ * @param options.decisionLayout
+ * @param options.dependencyLayout
  * @returns The Markdown representation.
  * @example
  * ```ts
@@ -422,7 +509,7 @@ function generateDocFile(doc, fileName, types, fromIdx, nodeMap) {
  * writeFileSync("output.spm.md", md);
  * ```
  */
-export function jsonToMarkdownSingle(doc) {
+export function jsonToMarkdownSingle(doc, options) {
     const fromIdx = indexRelationshipsFrom(doc.relationships ?? []);
     const nodeMap = buildNodeLocationMap(doc.nodes, "single-file");
     const lines = [];
@@ -449,6 +536,26 @@ export function jsonToMarkdownSingle(doc) {
         "version",
     ];
     lines.push(...renderNodesGrouped(doc.nodes, allTypes, fromIdx, 2, nodeMap));
+    // Diagrams section
+    if (options?.embedDiagrams &&
+        doc.relationships &&
+        doc.relationships.length > 0) {
+        lines.push("## Diagrams");
+        lines.push("");
+        lines.push("### Relationship Graph");
+        lines.push("");
+        lines.push("```mermaid");
+        lines.push(graphOp({
+            doc,
+            format: "mermaid",
+            layout: options?.relationshipLayout ?? "TD",
+            labelMode: options?.labelMode ?? "friendly",
+            cluster: true,
+            connectedOnly: false,
+        }));
+        lines.push("```");
+        lines.push("");
+    }
     // Relationships summary
     if (doc.relationships && doc.relationships.length > 0) {
         lines.push("## Relationships");
@@ -479,12 +586,19 @@ export function jsonToMarkdownSingle(doc) {
  * Convert a SysProM document to a multi-document Markdown folder.
  * @param doc - The SysProM document to convert.
  * @param outDir - Output directory path.
+ * @param options
+ * @param options.embedDiagrams
+ * @param options.labelMode
+ * @param options.relationshipLayout
+ * @param options.refinementLayout
+ * @param options.decisionLayout
+ * @param options.dependencyLayout
  * @example
  * ```ts
  * jsonToMarkdownMultiDoc(doc, "./SysProM");
  * ```
  */
-export function jsonToMarkdownMultiDoc(doc, outDir) {
+export function jsonToMarkdownMultiDoc(doc, outDir, options) {
     mkdirSync(outDir, { recursive: true });
     const fromIdx = indexRelationshipsFrom(doc.relationships ?? []);
     const nodeMap = buildNodeLocationMap(doc.nodes, "multi-doc");
@@ -495,6 +609,18 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
             continue;
         writeFileSync(join(outDir, `${fileName}.md`), generateDocFile(doc, fileName, types, fromIdx, nodeMap));
     }
+    // Diagrams file
+    if (options?.embedDiagrams &&
+        doc.relationships &&
+        doc.relationships.length > 0) {
+        writeFileSync(join(outDir, "DIAGRAMS.md"), generateDiagramsFile(doc, {
+            labelMode: options?.labelMode ?? "friendly",
+            relationshipLayout: options?.relationshipLayout,
+            refinementLayout: options?.refinementLayout,
+            decisionLayout: options?.decisionLayout,
+            dependencyLayout: options?.dependencyLayout,
+        }));
+    }
     // Subsystem folders or single files
     const subsystemNodes = doc.nodes.filter((n) => n.subsystem);
     // Count subsystems per type to decide automatic grouping
@@ -556,9 +682,23 @@ export function jsonToMarkdownMultiDoc(doc, outDir) {
  */
 export function jsonToMarkdown(doc, output, options) {
     if (options.form === "single-file") {
-        writeFileSync(output, jsonToMarkdownSingle(doc));
+        writeFileSync(output, jsonToMarkdownSingle(doc, {
+            embedDiagrams: options.embedDiagrams,
+            labelMode: options.labelMode,
+            relationshipLayout: options.relationshipLayout,
+            refinementLayout: options.refinementLayout,
+            decisionLayout: options.decisionLayout,
+            dependencyLayout: options.dependencyLayout,
+        }));
     }
     else {
-        jsonToMarkdownMultiDoc(doc, output);
+        jsonToMarkdownMultiDoc(doc, output, {
+            embedDiagrams: options.embedDiagrams,
+            labelMode: options.labelMode,
+            relationshipLayout: options.relationshipLayout,
+            refinementLayout: options.refinementLayout,
+            decisionLayout: options.decisionLayout,
+            dependencyLayout: options.dependencyLayout,
+        });
     }
 }

package/dist/src/mcp/server.js

@@ -5,11 +5,76 @@ import * as z from "zod";
 import { loadDocument, saveDocument } from "../io.js";
 import { NodeType, RelationshipType } from "../schema.js";
 import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, nextIdOp, inferCompletenessOp, inferLifecycleOp, inferImpactOp, impactSummaryOp, inferDerivedOp, } from "../operations/index.js";
+/**
+ * Wrap an error with a descriptive prefix and attach the original as cause.
+ * @param prefix - The error prefix (e.g., "Failed to add node")
+ * @param error - The caught error
+ * @example
+ * ```ts
+ * try {
+ *   someOperation();
+ * } catch (error) {
+ *   wrapError("Failed to do X", error);
+ * }
+ * ```
+ */
+function wrapError(prefix, error) {
+    throw new Error(`${prefix}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
 // Create MCP server instance
 const server = new McpServer({
     name: "sysprom-mcp",
     version: "1.0.0",
 });
+// Register init-document tool
+server.registerTool("init-document", {
+    description: "Initialise a new SysProM document with metadata and empty structure",
+    inputSchema: z.object({
+        path: z
+            .string()
+            .describe("Output path for the document (must end in .json)"),
+        title: z.string().describe("Document title"),
+        description: z.string().optional().describe("Document description"),
+        scope: z.string().optional().describe("Document scope"),
+    }),
+}, ({ path, title, description, scope }) => {
+    try {
+        const now = new Date().toISOString().split("T")[0];
+        const doc = {
+            $schema: "https://sysprom.org/schema.json",
+            metadata: {
+                title,
+                ...(description && { description }),
+                ...(scope && { scope }),
+                version: "1.0.0",
+                created: now,
+            },
+            nodes: [],
+            relationships: [],
+        };
+        try {
+            saveDocument(doc, "json", path);
+        }
+        catch (error) {
+            wrapError("Failed to save document", error);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Document initialised",
+                        path,
+                        title,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("init-document", error);
+    }
+});
 // Register validate tool
 server.registerTool("validate", {
     description: "Validate a SysProM document and return any validation issues",
@@ -145,34 +210,50 @@ server.registerTool("add-node", {
         description: z.string().optional().describe("Node description"),
     }),
 }, ({ path, type, id, name, description }) => {
-    const loaded = loadDocument(path);
-    const nodeType = NodeType.safeParse(type);
-    if (!nodeType.success) {
-        throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
-    }
-    const nodeId = id ?? nextIdOp({ doc: loaded.doc, type: nodeType.data });
-    const updated = addNodeOp({
-        doc: loaded.doc,
-        node: {
-            id: nodeId,
-            type: nodeType.data,
-            name,
-            ...(description && { description }),
-        },
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Node added",
+    try {
+        const loaded = loadDocument(path);
+        const nodeType = NodeType.safeParse(type);
+        if (!nodeType.success) {
+            throw new Error(`Invalid node type: "${type}". Valid types: ${NodeType.options.join(", ")}`);
+        }
+        const nodeId = id ?? nextIdOp({ doc: loaded.doc, type: nodeType.data });
+        let updated;
+        try {
+            updated = addNodeOp({
+                doc: loaded.doc,
+                node: {
                     id: nodeId,
-                    nodeCount: updated.nodes.length,
-                }, null, 2),
-            },
-        ],
-    };
+                    type: nodeType.data,
+                    name,
+                    ...(description && { description }),
+                },
+            });
+        }
+        catch (error) {
+            wrapError("Failed to add node", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Node added",
+                        id: nodeId,
+                        nodeCount: updated.nodes.length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("add-node", error);
+    }
 });
 // Register remove-node tool
 server.registerTool("remove-node", {
@@ -182,21 +263,37 @@ server.registerTool("remove-node", {
         id: z.string().describe("Node ID"),
     }),
 }, ({ path, id }) => {
-    const loaded = loadDocument(path);
-    const result = removeNodeOp({ doc: loaded.doc, id });
-    saveDocument(result.doc, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: `Node ${id} removed`,
-                    nodeCount: result.doc.nodes.length,
-                    warnings: result.warnings,
-                }, null, 2),
-            },
-        ],
-    };
+    try {
+        const loaded = loadDocument(path);
+        let result;
+        try {
+            result = removeNodeOp({ doc: loaded.doc, id });
+        }
+        catch (error) {
+            wrapError("Failed to remove node", error);
+        }
+        try {
+            saveDocument(result.doc, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: `Node ${id} removed`,
+                        nodeCount: result.doc.nodes.length,
+                        warnings: result.warnings,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("remove-node", error);
+    }
 });
 // Register update-node tool
 server.registerTool("update-node", {
@@ -207,11 +304,10 @@ server.registerTool("update-node", {
         fields: z.record(z.string(), z.unknown()).describe("Fields to update"),
     }),
 }, ({ path, id, fields }) => {
-    const loaded = loadDocument(path);
-    // Validate fields are valid node property updates
-    const validFields = Object.entries(fields).reduce((acc, [key, value]) => {
-        // Allow common node fields; unknown fields are silently ignored
-        if ([
+    try {
+        const loaded = loadDocument(path);
+        // Track which fields are valid
+        const allowedFields = [
             "name",
             "description",
             "status",
@@ -227,26 +323,55 @@ server.registerTool("update-node", {
             "input",
             "output",
             "external_references",
-        ].includes(key)) {
-            acc[key] = value;
+        ];
+        const droppedFields = [];
+        const validFields = Object.entries(fields).reduce((acc, [key, value]) => {
+            if (allowedFields.includes(key)) {
+                acc[key] = value;
+            }
+            else {
+                droppedFields.push(key);
+            }
+            return acc;
+        }, {});
+        let updated;
+        try {
+            updated = updateNodeOp({
+                doc: loaded.doc,
+                id,
+                fields: validFields,
+            });
         }
-        return acc;
-    }, {});
-    const updated = updateNodeOp({
-        doc: loaded.doc,
-        id,
-        fields: validFields,
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    const node = updated.nodes.find((n) => n.id === id);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({ message: "Node updated", node }, null, 2),
-            },
-        ],
-    };
+        catch (error) {
+            wrapError("Failed to update node", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const node = updated.nodes.find((n) => n.id === id);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Node updated",
+                        node,
+                        ...(droppedFields.length > 0 && {
+                            warnings: [
+                                `These fields are not updateable and were ignored: ${droppedFields.join(", ")}`,
+                            ],
+                        }),
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("update-node", error);
+    }
 });
 // Register add-relationship tool
 server.registerTool("add-relationship", {
@@ -258,31 +383,47 @@ server.registerTool("add-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const loaded = loadDocument(path);
-    const relType = RelationshipType.safeParse(type);
-    if (!relType.success) {
-        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+    try {
+        const loaded = loadDocument(path);
+        const relType = RelationshipType.safeParse(type);
+        if (!relType.success) {
+            throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+        }
+        let updated;
+        try {
+            updated = addRelationshipOp({
+                doc: loaded.doc,
+                rel: {
+                    from,
+                    to,
+                    type: relType.data,
+                },
+            });
+        }
+        catch (error) {
+            wrapError("Failed to add relationship", error);
+        }
+        try {
+            saveDocument(updated, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Relationship added",
+                        relationshipCount: (updated.relationships ?? []).length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("add-relationship", error);
     }
-    const updated = addRelationshipOp({
-        doc: loaded.doc,
-        rel: {
-            from,
-            to,
-            type: relType.data,
-        },
-    });
-    saveDocument(updated, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Relationship added",
-                    relationshipCount: (updated.relationships ?? []).length,
-                }, null, 2),
-            },
-        ],
-    };
 });
 // Register remove-relationship tool
 server.registerTool("remove-relationship", {
@@ -294,29 +435,45 @@ server.registerTool("remove-relationship", {
         type: z.string().describe("Relationship type"),
     }),
 }, ({ path, from, to, type }) => {
-    const loaded = loadDocument(path);
-    const relType = RelationshipType.safeParse(type);
-    if (!relType.success) {
-        throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+    try {
+        const loaded = loadDocument(path);
+        const relType = RelationshipType.safeParse(type);
+        if (!relType.success) {
+            throw new Error(`Invalid relationship type: "${type}". Valid types: ${RelationshipType.options.join(", ")}`);
+        }
+        let result;
+        try {
+            result = removeRelationshipOp({
+                doc: loaded.doc,
+                from,
+                to,
+                type: relType.data,
+            });
+        }
+        catch (error) {
+            wrapError("Failed to remove relationship", error);
+        }
+        try {
+            saveDocument(result.doc, loaded.format, loaded.path);
+        }
+        catch (error) {
+            throw new Error(`Failed to save document: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        message: "Relationship removed",
+                        relationshipCount: (result.doc.relationships ?? []).length,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        wrapError("remove-relationship", error);
     }
-    const result = removeRelationshipOp({
-        doc: loaded.doc,
-        from,
-        to,
-        type: relType.data,
-    });
-    saveDocument(result.doc, loaded.format, loaded.path);
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    message: "Relationship removed",
-                    relationshipCount: (result.doc.relationships ?? []).length,
-                }, null, 2),
-            },
-        ],
-    };
 });
 // Register infer-completeness tool
 server.registerTool("infer-completeness", {

package/dist/src/md-to-json.js

@@ -3,6 +3,13 @@ import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
 import { join, basename } from "node:path";
 import { NODE_FILE_MAP, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, NodeType, RelationshipType, NodeStatus, ExternalReferenceRole, } from "./schema.js";
 /** Strip markdown link syntax `[text](url)` → `text`. */
+/**
+ * Strip markdown link syntax `[text](url)` → `text`.
+ * @param s - Markdown text potentially containing links
+ * @returns Text with markdown links removed
+ * @example
+ * // stripMarkdownLink('[Hello](https://example.com)') // 'Hello'
+ */
 function stripMarkdownLink(s) {
     return s.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1");
 }