sysprom 1.0.0 → 1.0.6

package/dist/src/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * SysProM — System Provenance Model
+ *
+ * A recursive, decision-driven model for recording where every part of a
+ * system came from, what decisions shaped it, and how it reached its current form.
+ *
+ * @packageDocumentation
+ */
+import type { SysProMDocument, Node, NodeType, Relationship, RelationshipType } from "./schema.js";
+import type { ValidationResult, DocumentStats, NodeDetail, TraceNode, RemoveResult, TimelineEvent, NodeState } from "./operations/index.js";
+export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, toJSONSchema, } from "./schema.js";
+export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, type ConvertOptions, } from "./json-to-md.js";
+export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";
+export { validateOp, type ValidationResult } from "./operations/index.js";
+export { statsOp, type DocumentStats } from "./operations/index.js";
+export { queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, type NodeDetail, type TraceNode, } from "./operations/index.js";
+export { nextIdOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, addPlanTaskOp, updatePlanTaskOp, type RemoveResult, } from "./operations/index.js";
+export declare function validate(doc: SysProMDocument): ValidationResult;
+export declare function stats(doc: SysProMDocument): DocumentStats;
+export declare function queryNodes(doc: SysProMDocument, filters?: {
+    type?: string;
+    status?: string;
+}): Node[];
+export declare function queryNode(doc: SysProMDocument, id: string): NodeDetail | undefined;
+export declare function queryRelationships(doc: SysProMDocument, filters?: {
+    from?: string;
+    to?: string;
+    type?: string;
+}): Relationship[];
+export declare function traceFromNode(doc: SysProMDocument, startId: string): TraceNode;
+export declare function nextId(doc: SysProMDocument, type: NodeType): string;
+export declare function addNode(doc: SysProMDocument, node: Node): SysProMDocument;
+export declare function removeNode(doc: SysProMDocument, id: string): RemoveResult;
+export declare function updateNode(doc: SysProMDocument, id: string, fields: Partial<Node>): SysProMDocument;
+export declare function addRelationship(doc: SysProMDocument, rel: Relationship): SysProMDocument;
+export declare function removeRelationship(doc: SysProMDocument, from: string, type: RelationshipType, to: string): SysProMDocument;
+export declare function updateMetadata(doc: SysProMDocument, fields: Record<string, unknown>): SysProMDocument;
+export declare function addPlanTask(doc: SysProMDocument, changeId: string, description: string): SysProMDocument;
+export declare function updatePlanTask(doc: SysProMDocument, changeId: string, taskIndex: number, done: boolean): SysProMDocument;
+export { canonicalise, type FormatOptions } from "./canonical-json.js";
+export { textToString, textToLines, textToMarkdown, markdownToText, } from "./text.js";
+export { loadDocument, saveDocument, type Format, type LoadedDocument, } from "./io.js";
+export { detectSpecKitProject, listFeatures, getFeature, resolveConstitution, type SpecKitProject, type SpecKitFeature, parseConstitution, parseSpec, parsePlan, parseTasks, parseChecklist, parseSpecKitFeature, generateConstitution, generateSpec, generatePlan, generateTasks, generateChecklist, generateSpecKitProject, type ParseResult, } from "./speckit/index.js";
+export { timelineOp, nodeHistoryOp, stateAtOp, type TimelineEvent, type NodeState, } from "./operations/index.js";
+export declare function timeline(doc: SysProMDocument): TimelineEvent[];
+export declare function nodeHistory(doc: SysProMDocument, nodeId: string): TimelineEvent[];
+export declare function stateAt(doc: SysProMDocument, timestamp: string): NodeState[];
+export { defineOperation, type OperationDef, type DefinedOperation, searchOp, checkOp, graphOp, renameOp, } from "./operations/index.js";

package/dist/src/index.js

