sysprom 1.2.0 → 1.2.2

package/dist/src/operations/next-id.d.ts

@@ -2,8 +2,7 @@ import * as z from "zod";
 /**
  * Generate the next available ID for a given node type. Scans existing node IDs
  * matching the type's conventional prefix and returns `prefix + (max + 1)`.
- *
- * @throws If no ID prefix is defined for the given node type.
+ * @throws {Error} If no ID prefix is defined for the given node type.
  */
 export declare const nextIdOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/next-id.js

@@ -4,8 +4,7 @@ import { SysProMDocument, NodeType, NODE_ID_PREFIX } from "../schema.js";
 /**
  * Generate the next available ID for a given node type. Scans existing node IDs
  * matching the type's conventional prefix and returns `prefix + (max + 1)`.
- *
- * @throws If no ID prefix is defined for the given node type.
+ * @throws {Error} If no ID prefix is defined for the given node type.
  */
 export const nextIdOp = defineOperation({
     name: "nextId",

package/dist/src/operations/remove-node.d.ts

@@ -303,8 +303,7 @@ export type RemoveResult = z.infer<typeof RemoveResult>;
 /**
  * Remove a node and all relationships involving it. Also removes the node from
  * view includes and external references. Warns if scope or operation references remain.
- *
- * @throws If the node ID is not found.
+ * @throws {Error} If the node ID is not found.
  */
 export declare const removeNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/remove-node.js

@@ -9,8 +9,7 @@ export const RemoveResult = z.object({
 /**
  * Remove a node and all relationships involving it. Also removes the node from
  * view includes and external references. Warns if scope or operation references remain.
- *
- * @throws If the node ID is not found.
+ * @throws {Error} If the node ID is not found.
  */
 export const removeNodeOp = defineOperation({
     name: "removeNode",

package/dist/src/operations/remove-relationship.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Remove a relationship matching from, type, and to. Returns a new document without it.
- *
- * @throws If no matching relationship is found.
+ * @throws {Error} If no matching relationship is found.
  */
 export declare const removeRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/remove-relationship.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, RelationshipType } from "../schema.js";
 /**
  * Remove a relationship matching from, type, and to. Returns a new document without it.
- *
- * @throws If no matching relationship is found.
+ * @throws {Error} If no matching relationship is found.
  */
 export const removeRelationshipOp = defineOperation({
     name: "removeRelationship",

package/dist/src/operations/rename.d.ts

@@ -3,8 +3,7 @@ import * as z from "zod";
  * Rename a node ID across all references in the document — the node itself,
  * relationships, scope, includes, operation targets, external references, and
  * recursively into subsystems.
- *
- * @throws If the old ID is not found or the new ID already exists.
+ * @throws {Error} If the old ID is not found or the new ID already exists.
  */
 export declare const renameOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/rename.js

@@ -93,8 +93,7 @@ function renameNodeId(doc, oldId, newId) {
  * Rename a node ID across all references in the document — the node itself,
  * relationships, scope, includes, operation targets, external references, and
  * recursively into subsystems.
- *
- * @throws If the old ID is not found or the new ID already exists.
+ * @throws {Error} If the old ID is not found or the new ID already exists.
  */
 export const renameOp = defineOperation({
     name: "rename",

package/dist/src/operations/task-list.d.ts

@@ -2,8 +2,7 @@ import * as z from "zod";
 /**
  * List tasks across change nodes, optionally filtered by change ID and/or
  * pending status. Returns a flat array of task rows tagged with their parent change node.
- *
- * @throws If a specific changeId is provided but not found.
+ * @throws {Error} If a specific changeId is provided but not found.
  */
 export declare const taskListOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/task-list.js

@@ -11,8 +11,7 @@ const TaskRow = z.object({
 /**
  * List tasks across change nodes, optionally filtered by change ID and/or
  * pending status. Returns a flat array of task rows tagged with their parent change node.
- *
- * @throws If a specific changeId is provided but not found.
+ * @throws {Error} If a specific changeId is provided but not found.
  */
 export const taskListOp = defineOperation({
     name: "taskList",

package/dist/src/operations/update-node.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Update specified fields on a node, merging the provided fields into the existing node.
- *
- * @throws If the node ID is not found.
+ * @throws {Error} If the node ID is not found.
  */
 export declare const updateNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/update-node.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Node } from "../schema.js";
 /**
  * Update specified fields on a node, merging the provided fields into the existing node.
- *
- * @throws If the node ID is not found.
+ * @throws {Error} If the node ID is not found.
  */
 export const updateNodeOp = defineOperation({
     name: "updateNode",

package/dist/src/operations/update-plan-task.d.ts

@@ -1,8 +1,7 @@
 import * as z from "zod";
 /**
  * Set the done status of a task in a change node's plan array. Returns a new document.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export declare const updatePlanTaskOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{

package/dist/src/operations/update-plan-task.js

@@ -3,8 +3,7 @@ import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
 /**
  * Set the done status of a task in a change node's plan array. Returns a new document.
- *
- * @throws If the change node is not found or the task index is out of range.
+ * @throws {Error} If the change node is not found or the task index is out of range.
  */
 export const updatePlanTaskOp = defineOperation({
     name: "updatePlanTask",

package/dist/src/schema.d.ts

@@ -930,6 +930,14 @@ export type Node = z.infer<typeof Node>;
 export declare const NODE_FILE_MAP: Record<string, string[]>;
 /** Conventional ID prefix for each node type. */
 export declare const NODE_ID_PREFIX: Record<string, string>;
-/** Generate the JSON Schema representation of the SysProM document schema. */
+/**
+ * Generate the JSON Schema representation of the SysProM document schema.
+ * @returns The JSON Schema object with Draft 2020-12 metadata.
+ * @example
+ * ```ts
+ * const schema = toJSONSchema();
+ * writeFileSync("schema.json", JSON.stringify(schema, null, 2));
+ * ```
+ */
 export declare function toJSONSchema(): Record<string, unknown>;
 export {};

package/dist/src/schema.js

@@ -371,7 +371,15 @@ export const NODE_ID_PREFIX = {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** Generate the JSON Schema representation of the SysProM document schema. */
+/**
+ * Generate the JSON Schema representation of the SysProM document schema.
+ * @returns The JSON Schema object with Draft 2020-12 metadata.
+ * @example
+ * ```ts
+ * const schema = toJSONSchema();
+ * writeFileSync("schema.json", JSON.stringify(schema, null, 2));
+ * ```
+ */
 export function toJSONSchema() {
     const generated = z.toJSONSchema(SysProMDocument, {
         target: "draft-2020-12",

package/dist/src/speckit/generate.d.ts

@@ -1,13 +1,67 @@
 import type { SysProMDocument } from "../schema.js";
-/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
+/**
+ * Generate a Spec-Kit constitution file from a SysProM document's principles and invariants.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateConstitution(doc, "FEAT");
+ * ```
+ */
 export declare function generateConstitution(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
+/**
+ * Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateSpec(doc, "FEAT");
+ * ```
+ */
 export declare function generateSpec(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
+/**
+ * Generate a Spec-Kit plan file from a SysProM document's phases and milestones.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generatePlan(doc, "FEAT");
+ * ```
+ */
 export declare function generatePlan(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
+/**
+ * Generate a Spec-Kit tasks file from a SysProM document's change nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateTasks(doc, "FEAT");
+ * ```
+ */
 export declare function generateTasks(doc: SysProMDocument, prefix: string): string;
-/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
+/**
+ * Generate a Spec-Kit checklist file from a SysProM document's gate nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateChecklist(doc, "FEAT");
+ * ```
+ */
 export declare function generateChecklist(doc: SysProMDocument, prefix: string): string;
-/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
+/**
+ * Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files.
+ * @param doc - The SysProM document.
+ * @param outputDir - Output directory path.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @example
+ * ```ts
+ * generateSpecKitProject(doc, "./output", "FEAT");
+ * ```
+ */
 export declare function generateSpecKitProject(doc: SysProMDocument, outputDir: string, prefix: string): void;

package/dist/src/speckit/generate.js

@@ -6,18 +6,40 @@ import { textToString } from "../text.js";
 // ============================================================================
 /**
  * Find a single node by ID, or null if not found.
+ * @param doc - The document to search.
+ * @param id - The node ID to find.
+ * @returns The matching node, or null.
+ * @example
+ * ```ts
+ * findNode(doc, "D1")
+ * ```
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
 }
 /**
  * Find all nodes of a specific type.
+ * @param doc - The document to search.
+ * @param type - The node type to filter by.
+ * @returns Matching nodes.
+ * @example
+ * ```ts
+ * const decisions = findNodesByType(doc, "decision");
+ * ```
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
 }
 /**
  * Find relationships from a source node to nodes of a target type.
+ * @param doc - The document to search.
+ * @param fromId - Source node ID.
+ * @param relationType - Optional relationship type filter.
+ * @returns Matching relationships.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsFrom(doc, "D1", "affects");
+ * ```
  */
 function findRelationshipsFrom(doc, fromId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -30,6 +52,14 @@ function findRelationshipsFrom(doc, fromId, relationType) {
 }
 /**
  * Find relationships to a target node.
+ * @param doc - The document to search.
+ * @param toId - Target node ID.
+ * @param relationType - Optional relationship type filter.
+ * @returns Matching relationships.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsTo(doc, "INV1", "must_preserve");
+ * ```
  */
 function findRelationshipsTo(doc, toId, relationType) {
     return (doc.relationships ?? []).filter((r) => {
@@ -43,6 +73,12 @@ function findRelationshipsTo(doc, toId, relationType) {
 /**
  * Extract priority from a node's name, description, or lifecycle fields.
  * Looks for patterns like "P1", "P2", "Priority: P1", etc.
+ * @param node - The node to extract priority from.
+ * @returns Priority string (e.g. "P1").
+ * @example
+ * ```ts
+ * const priority = extractPriority(node);
+ * ```
  */
 function extractPriority(node) {
     const text = [
@@ -57,6 +93,12 @@ function extractPriority(node) {
 }
 /**
  * Extract numeric suffix from an ID (e.g., "PREFIX-SPEC-001" -> "001").
+ * @param id - The node ID.
+ * @returns The numeric suffix.
+ * @example
+ * ```ts
+ * getIdSuffix("FEAT-SPEC-001"); // => "001"
+ * ```
  */
 function getIdSuffix(id) {
     const parts = id.split("-");
@@ -64,6 +106,12 @@ function getIdSuffix(id) {
 }
 /**
  * Parse tasks from a change node's plan array.
+ * @param node - The change node.
+ * @returns Array of task descriptions and done flags.
+ * @example
+ * ```ts
+ * const tasks = parseTasks(changeNode);
+ * ```
  */
 function parseTasks(node) {
     return (node.plan ?? []).map((task) => ({
@@ -73,6 +121,12 @@ function parseTasks(node) {
 }
 /**
  * Format the status for spec output: "proposed" -> "Draft", etc.
+ * @param status - The node status string.
+ * @returns Formatted status label.
+ * @example
+ * ```ts
+ * formatStatus("proposed"); // => "Draft"
+ * ```
  */
 function formatStatus(status) {
     if (!status)
@@ -87,7 +141,16 @@ function formatStatus(status) {
 // ============================================================================
 // generate Constitution
 // ============================================================================
-/** Generate a Spec-Kit constitution file from a SysProM document's principles and invariants. */
+/**
+ * Generate a Spec-Kit constitution file from a SysProM document's principles and invariants.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateConstitution(doc, "FEAT");
+ * ```
+ */
 export function generateConstitution(doc, prefix) {
     const protocolId = `${prefix}-CONST`;
     const protocol = findNode(doc, protocolId);
@@ -160,7 +223,16 @@ export function generateConstitution(doc, prefix) {
 // ============================================================================
 // generateSpec
 // ============================================================================
-/** Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria. */
+/**
+ * Generate a Spec-Kit specification file from a SysProM document's user stories, FRs, and acceptance criteria.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateSpec(doc, "FEAT");
+ * ```
+ */
 export function generateSpec(doc, prefix) {
     const specId = `${prefix}-SPEC`;
     const spec = findNode(doc, specId);
@@ -274,7 +346,16 @@ export function generateSpec(doc, prefix) {
 // ============================================================================
 // generatePlan
 // ============================================================================
-/** Generate a Spec-Kit plan file from a SysProM document's phases and milestones. */
+/**
+ * Generate a Spec-Kit plan file from a SysProM document's phases and milestones.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generatePlan(doc, "FEAT");
+ * ```
+ */
 export function generatePlan(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -325,7 +406,16 @@ export function generatePlan(doc, prefix) {
 // ============================================================================
 // generateTasks
 // ============================================================================
-/** Generate a Spec-Kit tasks file from a SysProM document's change nodes. */
+/**
+ * Generate a Spec-Kit tasks file from a SysProM document's change nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateTasks(doc, "FEAT");
+ * ```
+ */
 export function generateTasks(doc, prefix) {
     const implProtocolId = `${prefix}-PROT-IMPL`;
     const protocol = findNode(doc, implProtocolId);
@@ -465,7 +555,16 @@ export function generateTasks(doc, prefix) {
 // ============================================================================
 // generateChecklist
 // ============================================================================
-/** Generate a Spec-Kit checklist file from a SysProM document's gate nodes. */
+/**
+ * Generate a Spec-Kit checklist file from a SysProM document's gate nodes.
+ * @param doc - The SysProM document.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @returns The generated markdown.
+ * @example
+ * ```ts
+ * const md = generateChecklist(doc, "FEAT");
+ * ```
+ */
 export function generateChecklist(doc, prefix) {
     const gateId = `${prefix}-CHK`;
     const gate = findNode(doc, gateId);
@@ -520,7 +619,16 @@ export function generateChecklist(doc, prefix) {
 // ============================================================================
 // generateSpecKitProject
 // ============================================================================
-/** Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files. */
+/**
+ * Generate a complete Spec-Kit project directory from a SysProM document — constitution, spec, plan, tasks, and checklist files.
+ * @param doc - The SysProM document.
+ * @param outputDir - Output directory path.
+ * @param prefix - ID prefix identifying nodes to include.
+ * @example
+ * ```ts
+ * generateSpecKitProject(doc, "./output", "FEAT");
+ * ```
+ */
 export function generateSpecKitProject(doc, outputDir, prefix) {
     // Create output directory if it doesn't exist
     mkdirSync(outputDir, { recursive: true });

package/dist/src/speckit/parse.d.ts

@@ -6,15 +6,70 @@ export interface ParseResult {
     /** Relationships extracted from the parsed content. */
     relationships: Relationship[];
 }
-/** Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships. */
+/**
+ * Parse a Spec-Kit constitution file into SysProM nodes (principles and invariants) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseConstitution(content, "FEAT");
+ * ```
+ */
 export declare function parseConstitution(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria). */
+/**
+ * Parse a Spec-Kit specification file into SysProM nodes (user stories, functional requirements, acceptance criteria).
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseSpec(content, "FEAT");
+ * ```
+ */
 export declare function parseSpec(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships. */
+/**
+ * Parse a Spec-Kit plan file into SysProM nodes (phases, milestones) and relationships.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const result = parsePlan(content, "FEAT");
+ * ```
+ */
 export declare function parsePlan(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit tasks file into SysProM change nodes with task plans. */
+/**
+ * Parse a Spec-Kit tasks file into SysProM change nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseTasks(content, "FEAT");
+ * ```
+ */
 export declare function parseTasks(content: string, idPrefix: string): ParseResult;
-/** Parse a Spec-Kit checklist file into SysProM gate nodes with task plans. */
+/**
+ * Parse a Spec-Kit checklist file into SysProM gate nodes with task plans.
+ * @param content - Markdown file content.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const result = parseChecklist(content, "FEAT");
+ * ```
+ */
 export declare function parseChecklist(content: string, idPrefix: string): ParseResult;
-/** Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist. */
+/**
+ * Parse an entire Spec-Kit feature directory into a SysProM document, combining constitution, spec, plan, tasks, and checklist.
+ * @param featureDir - Path to Spec-Kit feature directory.
+ * @param idPrefix - ID prefix for generated nodes.
+ * @param constitutionPath - Path to constitution.md, or undefined.
+ * @returns The parsed SysProM document.
+ * @example
+ * ```ts
+ * const doc = parseSpecKitFeature("./features/auth", "AUTH");
+ * ```
+ */
 export declare function parseSpecKitFeature(featureDir: string, idPrefix: string, constitutionPath?: string): SysProMDocument;