sysprom 1.0.0 → 1.0.6

package/dist/schema.json

@@ -0,0 +1,510 @@
+{
+    "$id": "https://sysprom.org/schema.json",
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "additionalProperties": false,
+    "description": "JSON Schema for SysProM — a recursive, decision-driven model for recording system provenance.",
+    "id": "SysProM",
+    "properties": {
+        "$schema": {
+            "description": "Schema URI for self-identification.",
+            "type": "string"
+        },
+        "external_references": {
+            "description": "References to resources outside the graph, declared at system level.",
+            "items": {
+                "additionalProperties": false,
+                "description": "A reference to a resource outside the SysProM graph.",
+                "properties": {
+                    "description": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ]
+                    },
+                    "identifier": {
+                        "description": "Serialisation-specific identifier (URI, file path, DOI, etc.).",
+                        "type": "string"
+                    },
+                    "internalised": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ],
+                        "description": "Inline content captured from the external resource. When present, the node is self-contained and does not depend on the external identifier being resolvable."
+                    },
+                    "node_id": {
+                        "description": "ID of the node this reference belongs to. Used when the reference is declared at graph level rather than inline on the node.",
+                        "type": "string"
+                    },
+                    "role": {
+                        "enum": [
+                            "input",
+                            "output",
+                            "context",
+                            "evidence",
+                            "source",
+                            "standard",
+                            "prior_art"
+                        ],
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "role",
+                    "identifier"
+                ],
+                "type": "object"
+            },
+            "type": "array"
+        },
+        "metadata": {
+            "additionalProperties": {},
+            "description": "Document-level metadata. Analogous to front matter in Markdown.",
+            "properties": {
+                "doc_type": {
+                    "description": "Document type. Use 'sysprom' for the root entry point. Subsystems and features may use other values.",
+                    "type": "string"
+                },
+                "scope": {
+                    "description": "The scope of this document (e.g. system, feature, component).",
+                    "type": "string"
+                },
+                "status": {
+                    "type": "string"
+                },
+                "title": {
+                    "type": "string"
+                },
+                "version": {
+                    "anyOf": [
+                        {
+                            "type": "string"
+                        },
+                        {
+                            "maximum": 9007199254740991,
+                            "minimum": -9007199254740991,
+                            "type": "integer"
+                        }
+                    ]
+                }
+            },
+            "type": "object"
+        },
+        "nodes": {
+            "description": "All nodes in the graph.",
+            "items": {
+                "additionalProperties": {},
+                "description": "A uniquely identifiable entity within the system.",
+                "properties": {
+                    "context": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ],
+                        "description": "Background context explaining why this node exists or why a decision was needed."
+                    },
+                    "description": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ]
+                    },
+                    "external_references": {
+                        "description": "External resources related to this node.",
+                        "items": {
+                            "additionalProperties": false,
+                            "description": "A reference to a resource outside the SysProM graph.",
+                            "properties": {
+                                "description": {
+                                    "anyOf": [
+                                        {
+                                            "type": "string"
+                                        },
+                                        {
+                                            "items": {
+                                                "type": "string"
+                                            },
+                                            "type": "array"
+                                        }
+                                    ]
+                                },
+                                "identifier": {
+                                    "description": "Serialisation-specific identifier (URI, file path, DOI, etc.).",
+                                    "type": "string"
+                                },
+                                "internalised": {
+                                    "anyOf": [
+                                        {
+                                            "type": "string"
+                                        },
+                                        {
+                                            "items": {
+                                                "type": "string"
+                                            },
+                                            "type": "array"
+                                        }
+                                    ],
+                                    "description": "Inline content captured from the external resource. When present, the node is self-contained and does not depend on the external identifier being resolvable."
+                                },
+                                "node_id": {
+                                    "description": "ID of the node this reference belongs to. Used when the reference is declared at graph level rather than inline on the node.",
+                                    "type": "string"
+                                },
+                                "role": {
+                                    "enum": [
+                                        "input",
+                                        "output",
+                                        "context",
+                                        "evidence",
+                                        "source",
+                                        "standard",
+                                        "prior_art"
+                                    ],
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "role",
+                                "identifier"
+                            ],
+                            "type": "object"
+                        },
+                        "type": "array"
+                    },
+                    "id": {
+                        "description": "Unique identifier for this node.",
+                        "type": "string"
+                    },
+                    "includes": {
+                        "description": "IDs of nodes included in this projection. Applicable to view nodes.",
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array"
+                    },
+                    "input": {
+                        "description": "ID of the input artefact. Applicable to artefact_flow nodes.",
+                        "type": "string"
+                    },
+                    "lifecycle": {
+                        "additionalProperties": {
+                            "anyOf": [
+                                {
+                                    "type": "boolean"
+                                },
+                                {
+                                    "type": "string"
+                                }
+                            ]
+                        },
+                        "description": "Map of lifecycle state names to completion status. Values may be boolean or an ISO date string indicating when the state was reached.",
+                        "propertyNames": {
+                            "type": "string"
+                        },
+                        "type": "object"
+                    },
+                    "name": {
+                        "description": "Human-readable name.",
+                        "type": "string"
+                    },
+                    "operations": {
+                        "description": "Operations performed. Applicable to change nodes.",
+                        "items": {
+                            "additionalProperties": {},
+                            "description": "An atomic operation within a change.",
+                            "properties": {
+                                "description": {
+                                    "anyOf": [
+                                        {
+                                            "type": "string"
+                                        },
+                                        {
+                                            "items": {
+                                                "type": "string"
+                                            },
+                                            "type": "array"
+                                        }
+                                    ]
+                                },
+                                "target": {
+                                    "description": "ID of the affected node.",
+                                    "type": "string"
+                                },
+                                "type": {
+                                    "enum": [
+                                        "add",
+                                        "update",
+                                        "remove",
+                                        "link"
+                                    ],
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "type"
+                            ],
+                            "type": "object"
+                        },
+                        "type": "array"
+                    },
+                    "options": {
+                        "description": "Alternatives considered. Applicable to decision nodes.",
+                        "items": {
+                            "additionalProperties": {},
+                            "description": "An alternative considered as part of a decision.",
+                            "properties": {
+                                "description": {
+                                    "anyOf": [
+                                        {
+                                            "type": "string"
+                                        },
+                                        {
+                                            "items": {
+                                                "type": "string"
+                                            },
+                                            "type": "array"
+                                        }
+                                    ]
+                                },
+                                "id": {
+                                    "type": "string"
+                                }
+                            },
+                            "required": [
+                                "id",
+                                "description"
+                            ],
+                            "type": "object"
+                        },
+                        "type": "array"
+                    },
+                    "output": {
+                        "description": "ID of the output artefact. Applicable to artefact_flow nodes.",
+                        "type": "string"
+                    },
+                    "plan": {
+                        "description": "Execution plan as a sequence of tasks. Applicable to change nodes.",
+                        "items": {
+                            "additionalProperties": {},
+                            "description": "A single task within a change's execution plan.",
+                            "properties": {
+                                "description": {
+                                    "anyOf": [
+                                        {
+                                            "type": "string"
+                                        },
+                                        {
+                                            "items": {
+                                                "type": "string"
+                                            },
+                                            "type": "array"
+                                        }
+                                    ]
+                                },
+                                "done": {
+                                    "default": false,
+                                    "type": "boolean"
+                                }
+                            },
+                            "required": [
+                                "description"
+                            ],
+                            "type": "object"
+                        },
+                        "type": "array"
+                    },
+                    "propagation": {
+                        "additionalProperties": {
+                            "type": "boolean"
+                        },
+                        "description": "Layer propagation status. Applicable to change nodes.",
+                        "propertyNames": {
+                            "type": "string"
+                        },
+                        "type": "object"
+                    },
+                    "rationale": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ],
+                        "description": "Reasoning for the choice. Applicable to decision nodes."
+                    },
+                    "scope": {
+                        "description": "IDs of nodes affected by this change. Applicable to change nodes.",
+                        "items": {
+                            "type": "string"
+                        },
+                        "type": "array"
+                    },
+                    "selected": {
+                        "description": "ID of the chosen option. Applicable to decision nodes.",
+                        "type": "string"
+                    },
+                    "status": {
+                        "enum": [
+                            "proposed",
+                            "accepted",
+                            "active",
+                            "implemented",
+                            "adopted",
+                            "defined",
+                            "introduced",
+                            "in_progress",
+                            "complete",
+                            "consolidated",
+                            "experimental",
+                            "deprecated",
+                            "retired",
+                            "superseded",
+                            "abandoned",
+                            "deferred"
+                        ],
+                        "type": "string"
+                    },
+                    "subsystem": {
+                        "$ref": "#"
+                    },
+                    "type": {
+                        "enum": [
+                            "intent",
+                            "concept",
+                            "capability",
+                            "element",
+                            "realisation",
+                            "invariant",
+                            "principle",
+                            "policy",
+                            "protocol",
+                            "stage",
+                            "role",
+                            "gate",
+                            "mode",
+                            "artefact",
+                            "artefact_flow",
+                            "decision",
+                            "change",
+                            "view",
+                            "milestone",
+                            "version"
+                        ],
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "id",
+                    "type",
+                    "name"
+                ],
+                "type": "object"
+            },
+            "type": "array"
+        },
+        "relationships": {
+            "description": "Typed, directed connections between nodes.",
+            "items": {
+                "additionalProperties": {},
+                "description": "A typed, directed connection between two nodes.",
+                "properties": {
+                    "description": {
+                        "anyOf": [
+                            {
+                                "type": "string"
+                            },
+                            {
+                                "items": {
+                                    "type": "string"
+                                },
+                                "type": "array"
+                            }
+                        ]
+                    },
+                    "from": {
+                        "description": "Source node ID.",
+                        "type": "string"
+                    },
+                    "to": {
+                        "description": "Target node ID.",
+                        "type": "string"
+                    },
+                    "type": {
+                        "enum": [
+                            "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"
+                        ],
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "from",
+                    "to",
+                    "type"
+                ],
+                "type": "object"
+            },
+            "type": "array"
+        }
+    },
+    "required": [
+        "nodes"
+    ],
+    "title": "SysProM: System Provenance Model",
+    "type": "object"
+}