@@ -0,0 +1,99 @@
+/**
+ * SysProM — System Provenance Model
+ *
+ * A recursive, decision-driven model for recording where every part of a
+ * system came from, what decisions shaped it, and how it reached its current form.
+ *
+ * @packageDocumentation
+ */
+import { validateOp, statsOp, queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, nextIdOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, addPlanTaskOp, updatePlanTaskOp, timelineOp, nodeHistoryOp, stateAtOp, } from "./operations/index.js";
+// Schema types and validators (const and type share the same name)
+export { SysProMDocument, Node, Relationship, NodeType, NodeStatus, RelationshipType, Text, Option, Operation, Task, ExternalReference, ExternalReferenceRole, Metadata, 
+// Labels
+NODE_TYPE_LABELS, NODE_LABEL_TO_TYPE, RELATIONSHIP_TYPE_LABELS, RELATIONSHIP_LABEL_TO_TYPE, EXTERNAL_REFERENCE_ROLE_LABELS, EXTERNAL_REFERENCE_LABEL_TO_ROLE, NODE_STATUSES, NODE_FILE_MAP, NODE_ID_PREFIX, 
+// Schema generator
+toJSONSchema, } from "./schema.js";
+// Converters: JSON to Markdown
+export { jsonToMarkdownSingle, jsonToMarkdownMultiDoc, jsonToMarkdown, } from "./json-to-md.js";
+// Converters: Markdown to JSON
+export { markdownSingleToJson, markdownMultiDocToJson, markdownToJson, } from "./md-to-json.js";
+// Validation
+export { validateOp } from "./operations/index.js";
+// Stats
+export { statsOp } from "./operations/index.js";
+// Query
+export { queryNodesOp, queryNodeOp, queryRelationshipsOp, traceFromNodeOp, } from "./operations/index.js";
+// Mutation
+export { nextIdOp, addNodeOp, removeNodeOp, updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, addPlanTaskOp, updatePlanTaskOp, } from "./operations/index.js";
+// Convenience wrappers for backwards compatibility
+export function validate(doc) {
+    return validateOp({ doc });
+}
+export function stats(doc) {
+    return statsOp({ doc });
+}
+export function queryNodes(doc, filters) {
+    return queryNodesOp({ doc, type: filters?.type, status: filters?.status });
+}
+export function queryNode(doc, id) {
+    return queryNodeOp({ doc, id }) ?? undefined;
+}
+export function queryRelationships(doc, filters) {
+    return queryRelationshipsOp({
+        doc,
+        from: filters?.from,
+        to: filters?.to,
+        type: filters?.type,
+    });
+}
+export function traceFromNode(doc, startId) {
+    return traceFromNodeOp({ doc, startId });
+}
+export function nextId(doc, type) {
+    return nextIdOp({ doc, type });
+}
+export function addNode(doc, node) {
+    return addNodeOp({ doc, node });
+}
+export function removeNode(doc, id) {
+    return removeNodeOp({ doc, id });
+}
+export function updateNode(doc, id, fields) {
+    return updateNodeOp({ doc, id, fields });
+}
+export function addRelationship(doc, rel) {
+    return addRelationshipOp({ doc, rel });
+}
+export function removeRelationship(doc, from, type, to) {
+    return removeRelationshipOp({ doc, from, type, to });
+}
+export function updateMetadata(doc, fields) {
+    return updateMetadataOp({ doc, fields });
+}
+export function addPlanTask(doc, changeId, description) {
+    return addPlanTaskOp({ doc, changeId, description });
+}
+export function updatePlanTask(doc, changeId, taskIndex, done) {
+    return updatePlanTaskOp({ doc, changeId, taskIndex, done });
+}
+// Utilities
+export { canonicalise } from "./canonical-json.js";
+export { textToString, textToLines, textToMarkdown, markdownToText, } from "./text.js";
+// IO
+export { loadDocument, saveDocument, } from "./io.js";
+// Spec-Kit interoperability
+export { detectSpecKitProject, listFeatures, getFeature, resolveConstitution, parseConstitution, parseSpec, parsePlan, parseTasks, parseChecklist, parseSpecKitFeature, generateConstitution, generateSpec, generatePlan, generateTasks, generateChecklist, generateSpecKitProject, } from "./speckit/index.js";
+// Temporal query
+export { timelineOp, nodeHistoryOp, stateAtOp, } from "./operations/index.js";
+// Convenience wrappers for temporal
+export function timeline(doc) {
+    return timelineOp({ doc });
+}
+export function nodeHistory(doc, nodeId) {
+    return nodeHistoryOp({ doc, nodeId });
+}
+export function stateAt(doc, timestamp) {
+    return stateAtOp({ doc, timestamp });
+}
+// Operations (single source of truth for domain logic + metadata)
+export { defineOperation, searchOp, checkOp, graphOp, renameOp, } from "./operations/index.js";

