sysprom 1.17.0 → 1.18.0

package/dist/src/operations/graph-refinement.d.ts

@@ -0,0 +1,329 @@
+import * as z from "zod";
+/** Generate a refinement chain diagram showing how nodes elaborate through abstraction layers. */
+export declare const graphRefinementOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
+    doc: z.ZodObject<{
+        $schema: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            doc_type: z.ZodOptional<z.ZodString>;
+            scope: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodString>;
+            version: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodInt]>>;
+        }, z.core.$loose> & {
+            is(value: unknown): value is {
+                [x: string]: unknown;
+                title?: string | undefined;
+                doc_type?: string | undefined;
+                scope?: string | undefined;
+                status?: string | undefined;
+                version?: string | number | undefined;
+            };
+        }>;
+        nodes: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodEnum<{
+                intent: "intent";
+                concept: "concept";
+                capability: "capability";
+                element: "element";
+                realisation: "realisation";
+                invariant: "invariant";
+                principle: "principle";
+                policy: "policy";
+                protocol: "protocol";
+                stage: "stage";
+                role: "role";
+                gate: "gate";
+                mode: "mode";
+                artefact: "artefact";
+                artefact_flow: "artefact_flow";
+                decision: "decision";
+                change: "change";
+                view: "view";
+                milestone: "milestone";
+                version: "version";
+            }> & {
+                is(value: unknown): value is "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version";
+            };
+            name: z.ZodString;
+            description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+            status: z.ZodOptional<z.ZodEnum<{
+                deprecated: "deprecated";
+                proposed: "proposed";
+                accepted: "accepted";
+                active: "active";
+                implemented: "implemented";
+                adopted: "adopted";
+                defined: "defined";
+                introduced: "introduced";
+                in_progress: "in_progress";
+                complete: "complete";
+                consolidated: "consolidated";
+                experimental: "experimental";
+                retired: "retired";
+                superseded: "superseded";
+                abandoned: "abandoned";
+                deferred: "deferred";
+            }> & {
+                is(value: unknown): value is "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred";
+            }>;
+            lifecycle: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>>;
+            context: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+            options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                    is(value: unknown): value is string | string[];
+                };
+            }, z.core.$loose> & {
+                is(value: unknown): value is {
+                    [x: string]: unknown;
+                    id: string;
+                    description: string | string[];
+                };
+            }>>;
+            selected: z.ZodOptional<z.ZodString>;
+            rationale: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+            scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            operations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                type: z.ZodEnum<{
+                    link: "link";
+                    add: "add";
+                    update: "update";
+                    remove: "remove";
+                }>;
+                target: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                    is(value: unknown): value is string | string[];
+                }>;
+            }, z.core.$loose> & {
+                is(value: unknown): value is {
+                    [x: string]: unknown;
+                    type: "link" | "add" | "update" | "remove";
+                    target?: string | undefined;
+                    description?: string | string[] | undefined;
+                };
+            }>>;
+            plan: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                description: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                    is(value: unknown): value is string | string[];
+                };
+                done: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+            }, z.core.$loose> & {
+                is(value: unknown): value is {
+                    [x: string]: unknown;
+                    description: string | string[];
+                    done?: boolean | undefined;
+                };
+            }>>;
+            propagation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+            includes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            input: z.ZodOptional<z.ZodString>;
+            output: z.ZodOptional<z.ZodString>;
+            external_references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                role: z.ZodEnum<{
+                    output: "output";
+                    input: "input";
+                    context: "context";
+                    evidence: "evidence";
+                    source: "source";
+                    standard: "standard";
+                    prior_art: "prior_art";
+                }> & {
+                    is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+                };
+                identifier: z.ZodString;
+                description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                    is(value: unknown): value is string | string[];
+                }>;
+                node_id: z.ZodOptional<z.ZodString>;
+                internalised: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                    is(value: unknown): value is string | string[];
+                }>;
+            }, z.core.$strip> & {
+                is(value: unknown): value is {
+                    role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+                    identifier: string;
+                    description?: string | string[] | undefined;
+                    node_id?: string | undefined;
+                    internalised?: string | string[] | undefined;
+                };
+            }>>;
+            readonly subsystem: z.ZodOptional<z.ZodObject</*elided*/ any, z.core.$strip>>;
+        }, z.core.$loose>>;
+        relationships: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+            type: z.ZodEnum<{
+                refines: "refines";
+                realises: "realises";
+                implements: "implements";
+                depends_on: "depends_on";
+                constrained_by: "constrained_by";
+                affects: "affects";
+                supersedes: "supersedes";
+                must_preserve: "must_preserve";
+                performs: "performs";
+                part_of: "part_of";
+                precedes: "precedes";
+                must_follow: "must_follow";
+                blocks: "blocks";
+                routes_to: "routes_to";
+                governed_by: "governed_by";
+                modifies: "modifies";
+                triggered_by: "triggered_by";
+                applies_to: "applies_to";
+                produces: "produces";
+                consumes: "consumes";
+                transforms_into: "transforms_into";
+                selects: "selects";
+                requires: "requires";
+                disables: "disables";
+                influence: "influence";
+                justifies: "justifies";
+            }> & {
+                is(value: unknown): value is "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables" | "influence" | "justifies";
+            };
+            description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+            polarity: z.ZodOptional<z.ZodEnum<{
+                positive: "positive";
+                negative: "negative";
+                neutral: "neutral";
+                uncertain: "uncertain";
+            }> & {
+                is(value: unknown): value is "positive" | "negative" | "neutral" | "uncertain";
+            }>;
+            strength: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$loose> & {
+            is(value: unknown): value is {
+                [x: string]: unknown;
+                from: string;
+                to: string;
+                type: "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables" | "influence" | "justifies";
+                description?: string | string[] | undefined;
+                polarity?: "positive" | "negative" | "neutral" | "uncertain" | undefined;
+                strength?: number | undefined;
+            };
+        }>>;
+        external_references: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            role: z.ZodEnum<{
+                output: "output";
+                input: "input";
+                context: "context";
+                evidence: "evidence";
+                source: "source";
+                standard: "standard";
+                prior_art: "prior_art";
+            }> & {
+                is(value: unknown): value is "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+            };
+            identifier: z.ZodString;
+            description: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+            node_id: z.ZodOptional<z.ZodString>;
+            internalised: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]> & {
+                is(value: unknown): value is string | string[];
+            }>;
+        }, z.core.$strip> & {
+            is(value: unknown): value is {
+                role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+                identifier: string;
+                description?: string | string[] | undefined;
+                node_id?: string | undefined;
+                internalised?: string | string[] | undefined;
+            };
+        }>>;
+    }, z.core.$strip> & {
+        is(value: unknown): value is {
+            nodes: {
+                [x: string]: unknown;
+                id: string;
+                type: "intent" | "concept" | "capability" | "element" | "realisation" | "invariant" | "principle" | "policy" | "protocol" | "stage" | "role" | "gate" | "mode" | "artefact" | "artefact_flow" | "decision" | "change" | "view" | "milestone" | "version";
+                name: string;
+                description?: string | string[] | undefined;
+                status?: "deprecated" | "proposed" | "accepted" | "active" | "implemented" | "adopted" | "defined" | "introduced" | "in_progress" | "complete" | "consolidated" | "experimental" | "retired" | "superseded" | "abandoned" | "deferred" | undefined;
+                lifecycle?: Record<string, string | boolean> | undefined;
+                context?: string | string[] | undefined;
+                options?: {
+                    [x: string]: unknown;
+                    id: string;
+                    description: string | string[];
+                }[] | undefined;
+                selected?: string | undefined;
+                rationale?: string | string[] | undefined;
+                scope?: string[] | undefined;
+                operations?: {
+                    [x: string]: unknown;
+                    type: "link" | "add" | "update" | "remove";
+                    target?: string | undefined;
+                    description?: string | string[] | undefined;
+                }[] | undefined;
+                plan?: {
+                    [x: string]: unknown;
+                    description: string | string[];
+                    done?: boolean | undefined;
+                }[] | undefined;
+                propagation?: Record<string, boolean> | undefined;
+                includes?: string[] | undefined;
+                input?: string | undefined;
+                output?: string | undefined;
+                external_references?: {
+                    role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+                    identifier: string;
+                    description?: string | string[] | undefined;
+                    node_id?: string | undefined;
+                    internalised?: string | string[] | undefined;
+                }[] | undefined;
+                subsystem?: /*elided*/ any | undefined;
+            }[];
+            $schema?: string | undefined;
+            metadata?: {
+                [x: string]: unknown;
+                title?: string | undefined;
+                doc_type?: string | undefined;
+                scope?: string | undefined;
+                status?: string | undefined;
+                version?: string | number | undefined;
+            } | undefined;
+            relationships?: {
+                [x: string]: unknown;
+                from: string;
+                to: string;
+                type: "refines" | "realises" | "implements" | "depends_on" | "constrained_by" | "affects" | "supersedes" | "must_preserve" | "performs" | "part_of" | "precedes" | "must_follow" | "blocks" | "routes_to" | "governed_by" | "modifies" | "triggered_by" | "applies_to" | "produces" | "consumes" | "transforms_into" | "selects" | "requires" | "disables" | "influence" | "justifies";
+                description?: string | string[] | undefined;
+                polarity?: "positive" | "negative" | "neutral" | "uncertain" | undefined;
+                strength?: number | undefined;
+            }[] | undefined;
+            external_references?: {
+                role: "output" | "input" | "context" | "evidence" | "source" | "standard" | "prior_art";
+                identifier: string;
+                description?: string | string[] | undefined;
+                node_id?: string | undefined;
+                internalised?: string | string[] | undefined;
+            }[] | undefined;
+        };
+    };
+    format: z.ZodDefault<z.ZodEnum<{
+        dot: "dot";
+        mermaid: "mermaid";
+    }>>;
+    seedIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    layout: z.ZodDefault<z.ZodEnum<{
+        TD: "TD";
+        BT: "BT";
+        RL: "RL";
+        LR: "LR";
+    }>>;
+    labelMode: z.ZodDefault<z.ZodEnum<{
+        friendly: "friendly";
+        compact: "compact";
+    }>>;
+}, z.core.$strip>, z.ZodString>;

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

