sysprom 1.17.0 → 1.18.0

package/dist/src/cli/define-command.js

@@ -15,7 +15,6 @@ function fieldIsArray(field) {
 }
 function fieldIsBoolean(field) {
     const inner = unwrapField(field);
-    // ZodBoolean has no unique property, but we can check safeParse
     const trueResult = inner.safeParse(true);
     const strResult = inner.safeParse("test");
     return trueResult.success && !strResult.success;
@@ -33,26 +32,9 @@ function fieldChoices(field) {
     }
     return undefined;
 }
-function isZodField(obj) {
-    if (typeof obj !== "object" || obj === null)
-        return false;
-    // Check if it has methods/properties characteristic of Zod fields
-    const maybeField = toRecord(obj);
-    return (maybeField !== undefined &&
-        (typeof maybeField.safeParse === "function" ||
-            "description" in maybeField ||
-            "options" in maybeField ||
-            "element" in maybeField));
-}
 function isRecord(obj) {
     return typeof obj === "object" && obj !== null;
 }
-function toRecord(obj) {
-    if (isRecord(obj)) {
-        return obj;
-    }
-    return undefined;
-}
 function fieldDescription(field) {
     return field.description ?? "";
 }
@@ -65,6 +47,12 @@ function isZodLikeSchema(obj) {
     const maybeShape = toRecord(obj)?.shape;
     return typeof maybeShape === "object" && maybeShape !== null;
 }
