sysprom 1.7.0 → 1.7.1

package/dist/src/endpoint-types.d.ts

@@ -12,9 +12,13 @@ export declare const RELATIONSHIP_ENDPOINT_TYPES: Record<RelationshipType, {
 }>;
 /**
  * Check if a relationship type is valid for the given endpoint node types.
- * @param relType The relationship type
- * @param fromType The source node type
- * @param toType The target node type
+ * @param relType - The relationship type
+ * @param fromType - The source node type
+ * @param toType - The target node type
  * @returns true if the endpoint types are valid for this relationship
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 export declare function isValidEndpointPair(relType: RelationshipType, fromType: NodeType, toType: NodeType): boolean;

package/dist/src/endpoint-types.js

@@ -288,16 +288,16 @@ export const RELATIONSHIP_ENDPOINT_TYPES = {
 };
 /**
  * Check if a relationship type is valid for the given endpoint node types.
- * @param relType The relationship type
- * @param fromType The source node type
- * @param toType The target node type
+ * @param relType - The relationship type
+ * @param fromType - The source node type
+ * @param toType - The target node type
  * @returns true if the endpoint types are valid for this relationship
+ * @example
+ * ```ts
+ * isValidEndpointPair("refines", "intent", "concept") // true
+ * ```
  */
 export function isValidEndpointPair(relType, fromType, toType) {
     const endpoints = RELATIONSHIP_ENDPOINT_TYPES[relType];
-    if (!endpoints) {
-        // Unknown relationship type — should be caught by schema validation
-        return false;
-    }
-    return (endpoints.from.includes(fromType) && endpoints.to.includes(toType));
+    return endpoints.from.includes(fromType) && endpoints.to.includes(toType);
 }

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

@@ -35,7 +35,15 @@ function parseText(raw) {
     const lines = raw.split("\n");
     return lines.length === 1 ? lines[0] : lines;
 }
-/** Separate $schema from front matter so it becomes a top-level document key. */
+/**
+ * Separate $schema from front matter so it becomes a top-level document key.
+ * @param front - The front matter object
+ * @returns An object with extracted schema and remaining metadata
+ * @example
+ * ```ts
+ * const { schema, metadata } = extractSchema({ $schema: "...", foo: "bar" });
+ * ```
+ */
 function extractSchema(front) {
     const schema = typeof front.$schema === "string" ? front.$schema : undefined;
     const metadata = { ...front };

package/dist/src/sync.d.ts

@@ -12,15 +12,18 @@ export interface DetectionResult {
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export declare function detectChanges(jsonPath: string, mdPath: string): DetectionResult;

package/dist/src/sync.js

@@ -5,31 +5,38 @@ import { SysProMDocument } from "./schema.js";
 /**
  * Compute a normalised hash of a document for comparison.
  * Uses canonical JSON representation.
- * @param doc The SysProM document
+ * @param doc - The SysProM document
  * @returns SHA256 hash of the canonicalised document
+ * @example
+ * ```ts
+ * const hash = normaliseHash({ nodes: [], relationships: [] });
+ * ```
  */
 function normaliseHash(doc) {
-    const sorted = JSON.stringify(doc, Object.keys(doc).sort());
+    const keys = doc && typeof doc === "object" ? Object.keys(doc).sort() : [];
+    const sorted = JSON.stringify(doc, keys);
     return createHash("sha256").update(sorted).digest("hex");
 }
 /**
  * Detect whether JSON and/or Markdown have changed.
  * Strategy:
- * 1. Parse both JSON and Markdown to document objects
- * 2. If documents are identical → no change
- * 3. If documents differ:
- *    - Use file modification times to determine which was edited more recently
- *    - The newer file is considered the "changed" one
- *    - If modification times are very close (< 100ms), treat as conflict
- *
- * @param jsonPath Path to JSON file
- * @param mdPath Path to Markdown file (single or multi-doc)
+ * 1. Parse both JSON and Markdown to document objects.
+ * 2. If documents are identical, no change.
+ * 3. If documents differ, use file modification times to determine which was
+ *    edited more recently. The newer file is considered the "changed" one.
+ *    If modification times are very close (< 100ms), treat as conflict.
+ * @param jsonPath - Path to JSON file
+ * @param mdPath - Path to Markdown file (single or multi-doc)
  * @returns Detection result with jsonChanged, mdChanged, and conflict flags
+ * @example
+ * ```ts
+ * const result = detectChanges("doc.spm.json", "doc.spm.md");
+ * if (result.conflict) throw new Error("Both files changed");
+ * ```
  */
 export function detectChanges(jsonPath, mdPath) {
     // Read files
     const jsonContent = readFileSync(jsonPath, "utf8");
-    const mdContent = readFileSync(mdPath, "utf8");
     // Parse JSON
     const jsonDoc = JSON.parse(jsonContent);
     if (!SysProMDocument.is(jsonDoc)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sysprom",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "SysProM — System Provenance Model CLI and library",
   "author": "ExaDev",
   "homepage": "https://exadev.github.io/SysProM",