@@ -0,0 +1,97 @@
+import * as z from "zod";
+import { defineOperation } from "./define-operation.js";
+import { SysProMDocument } from "../schema.js";
+import { sanitiseMermaidId, mermaidShapeForNode, renderMermaidNode, renderMermaidClassDefs, mermaidClassForNode, dotNodeAttrsWithMode, renderRelationshipLabel, } from "./graph-shared.js";
+const REFINEMENT_REL_TYPES = new Set(["refines", "realises", "implements"]);
+function collectRefinementChain(doc, seedIds) {
+    const rels = (doc.relationships ?? []).filter((r) => REFINEMENT_REL_TYPES.has(r.type));
+    if (seedIds && seedIds.length > 0) {
+        const reachable = new Set(seedIds);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const r of rels) {
+                if (reachable.has(r.from) && !reachable.has(r.to)) {
+                    reachable.add(r.to);
+                    changed = true;
+                }
+                if (reachable.has(r.to) && !reachable.has(r.from)) {
+                    reachable.add(r.from);
+                    changed = true;
+                }
+            }
+        }
+        const filteredRels = rels.filter((r) => reachable.has(r.from) && reachable.has(r.to));
+        const nodes = doc.nodes.filter((n) => reachable.has(n.id));
+        return { nodes, rels: filteredRels };
+    }
+    const nodeIds = new Set(rels.flatMap((r) => [r.from, r.to]));
+    const nodes = doc.nodes.filter((n) => nodeIds.has(n.id));
+    return { nodes, rels };
+}
+function generateRefinementMermaid(nodes, rels, labelMode) {
+    const lines = [];
+    lines.push("graph TD");
+    for (const def of renderMermaidClassDefs()) {
+        lines.push(`  ${def}`);
+    }
+    lines.push("");
+    for (const node of nodes) {
+        const shape = mermaidShapeForNode(node);
+        const cls = mermaidClassForNode(node);
+        lines.push(`  ${renderMermaidNode(node.id, node.name, shape, labelMode)}:::${cls}`);
+    }
+    lines.push("");
+    for (const rel of rels) {
+        const fromId = sanitiseMermaidId(rel.from);
+        const toId = sanitiseMermaidId(rel.to);
+        const label = renderRelationshipLabel(rel);
+        lines.push(`  ${fromId} -->|${label}| ${toId}`);
+    }
+    return lines.join("\n");
+}
+function generateRefinementDot(nodes, rels, layout, labelMode) {
+    const lines = [];
+    lines.push("digraph RefinementChain {");
+    const rankdir = layout === "TD"
+        ? "TB"
+        : layout === "BT"
+            ? "BT"
+            : layout === "RL"
+                ? "RL"
+                : "LR";
+    lines.push(`  rankdir=${rankdir};`);
+    lines.push("  node [style=filled];");
+    for (const node of nodes) {
+        lines.push(`  "${node.id}" ${dotNodeAttrsWithMode(node, labelMode)};`);
+    }
+    for (const rel of rels) {
+        const label = renderRelationshipLabel(rel);
+        lines.push(`  "${rel.from}" -> "${rel.to}" [label="${label}"];`);
+    }
+    lines.push("}");
+    return lines.join("\n");
+}
+/** Generate a refinement chain diagram showing how nodes elaborate through abstraction layers. */
+export const graphRefinementOp = defineOperation({
+    name: "graphRefinement",
+    description: "Generate a refinement chain diagram showing intent → concept → capability → element → realisation relationships.",
+    input: z.object({
+        doc: SysProMDocument,
+        format: z.enum(["mermaid", "dot"]).default("mermaid"),
+        seedIds: z.array(z.string()).optional(),
+        layout: z.enum(["LR", "TD", "RL", "BT"]).default("TD"),
+        labelMode: z.enum(["friendly", "compact"]).default("friendly"),
+    }),
+    output: z.string(),
+    fn({ doc, format, seedIds, layout, labelMode }) {
+        const { nodes, rels } = collectRefinementChain(doc, seedIds);
+        if (format === "dot") {
+            return generateRefinementDot(nodes, rels, layout, labelMode);
+        }
+        const mermaid = generateRefinementMermaid(nodes, rels, labelMode);
+        const mermaidLines = mermaid.split("\n");
+        mermaidLines[0] = `graph ${layout}`;
+        return mermaidLines.join("\n");
+    },
+});