+function toRecord(obj) {
+    if (isRecord(obj)) {
+        return obj;
+    }
+    return undefined;
+}
 function getShape(schema) {
     if (isZodLikeSchema(schema)) {
         return schema.shape;
@@ -72,11 +60,127 @@ function getShape(schema) {
     return undefined;
 }
 // ---------------------------------------------------------------------------
-// Build Commander from CommandDef
+// Helpers
 // ---------------------------------------------------------------------------
 function collect(value, previous) {
     return [...previous, value];
 }
+// ---------------------------------------------------------------------------
+// Action handler
+// ---------------------------------------------------------------------------
+function actionFailure(message) {
+    console.error(message);
+    process.exit(1);
+}
+function buildArgsObj(argsSchema, commanderArgs) {
+    const argsKeys = argsSchema ? Object.keys(getShape(argsSchema) ?? {}) : [];
+    const argsObj = {};
+    for (let i = 0; i < argsKeys.length; i++) {
+        argsObj[argsKeys[i]] = commanderArgs[i];
+    }
+    return argsObj;
+}
+function buildOptsObj(argsSchema, commanderArgs) {
+    const argsKeys = argsSchema ? Object.keys(getShape(argsSchema) ?? {}) : [];
+    const optsObjValue = commanderArgs[argsKeys.length];
+    return toRecord(optsObjValue) ?? {};
+}
+function validateAndParse(schema, data, label) {
+    const parsed = schema.safeParse(data);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            console.error(`${issue.path.join(".")}: ${issue.message}`);
+        }
+        actionFailure(`${label} validation failed`);
+    }
+    return schema.parse(data);
+}
+function runAction(argsSchema, optsSchema, commanderArgs, action) {
+    const argsObj = buildArgsObj(argsSchema, commanderArgs);
+    const optsObj = buildOptsObj(argsSchema, commanderArgs);
+    const argsData = argsSchema
+        ? validateAndParse(argsSchema, argsObj, "Argument")
+        : {};
+    const optsData = optsSchema
+        ? validateAndParse(optsSchema, optsObj, "Option")
+        : {};
+    try {
+        action(argsData, optsData);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(message);
+        actionFailure("Action threw an error");
+    }
+}
+// ---------------------------------------------------------------------------
+// Argument / option registration helpers
+// ---------------------------------------------------------------------------
+function registerArguments(cmd, argsSchema) {
+    const shape = getShape(argsSchema);
+    if (!shape)
+        return;
+    for (const key of Object.keys(shape)) {
+        const field = shape[key];
+        if (!field || !isZodField(field))
+            continue;
+        const desc = fieldDescription(field);
+        const choices = fieldChoices(field);
+        const optional = fieldIsOptional(field);
+        const flagName = camelToKebab(key);
+        if (choices) {
+            const arg = new Argument(optional ? `[${flagName}]` : `<${flagName}>`, desc).choices(choices);
+            cmd.addArgument(arg);
+        }
+        else {
+            cmd.argument(optional ? `[${flagName}]` : `<${flagName}>`, desc);
+        }
+    }
+}
+function registerOption(cmd, flagName, field, desc) {
+    const choices = fieldChoices(field);
+    const optional = fieldIsOptional(field);
+    const isArr = fieldIsArray(field);
+    const isBool = fieldIsBoolean(field);
+    if (isBool) {
+        cmd.addOption(new Option(`--${flagName}`, desc));
+        cmd.addOption(new Option(`--no-${flagName}`));
+    }
+    else if (isArr) {
+        const opt = new Option(`--${flagName} <value>`)
+            .argParser(collect)
+            .default([]);
+        if (!optional)
+            opt.makeOptionMandatory(true);
+        cmd.addOption(opt);
+    }
+    else if (choices) {
+        const opt = new Option(`--${flagName} <value>`).choices(choices);
+        if (!optional)
+            opt.makeOptionMandatory(true);
+        cmd.addOption(opt);
+    }
+    else if (optional) {
+        cmd.addOption(new Option(`--${flagName} <value>`).hideHelp());
+    }
+    else {
+        cmd.addOption(new Option(`--${flagName} <value>`).makeOptionMandatory(true).hideHelp());
+    }
+}
+function registerOptions(cmd, optsSchema) {
+    const shape = getShape(optsSchema);
+    if (!shape)
+        return;
+    for (const key of Object.keys(shape)) {
+        const field = shape[key];
+        if (!field || !isZodField(field))
+            continue;
+        registerOption(cmd, camelToKebab(key), field, fieldDescription(field));
+    }
+}
+// ---------------------------------------------------------------------------
+// Build Commander from CommandDef
+// ---------------------------------------------------------------------------
 /**
  * Build a Commander.js command tree from a declarative CommandDef, wiring up Zod-validated args, options, and actions.
  * @param def - The command definition to build from.
@@ -92,109 +196,12 @@ function collect(value, previous) {
 export function buildCommander(def, parent) {
     const cmd = parent.command(def.name);
     cmd.description(def.description);
-    {
-        const argsShape = getShape(def.args);
-        if (argsShape) {
-            for (const key of Object.keys(argsShape)) {
-                const field = argsShape[key];
-                if (!field || !isZodField(field))
-                    continue;
-                const desc = fieldDescription(field);
-                const choices = fieldChoices(field);
-                const optional = fieldIsOptional(field);
-                const flagName = camelToKebab(key);
-                if (choices) {
-                    const arg = new Argument(optional ? `[${flagName}]` : `<${flagName}>`, desc).choices(choices);
-                    cmd.addArgument(arg);
-                }
-                else {
-                    cmd.argument(optional ? `[${flagName}]` : `<${flagName}>`, desc);
-                }
-            }
-        }
-    }
-    {
-        const optsShape = getShape(def.opts);
-        if (optsShape) {
-            for (const key of Object.keys(optsShape)) {
-                const field = optsShape[key];
-                if (!field || !isZodField(field))
-                    continue;
-                const desc = fieldDescription(field);
-                const choices = fieldChoices(field);
-                const flagName = camelToKebab(key);
-                const optional = fieldIsOptional(field);
-                const isArr = fieldIsArray(field);
-                const isBool = fieldIsBoolean(field);
-                if (isBool) {
-                    cmd.option(`--${flagName}`, desc);
-                }
-                else if (isArr) {
-                    if (optional) {
-                        cmd.option(`--${flagName} <value>`, desc, collect, []);
-                    }
-                    else {
-                        cmd.requiredOption(`--${flagName} <value>`, desc, collect, []);
-                    }
-                }
-                else if (choices) {
-                    const opt = new Option(`--${flagName} <value>`, desc).choices(choices);
-                    if (!optional)
-                        opt.makeOptionMandatory();
-                    cmd.addOption(opt);
-                }
-                else if (optional) {
-                    cmd.option(`--${flagName} <value>`, desc);
-                }
-                else {
-                    cmd.requiredOption(`--${flagName} <value>`, desc);
-                }
-            }
-        }
-    }
+    registerArguments(cmd, def.args);
+    registerOptions(cmd, def.opts);
     if (def.action) {
         const action = def.action;
-        const argsSchema = def.args;
-        const optsSchema = def.opts;
         cmd.action((...commanderArgs) => {
-            let argsKeys = [];
-            const argsShape = getShape(argsSchema);
-            if (argsShape) {
-                argsKeys = Object.keys(argsShape);
-            }
-            const argsObj = {};
-            for (let i = 0; i < argsKeys.length; i++) {
-                argsObj[argsKeys[i]] = commanderArgs[i];
-            }
-            const optsObjValue = commanderArgs[argsKeys.length];
-            const optsObj = toRecord(optsObjValue) ?? {};
-            const parsedArgs = argsSchema
-                ? argsSchema.safeParse(argsObj)
-                : { data: {} };
-            const parsedOpts = optsSchema
-                ? optsSchema.safeParse(optsObj)
-                : { data: {} };
-            if ("success" in parsedArgs && !parsedArgs.success) {
-                for (const issue of parsedArgs.error.issues) {
-                    console.error(`${issue.path.join(".")}: ${issue.message}`);
-                }
-                process.exit(1);
-            }
-            if ("success" in parsedOpts && !parsedOpts.success) {
-                for (const issue of parsedOpts.error.issues) {
-                    console.error(`${issue.path.join(".")}: ${issue.message}`);
-                }
-                process.exit(1);
-            }
-            try {
-                const argsData = "data" in parsedArgs ? parsedArgs.data : {};
-                const optsData = "data" in parsedOpts ? parsedOpts.data : {};
-                action(argsData, optsData);
-            }
-            catch (err) {
-                console.error(err instanceof Error ? err.message : String(err));
-                process.exit(1);
-            }
+            runAction(def.args, def.opts, commanderArgs, action);
         });
     }
     if (def.subcommands) {
@@ -204,6 +211,54 @@ export function buildCommander(def, parent) {
     }
     return cmd;
 }
+// ---------------------------------------------------------------------------
+// Documentation extraction
+// ---------------------------------------------------------------------------
+function buildArgDocs(shape) {
+    const docs = [];
+    if (!shape)
+        return docs;
+    for (const key of Object.keys(shape)) {
+        const field = shape[key];
+        if (!field || !isZodField(field))
+            continue;
+        docs.push({
+            name: camelToKebab(key),
+            description: fieldDescription(field),
+            required: !fieldIsOptional(field),
+            choices: fieldChoices(field),
+        });
+    }
+    return docs;
+}
+function buildOptDocs(shape) {
+    const docs = [];
+    if (!shape)
+        return docs;
+    for (const key of Object.keys(shape)) {
+        const field = shape[key];
+        if (!field || !isZodField(field))
+            continue;
+        docs.push({
+            flag: `--${camelToKebab(key)}`,
+            description: fieldDescription(field),
+            required: !fieldIsOptional(field),
+            repeatable: fieldIsArray(field),
+            choices: fieldChoices(field),
+        });
+    }
+    return docs;
+}
+function isZodField(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return false;
+    const maybeField = toRecord(obj);
+    return (maybeField !== undefined &&
+        (typeof maybeField.safeParse === "function" ||
+            "description" in maybeField ||
+            "options" in maybeField ||
+            "element" in maybeField));
+}
 /**
  * Extract structured documentation from a CommandDef by introspecting its Zod schemas for args and options.
  * @param def - The command definition to extract docs from.
@@ -215,46 +270,11 @@ export function buildCommander(def, parent) {
  * ```
  */
 export function extractDocs(def) {
-    const args = [];
-    {
-        const argsShape = getShape(def.args);
-        if (argsShape) {
-            for (const key of Object.keys(argsShape)) {
-                const field = argsShape[key];
-                if (!field || !isZodField(field))
-                    continue;
-                args.push({
-                    name: camelToKebab(key),
-                    description: fieldDescription(field),
-                    required: !fieldIsOptional(field),
-                    choices: fieldChoices(field),
-                });
-            }
-        }
-    }
-    const opts = [];
-    {
-        const optsShape = getShape(def.opts);
-        if (optsShape) {
-            for (const key of Object.keys(optsShape)) {
-                const field = optsShape[key];
-                if (!field || !isZodField(field))
-                    continue;
-                opts.push({
-                    flag: `--${camelToKebab(key)}`,
-                    description: fieldDescription(field),
-                    required: !fieldIsOptional(field),
-                    repeatable: fieldIsArray(field),
-                    choices: fieldChoices(field),
-                });
-            }
-        }
-    }
     return {
         name: def.name,
         description: def.description,
-        args,
-        opts,
+        args: buildArgDocs(getShape(def.args)),
+        opts: buildOptDocs(getShape(def.opts)),
         subcommands: def.subcommands?.map(extractDocs),
         apiLink: def.apiLink,
     };

package/dist/src/endpoint-types.js

@@ -29,8 +29,8 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
     },
     // Realises — implementation hierarchy
     realises: {
-        from: ["capability", "element", "realisation"],
-        to: ["capability", "element", "realisation"],
+        from: ["capability", "element", "realisation", "artefact", "mode"],
+        to: ["capability", "element", "realisation", "concept", "stage"],
     },
     // Implements — operationalisation
     implements: {
@@ -161,7 +161,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
     // Performs — process enactment
     performs: {
         from: ["stage", "role"],
-        to: ["capability", "artefact", "artefact_flow"],
+        to: ["capability", "artefact", "artefact_flow", "stage"],
     },
     // Precedes — temporal ordering
     precedes: {
@@ -227,6 +227,7 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
             "gate",
             "change",
             "policy",
+            "artefact",
         ],
         to: ["policy", "protocol", "role", "principle", "invariant", "concept"],
     },