package/dist/src/canonical-json.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @module canonical-json
+ *
+ * JSON serialisation with RFC 8785 key ordering and value semantics,
+ * optionally pretty-printed with configurable indentation.
+ *
+ * - Object keys sorted by Unicode code point order
+ * - Numbers formatted per ECMAScript toString()
+ * - Strings escaped per JSON spec
+ * - null, true, false as literals
+ * - undefined values omitted from objects
+ */
+export interface FormatOptions {
+    indent?: string;
+}
+/**
+ * Serialise a value to canonical JSON with RFC 8785 key ordering.
+ *
+ * @param value - The value to serialise.
+ * @param options - Formatting options (e.g. indentation).
+ * @returns The canonical JSON string.
+ */
+export declare function canonicalise(value: unknown, options?: FormatOptions): string;

package/dist/src/canonical-json.js

@@ -0,0 +1,120 @@
+/**
+ * @module canonical-json
+ *
+ * JSON serialisation with RFC 8785 key ordering and value semantics,
+ * optionally pretty-printed with configurable indentation.
+ *
+ * - Object keys sorted by Unicode code point order
+ * - Numbers formatted per ECMAScript toString()
+ * - Strings escaped per JSON spec
+ * - null, true, false as literals
+ * - undefined values omitted from objects
+ */
+/**
+ * Serialise a value to canonical JSON with RFC 8785 key ordering.
+ *
+ * @param value - The value to serialise.
+ * @param options - Formatting options (e.g. indentation).
+ * @returns The canonical JSON string.
+ */
+export function canonicalise(value, options = {}) {
+    const indent = options.indent ?? "";
+    return serialise(value, indent, 0);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function serialise(value, indent, depth) {
+    if (value === null)
+        return "null";
+    if (value === true)
+        return "true";
+    if (value === false)
+        return "false";
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new Error("Non-finite numbers are not serialisable");
+        }
+        return Object.is(value, -0) ? "0" : String(value);
+    }
+    if (typeof value === "string") {
+        return serialiseString(value);
+    }
+    if (Array.isArray(value)) {
+        return serialiseArray(value, indent, depth);
+    }
+    if (isRecord(value)) {
+        return serialiseObject(value, indent, depth);
+    }
+    throw new Error(`Unserialisable type: ${typeof value}`);
+}
+function serialiseArray(value, indent, depth) {
+    if (value.length === 0)
+        return "[]";
+    if (!indent) {
+        return "[" + value.map((v) => serialise(v, indent, depth)).join(",") + "]";
+    }
+    const inner = depth + 1;
+    const pad = indent.repeat(inner);
+    const items = value.map((v) => pad + serialise(v, indent, inner));
+    return "[\n" + items.join(",\n") + "\n" + indent.repeat(depth) + "]";
+}
+function serialiseObject(value, indent, depth) {
+    const keys = Object.keys(value)
+        .filter((k) => value[k] !== undefined)
+        .sort(compareCodePoints);
+    if (keys.length === 0)
+        return "{}";
+    if (!indent) {
+        const entries = keys.map((k) => serialiseString(k) + ":" + serialise(value[k], indent, depth));
+        return "{" + entries.join(",") + "}";
+    }
+    const inner = depth + 1;
+    const pad = indent.repeat(inner);
+    const entries = keys.map((k) => pad + serialiseString(k) + ": " + serialise(value[k], indent, inner));
+    return "{\n" + entries.join(",\n") + "\n" + indent.repeat(depth) + "}";
+}
+function compareCodePoints(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+function serialiseString(value) {
+    let result = '"';
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        switch (code) {
+            case 0x08:
+                result += "\\b";
+                break;
+            case 0x09:
+                result += "\\t";
+                break;
+            case 0x0a:
+                result += "\\n";
+                break;
+            case 0x0c:
+                result += "\\f";
+                break;
+            case 0x0d:
+                result += "\\r";
+                break;
+            case 0x22:
+                result += '\\"';
+                break;
+            case 0x5c:
+                result += "\\\\";
+                break;
+            default:
+                if (code < 0x20) {
+                    result += "\\u" + code.toString(16).padStart(4, "0");
+                }
+                else {
+                    result += value[i];
+                }
+        }
+    }
+    return result + '"';
+}

package/dist/src/cli/commands/add.d.ts

@@ -0,0 +1,22 @@
+import * as z from "zod";
+import type { CommandDef } from "../define-command.js";
+declare const argsSchema: z.ZodObject<{
+    input: z.ZodString;
+    nodeType: z.ZodString;
+}, z.core.$strip>;
+declare const optsSchema: z.ZodObject<{
+    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    sync: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodString>;
+    rationale: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    selected: z.ZodOptional<z.ZodString>;
+    option: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const addCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+export {};