package/dist/src/io.d.ts

@@ -0,0 +1,22 @@
+import { SysProMDocument } from "./schema.js";
+export type Format = "json" | "single-md" | "multi-md";
+export interface LoadedDocument {
+    doc: SysProMDocument;
+    format: Format;
+    path: string;
+}
+/**
+ * Load a SysProM document from a file (JSON or Markdown).
+ *
+ * @param input - File path or directory to load from.
+ * @returns The loaded document with its detected format and resolved path.
+ */
+export declare function loadDocument(input: string): LoadedDocument;
+/**
+ * Save a SysProM document to a file (JSON or Markdown).
+ *
+ * @param doc - The SysProM document to save.
+ * @param format - Output format: 'json', 'single-md', or 'multi-md'.
+ * @param path - Destination file path or directory.
+ */
+export declare function saveDocument(doc: SysProMDocument, format: Format, path: string): void;

package/dist/src/io.js

@@ -0,0 +1,66 @@
+import { readFileSync, writeFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { SysProMDocument } from "./schema.js";
+import { markdownSingleToJson, markdownMultiDocToJson } from "./md-to-json.js";
+import { jsonToMarkdownSingle, jsonToMarkdownMultiDoc } from "./json-to-md.js";
+import { canonicalise } from "./canonical-json.js";
+function detectFormat(input) {
+    const stat = statSync(input);
+    if (stat.isDirectory())
+        return "multi-md";
+    if (input.endsWith(".json"))
+        return "json";
+    return "single-md";
+}
+/**
+ * Load a SysProM document from a file (JSON or Markdown).
+ *
+ * @param input - File path or directory to load from.
+ * @returns The loaded document with its detected format and resolved path.
+ */
+export function loadDocument(input) {
+    const path = resolve(input);
+    const format = detectFormat(path);
+    let doc;
+    switch (format) {
+        case "json": {
+            const raw = JSON.parse(readFileSync(path, "utf8"));
+            const result = SysProMDocument.safeParse(raw);
+            if (!result.success) {
+                throw new Error(`Invalid SysProM document:\n${result.error.issues.map((i) => `  ${i.path.join(".")}: ${i.message}`).join("\n")}`);
+            }
+            doc = result.data;
+            break;
+        }
+        case "single-md": {
+            const content = readFileSync(path, "utf8");
+            doc = markdownSingleToJson(content);
+            break;
+        }
+        case "multi-md": {
+            doc = markdownMultiDocToJson(path);
+            break;
+        }
+    }
+    return { doc, format, path };
+}
+/**
+ * Save a SysProM document to a file (JSON or Markdown).
+ *
+ * @param doc - The SysProM document to save.
+ * @param format - Output format: 'json', 'single-md', or 'multi-md'.
+ * @param path - Destination file path or directory.
+ */
+export function saveDocument(doc, format, path) {
+    switch (format) {
+        case "json":
+            writeFileSync(path, canonicalise(doc, { indent: "\t" }) + "\n");
+            break;
+        case "single-md":
+            writeFileSync(path, jsonToMarkdownSingle(doc));
+            break;
+        case "multi-md":
+            jsonToMarkdownMultiDoc(doc, path);
+            break;
+    }
+}

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

@@ -0,0 +1,26 @@
+import { type SysProMDocument } from "./schema.js";
+export interface ConvertOptions {
+    form: "single-file" | "multi-doc";
+}
+/**
+ * Convert a SysProM document to a single Markdown string.
+ *
+ * @param doc - The SysProM document to convert.
+ * @returns The Markdown representation.
+ */
+export declare function jsonToMarkdownSingle(doc: SysProMDocument): string;
+/**
+ * Convert a SysProM document to a multi-document Markdown folder.
+ *
+ * @param doc - The SysProM document to convert.
+ * @param outDir - Output directory path.
+ */
+export declare function jsonToMarkdownMultiDoc(doc: SysProMDocument, outDir: string): void;
+/**
+ * Convert a SysProM document to Markdown, writing to the specified output path.
+ *
+ * @param doc - The SysProM document to convert.
+ * @param output - Output file or directory path.
+ * @param options - Conversion options specifying single-file or multi-doc form.
+ */
+export declare function jsonToMarkdown(doc: SysProMDocument, output: string, options: ConvertOptions): void;