@@ -269,16 +270,17 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
             "stage",
             "decision",
             "change",
+            "invariant",
         ],
     },
     // Produces — generation
     produces: {
-        from: ["stage", "artefact_flow", "realisation"],
-        to: ["artefact"],
+        from: ["stage", "artefact_flow", "realisation", "concept"],
+        to: ["artefact", "concept"],
     },
     // Consumes — usage
     consumes: {
-        from: ["stage", "artefact_flow", "realisation"],
+        from: ["stage", "artefact_flow", "realisation", "role"],
         to: ["artefact"],
     },
     // Selects — choice and instantiation
@@ -309,6 +311,11 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
             "stage",
         ],
     },
+    // Justifies — design rationale grounding (principle/decision → invariant/decision/principle/concept)
+    justifies: {
+        from: ["principle", "decision"],
+        to: ["invariant", "decision", "principle", "concept"],
+    },
 };
 /**
  * Check if a relationship type is valid for the given endpoint node types.

package/dist/src/json-to-md.d.ts

@@ -1,11 +1,33 @@
 import { type SysProMDocument } from "./schema.js";
+type DiagramLayout = "LR" | "TD" | "RL" | "BT";
 /** Options for controlling JSON-to-Markdown conversion. */
 export interface ConvertOptions {
     form: "single-file" | "multi-doc";
+    embedDiagrams?: boolean;
+    labelMode?: "friendly" | "compact";
+    relationshipLayout?: DiagramLayout;
+    refinementLayout?: DiagramLayout;
+    decisionLayout?: DiagramLayout;
+    dependencyLayout?: DiagramLayout;
+}
+interface MarkdownRenderOptions {
+    embedDiagrams?: boolean;
+    labelMode?: "friendly" | "compact";
+    relationshipLayout?: DiagramLayout;
+    refinementLayout?: DiagramLayout;
+    decisionLayout?: DiagramLayout;
+    dependencyLayout?: DiagramLayout;
 }
 /**
  * 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
@@ -13,17 +35,24 @@ export interface ConvertOptions {
  * writeFileSync("output.spm.md", md);
  * ```
  */
-export declare function jsonToMarkdownSingle(doc: SysProMDocument): string;
+export declare function jsonToMarkdownSingle(doc: SysProMDocument, options?: MarkdownRenderOptions): string;
 /**
  * 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 declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: string): void;
+export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: string, options?: MarkdownRenderOptions): void;
 /**
  * Convert a SysProM document to Markdown, writing to the specified output path.
  * @param doc - The SysProM document to convert.
@@ -35,3 +64,4 @@ export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: str
  * ```
  */
 export declare function jsonToMarkdown(doc: SysProMDocument, output: string, options: ConvertOptions): void;
+export {};