package/dist/src/operations/graph-shared.d.ts

@@ -0,0 +1,116 @@
+import { type Node, type Relationship } from "../schema.js";
+/**
+ * Sanitise an identifier for use in Mermaid diagrams by replacing
+ * non-alphanumeric/underscore characters with an underscore.
+ * @param id - Identifier to sanitise
+ * @example
+ * // sanitiseMermaidId('I1:Name') // 'I1_Name'
+ */
+export declare function sanitiseMermaidId(id: string): string;
+/**
+ *
+ */
+export interface NodeCategory {
+    name: string;
+    label: string;
+    types: string[];
+    colour: string;
+    textColour: string;
+}
+export declare const NODE_CATEGORIES: NodeCategory[];
+/**
+ * Return the category for a given node. Falls back to the last category
+ * if the node type is unknown.
+ * @param node - Node to obtain category for
+ * @example
+ * // categoryForNode(node).name
+ */
+export declare function categoryForNode(node: Node): NodeCategory;
+/**
+ * Return the category for a node type.
+ * @param type - Node type string
+ * @example
+ * // categoryForType('intent').name // 'intent'
+ */
+export declare function categoryForType(type: string): NodeCategory;
+/**
+ *
+ */
+export type MermaidShape = "rounded" | "rectangle" | "rhombus" | "parallelogram";
+/**
+ * Map a node to its Mermaid shape.
+ * @param node - Node to determine shape for
+ * @example
+ */
+export declare function mermaidShapeForNode(node: Node): MermaidShape;
+/**
+ * Render a Mermaid node definition for a node id/name/shape.
+ * @param id - Node id
+ * @param name - Node name
+ * @param shape - Shape to render
+ * @param mode - Label mode, friendly shows id and name, compact shows id only
+ * @example
+ */
+export declare function renderMermaidNode(id: string, name: string, shape: MermaidShape, mode?: "friendly" | "compact"): string;
+/**
+ * Render a human-friendly relationship label including polarity and strength
+ * @param rel
+ * @example
+ */
+export declare function renderRelationshipLabel(rel: Relationship): string;
+/**
+ * @example
+ */
+export declare function renderMermaidClassDefs(): string[];
+/**
+ * @param node
+ * @example
+ */
+export declare function mermaidClassForNode(node: Node): string;
+/**
+ * @param node
+ * @example
+ */
+export declare function dotNodeAttrs(node: Node): string;
+/**
+ * Format a node label according to a mode. "friendly" shows id and name,
+ * "compact" shows only the id.
+ * @param node
+ * @param mode
+ * @example
+ */
+export declare function formatNodeLabel(node: Node, mode: "friendly" | "compact"): string;
+/**
+ * @param node
+ * @param mode
+ * @example
+ */
+export declare function dotNodeAttrsWithMode(node: Node, mode?: "friendly" | "compact"): string;
+/**
+ *
+ */
+export interface GraphFilterOptions {
+    nodeTypes?: string[];
+    nodeIds?: string[];
+    relTypes?: string[];
+    connectedOnly?: boolean;
+}
+/**
+ * @param nodes
+ * @param opts
+ * @example
+ */
+export declare function filterNodes(nodes: Node[], opts: GraphFilterOptions): Node[];
+/**
+ * @param rels
+ * @param opts
+ * @param allowedNodeIds
+ * @example
+ */
+export declare function filterRelationships(rels: Relationship[], opts: GraphFilterOptions, allowedNodeIds?: Set<string>): Relationship[];
+/**
+ * @param nodes
+ * @param rels
+ * @example
+ */
+export declare function applyConnectedOnly(nodes: Node[], rels: Relationship[]): Node[];