sysprom 1.0.7 → 1.1.0

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

@@ -1,11 +1,11 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
 declare const argsSchema: z.ZodObject<{
-    input: z.ZodString;
     oldId: z.ZodString;
     newId: z.ZodString;
 }, z.core.$strip>;
 declare const optsSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
     json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sync: z.ZodOptional<z.ZodString>;

package/dist/src/cli/commands/rename.js

@@ -1,8 +1,7 @@
 import * as z from "zod";
 import { renameOp } from "../../operations/index.js";
-import { inputArg, mutationOpts, loadDoc, persistDoc } from "../shared.js";
+import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 const argsSchema = z.object({
-    input: inputArg,
     oldId: z.string().describe("Current node ID"),
     newId: z.string().describe("New node ID"),
 });
@@ -15,7 +14,7 @@ export const renameCommand = {
     opts: optsSchema,
     action(args, opts) {
         try {
-            const loaded = loadDoc(args.input);
+            const loaded = loadDoc(opts.path);
             const { doc } = loaded;
             const updated = renameOp({ doc, oldId: args.oldId, newId: args.newId });
             persistDoc(updated, loaded, opts);

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

@@ -1,10 +1,10 @@
 import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
 declare const argsSchema: z.ZodObject<{
-    input: z.ZodString;
     term: z.ZodString;
 }, z.core.$strip>;
 declare const optsSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
     json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export declare const searchCommand: CommandDef<typeof argsSchema, typeof optsSchema>;

package/dist/src/cli/commands/search.js

@@ -1,9 +1,8 @@
 import * as z from "zod";
 import { searchOp } from "../../operations/index.js";
-import { inputArg, readOpts, loadDoc } from "../shared.js";
+import { readOpts, loadDoc } from "../shared.js";
 import { textToString } from "../../text.js";
 const argsSchema = z.object({
-    input: inputArg,
     term: z.string().describe("Search term"),
 });
 const optsSchema = readOpts;
@@ -14,7 +13,7 @@ export const searchCommand = {
     args: argsSchema,
     opts: optsSchema,
     action(args, opts) {
-        const { doc } = loadDoc(args.input);
+        const { doc } = loadDoc(opts.path);
         const matches = searchOp({ doc, term: args.term });
         if (opts.json) {
             console.log(JSON.stringify(matches, null, 2));

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

@@ -1,10 +1,8 @@
-import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-declare const argsSchema: z.ZodObject<{
-    input: z.ZodString;
-}, z.core.$strip>;
-declare const optsSchema: z.ZodObject<{
-    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-export declare const statsCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+import { noArgs } from "../shared.js";
+declare const optsSchema: import("zod").ZodObject<{
+    path: import("zod").ZodOptional<import("zod").ZodString>;
+    json: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
+}, import("zod/v4/core").$strip>;
+export declare const statsCommand: CommandDef<typeof noArgs, typeof optsSchema>;
 export {};

package/dist/src/cli/commands/stats.js

@@ -1,19 +1,14 @@
-import * as z from "zod";
 import pc from "picocolors";
 import { statsOp } from "../../operations/index.js";
-import { inputArg, readOpts, loadDoc } from "../shared.js";
-const argsSchema = z.object({
-    input: inputArg,
-});
+import { readOpts, loadDoc } from "../shared.js";
 const optsSchema = readOpts;
 export const statsCommand = {
     name: "stats",
     description: statsOp.def.description,
     apiLink: statsOp.def.name,
-    args: argsSchema,
     opts: optsSchema,
-    action(args) {
-        const { doc } = loadDoc(args.input);
+    action(_args, opts) {
+        const { doc } = loadDoc(opts.path);
         const s = statsOp({ doc });
         console.log(`${pc.bold("SysProM Document")}: ${s.title}`);
         console.log("");

package/dist/src/cli/commands/task.js

@@ -1,25 +1,20 @@
 import * as z from "zod";
-import { loadDocument, saveDocument } from "../../io.js";
+import { loadDoc, mutationOpts, persistDoc } from "../shared.js";
 import { addPlanTaskOp, markTaskDoneOp, markTaskUndoneOp, taskListOp, } from "../../operations/index.js";
 // ============================================================================
 // Subcommands
 // ============================================================================
-const listArgs = z.object({
-    input: z.string().describe("Path to SysProM document"),
-});
-const listOpts = z.object({
+const listOpts = mutationOpts.pick({ path: true, json: true }).extend({
     change: z.string().optional().describe("Filter by change ID"),
     pending: z.boolean().optional().describe("Show only pending tasks"),
-    json: z.boolean().optional().describe("Output as JSON"),
 });
 const listSubcommand = {
     name: "list",
     description: taskListOp.def.description,
     apiLink: taskListOp.def.name,
-    args: listArgs,
     opts: listOpts,
-    action(args, opts) {
-        const { doc } = loadDocument(args.input);
+    action(_args, opts) {
+        const { doc } = loadDoc(opts.path);
         try {
             const rows = taskListOp({
                 doc,
@@ -47,26 +42,26 @@ const listSubcommand = {
     },
 };
 const addArgs = z.object({
-    input: z.string().describe("Path to SysProM document"),
     changeId: z.string().describe("Change node ID"),
     description: z.string().describe("Task description"),
 });
-const addOpts = z.object({});
+const addOpts = mutationOpts.pick({ path: true });
 const addSubcommand = {
     name: "add",
     description: addPlanTaskOp.def.description,
     apiLink: addPlanTaskOp.def.name,
     args: addArgs,
     opts: addOpts,
-    action(args) {
-        const { doc, format, path } = loadDocument(args.input);
+    action(args, opts) {
+        const loaded = loadDoc(opts.path);
+        const { doc } = loaded;
         try {
             const newDoc = addPlanTaskOp({
                 doc,
                 changeId: args.changeId,
                 description: args.description,
             });
-            saveDocument(newDoc, format, path);
+            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
             const node = newDoc.nodes.find((n) => n.id === args.changeId);
             if (!node)
                 throw new Error(`Node ${args.changeId} not found`);
@@ -80,19 +75,19 @@ const addSubcommand = {
     },
 };
 const doneArgs = z.object({
-    input: z.string().describe("Path to SysProM document"),
     changeId: z.string().describe("Change node ID"),
     taskIndex: z.string().describe("Task index"),
 });
-const doneOpts = z.object({});
+const doneOpts = mutationOpts.pick({ path: true });
 const doneSubcommand = {
     name: "done",
     description: markTaskDoneOp.def.description,
     apiLink: markTaskDoneOp.def.name,
     args: doneArgs,
     opts: doneOpts,
-    action(args) {
-        const { doc, format, path } = loadDocument(args.input);
+    action(args, opts) {
+        const loaded = loadDoc(opts.path);
+        const { doc } = loaded;
         const taskIndex = parseInt(args.taskIndex, 10);
         if (isNaN(taskIndex) || taskIndex < 0) {
             console.error(`Invalid task index: ${args.taskIndex}`);
@@ -104,7 +99,7 @@ const doneSubcommand = {
                 changeId: args.changeId,
                 taskIndex,
             });
-            saveDocument(newDoc, format, path);
+            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
             console.log(`Marked task ${String(taskIndex)} done on ${args.changeId}`);
         }
         catch (err) {
@@ -114,19 +109,19 @@ const doneSubcommand = {
     },
 };
 const undoneArgs = z.object({
-    input: z.string().describe("Path to SysProM document"),
     changeId: z.string().describe("Change node ID"),
     taskIndex: z.string().describe("Task index"),
 });
-const undoneOpts = z.object({});
+const undoneOpts = mutationOpts.pick({ path: true });
 const undoneSubcommand = {
     name: "undone",
     description: markTaskUndoneOp.def.description,
     apiLink: markTaskUndoneOp.def.name,
     args: undoneArgs,
     opts: undoneOpts,
-    action(args) {
-        const { doc, format, path } = loadDocument(args.input);
+    action(args, opts) {
+        const loaded = loadDoc(opts.path);
+        const { doc } = loaded;
         const taskIndex = parseInt(args.taskIndex, 10);
         if (isNaN(taskIndex) || taskIndex < 0) {
             console.error(`Invalid task index: ${args.taskIndex}`);
@@ -138,7 +133,7 @@ const undoneSubcommand = {
                 changeId: args.changeId,
                 taskIndex,
             });
-            saveDocument(newDoc, format, path);
+            persistDoc(newDoc, loaded, { ...opts, json: false, dryRun: false });
             console.log(`Marked task ${String(taskIndex)} undone on ${args.changeId}`);
         }
         catch (err) {

package/dist/src/cli/commands/update.js

@@ -1,7 +1,7 @@
 import * as z from "zod";
 import { RelationshipType, NodeStatus } from "../../schema.js";
 import { updateNodeOp, addRelationshipOp, removeRelationshipOp, updateMetadataOp, } from "../../operations/index.js";
-import { inputArg, mutationOpts, loadDoc, persistDoc } from "../shared.js";
+import { mutationOpts, loadDoc, persistDoc } from "../shared.js";
 // ---------------------------------------------------------------------------
 // CLI helper functions
 // ---------------------------------------------------------------------------
@@ -25,7 +25,6 @@ function parseMetaValue(val) {
 // Arg/opt schemas
 // ---------------------------------------------------------------------------
 const updateNodeArgs = z.object({
-    input: inputArg,
     id: z.string().describe("node ID to update"),
 });
 const updateNodeOpts = mutationOpts.extend({
@@ -39,22 +38,17 @@ const updateNodeOpts = mutationOpts.extend({
         .describe("set lifecycle state (key=value format)"),
 });
 const addRelArgs = z.object({
-    input: inputArg,
     from: z.string().describe("source node ID"),
     type: RelationshipType.describe("relationship type"),
     to: z.string().describe("target node ID"),
 });
 const addRelOpts = mutationOpts;
 const removeRelArgs = z.object({
-    input: inputArg,
     from: z.string().describe("source node ID"),
     type: RelationshipType.describe("relationship type"),
     to: z.string().describe("target node ID"),
 });
 const removeRelOpts = mutationOpts;
-const metaArgs = z.object({
-    input: inputArg,
-});
 const metaOpts = mutationOpts.extend({
     fields: z
         .array(z.string())
@@ -72,7 +66,7 @@ const nodeSubcommand = {
     action(rawArgs, rawOpts) {
         const args = updateNodeArgs.parse(rawArgs);
         const opts = updateNodeOpts.parse(rawOpts);
-        const loaded = loadDoc(args.input);
+        const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const node = doc.nodes.find((n) => n.id === args.id);
         if (!node) {
@@ -126,7 +120,7 @@ const addRelSubcommand = {
     action(rawArgs, rawOpts) {
         const args = addRelArgs.parse(rawArgs);
         const opts = addRelOpts.parse(rawOpts);
-        const loaded = loadDoc(args.input);
+        const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const newDoc = addRelationshipOp({
             doc,
@@ -151,7 +145,7 @@ const removeRelSubcommand = {
     action(rawArgs, rawOpts) {
         const args = removeRelArgs.parse(rawArgs);
         const opts = removeRelOpts.parse(rawOpts);
-        const loaded = loadDoc(args.input);
+        const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const newDoc = removeRelationshipOp({
             doc,
@@ -172,16 +166,14 @@ const metaSubcommand = {
     name: "meta",
     description: updateMetadataOp.def.description,
     apiLink: updateMetadataOp.def.name,
-    args: metaArgs,
     opts: metaOpts,
-    action(rawArgs, rawOpts) {
-        const args = metaArgs.parse(rawArgs);
+    action(_rawArgs, rawOpts) {
         const opts = metaOpts.parse(rawOpts);
         if (opts.fields.length === 0) {
             console.error("No metadata fields specified. Use --fields key=value");
             process.exit(1);
         }
-        const loaded = loadDoc(args.input);
+        const loaded = loadDoc(opts.path);
         const { doc } = loaded;
         const fields = {};
         for (const kv of opts.fields) {

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

@@ -1,10 +1,8 @@
-import * as z from "zod";
 import type { CommandDef } from "../define-command.js";
-declare const argsSchema: z.ZodObject<{
-    input: z.ZodString;
-}, z.core.$strip>;
-declare const optsSchema: z.ZodObject<{
-    json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-export declare const validateCommand: CommandDef<typeof argsSchema, typeof optsSchema>;
+import { noArgs } from "../shared.js";
+declare const optsSchema: import("zod").ZodObject<{
+    path: import("zod").ZodOptional<import("zod").ZodString>;
+    json: import("zod").ZodDefault<import("zod").ZodOptional<import("zod").ZodBoolean>>;
+}, import("zod/v4/core").$strip>;
+export declare const validateCommand: CommandDef<typeof noArgs, typeof optsSchema>;
 export {};

package/dist/src/cli/commands/validate.js

@@ -1,19 +1,14 @@
-import * as z from "zod";
 import pc from "picocolors";
 import { validateOp } from "../../operations/index.js";
-import { inputArg, readOpts, loadDoc } from "../shared.js";
-const argsSchema = z.object({
-    input: inputArg,
-});
+import { readOpts, loadDoc } from "../shared.js";
 const optsSchema = readOpts;
 export const validateCommand = {
     name: "validate",
     description: validateOp.def.description,
     apiLink: validateOp.def.name,
-    args: argsSchema,
     opts: optsSchema,
-    action(args) {
-        const { doc } = loadDoc(args.input);
+    action(_args, opts) {
+        const { doc } = loadDoc(opts.path);
         const result = validateOp({ doc });
         if (result.valid) {
             console.log(pc.green("Valid SysProM document."));

package/dist/src/cli/shared.d.ts

@@ -1,14 +1,25 @@
 import * as z from "zod";
 import { type Format } from "../io.js";
 import type { SysProMDocument } from "../schema.js";
-/** Positional argument for a SysProM document path. */
+/** @deprecated Use --path option in readOpts/mutationOpts instead. */
 export declare const inputArg: z.ZodString;
+/** Empty args schema for commands that take no positional arguments. */
+export declare const noArgs: z.ZodObject<{}, z.core.$strict>;
+/**
+ * Resolve a SysProM document path. If no explicit path is given, search the
+ * working directory by priority:
+ *   1. .spm.json  2. .spm.md  3. .spm/
+ *   4. *.spm.json 5. *.spm.md 6. *.spm/ (glob — must be unique)
+ */
+export declare function resolveInput(input?: string, cwd?: string): string;
 /** Common output/persistence options for read-only commands. */
 export declare const readOpts: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
     json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 /** Common output/persistence options for mutation commands. */
 export declare const mutationOpts: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
     json: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sync: z.ZodOptional<z.ZodString>;
@@ -20,7 +31,7 @@ export interface LoadedDoc {
     format: Format;
     path: string;
 }
-/** Load a document from a CLI input path. */
-export declare function loadDoc(input: string): LoadedDoc;
+/** Load a document from a CLI input path (auto-resolved if omitted). */
+export declare function loadDoc(input?: string): LoadedDoc;
 /** Persist a document and optionally sync to markdown. */
 export declare function persistDoc(doc: SysProMDocument, loaded: LoadedDoc, opts: MutationOpts): void;

package/dist/src/cli/shared.js

@@ -1,19 +1,77 @@
 import * as z from "zod";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { loadDocument, saveDocument } from "../io.js";
 import { jsonToMarkdownMultiDoc } from "../json-to-md.js";
 // ---------------------------------------------------------------------------
 // Reusable CLI schemas — shared across all commands
 // ---------------------------------------------------------------------------
-/** Positional argument for a SysProM document path. */
+/** @deprecated Use --path option in readOpts/mutationOpts instead. */
 export const inputArg = z
     .string()
     .describe("SysProM document path (JSON, .md, or directory)");
+/** Empty args schema for commands that take no positional arguments. */
+export const noArgs = z.object({}).strict();
+/** Shared --path option for specifying the SysProM document location. */
+const pathOpt = z
+    .string()
+    .optional()
+    .describe("SysProM document path (auto-detected if omitted)");
+// ---------------------------------------------------------------------------
+// Default input resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a SysProM document path. If no explicit path is given, search the
+ * working directory by priority:
+ *   1. .spm.json  2. .spm.md  3. .spm/
+ *   4. *.spm.json 5. *.spm.md 6. *.spm/ (glob — must be unique)
+ */
+export function resolveInput(input, cwd) {
+    if (input)
+        return input;
+    const dir = resolve(cwd ?? ".");
+    // Priority 1–3: exact names
+    const exact = [".spm.json", ".spm.md", ".spm"];
+    for (const name of exact) {
+        const candidate = join(dir, name);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    // Priority 4–6: glob by suffix
+    const entries = readdirSync(dir);
+    const suffixes = [".spm.json", ".spm.md", ".spm"];
+    for (const suffix of suffixes) {
+        const matches = entries
+            .filter((e) => e.endsWith(suffix) && e !== suffix)
+            .map((e) => join(dir, e))
+            .filter((p) => {
+            if (suffix === ".spm") {
+                try {
+                    return statSync(p).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            }
+            return true;
+        });
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length > 1) {
+            const names = matches.map((m) => m.slice(dir.length + 1)).join(", ");
+            throw new Error(`Multiple SysProM documents found: ${names}. Specify one explicitly.`);
+        }
+    }
+    throw new Error("No SysProM document found in current directory. Specify a path or run `spm init`.");
+}
 /** Common output/persistence options for read-only commands. */
 export const readOpts = z.object({
+    path: pathOpt,
     json: z.boolean().optional().default(false).describe("output as JSON"),
 });
 /** Common output/persistence options for mutation commands. */
 export const mutationOpts = z.object({
+    path: pathOpt,
     json: z.boolean().optional().default(false).describe("output as JSON"),
     dryRun: z
         .boolean()
@@ -25,9 +83,9 @@ export const mutationOpts = z.object({
         .optional()
         .describe("sync to markdown directory after saving"),
 });
-/** Load a document from a CLI input path. */
+/** Load a document from a CLI input path (auto-resolved if omitted). */
 export function loadDoc(input) {
-    return loadDocument(input);
+    return loadDocument(resolveInput(input));
 }
 /** Persist a document and optionally sync to markdown. */
 export function persistDoc(doc, loaded, opts) {

package/dist/src/io.d.ts

@@ -1,8 +1,13 @@
 import { SysProMDocument } from "./schema.js";
+/** Supported serialisation formats for SysProM documents. */
 export type Format = "json" | "single-md" | "multi-md";
+/** The result of loading a SysProM document from disc. */
 export interface LoadedDocument {
+    /** The parsed SysProM document. */
     doc: SysProMDocument;
+    /** The detected serialisation format. */
     format: Format;
+    /** The resolved absolute path the document was loaded from. */
     path: string;
 }
 /**

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

@@ -1,4 +1,5 @@
 import { type SysProMDocument } from "./schema.js";
+/** Options for controlling JSON-to-Markdown conversion. */
 export interface ConvertOptions {
     form: "single-file" | "multi-doc";
 }

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

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Add a node to a SysProM document. Returns a new document with the node appended.
+ *
+ * @throws If a node with the same ID already exists.
+ */
 export declare const addNodeOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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

@@ -1,6 +1,11 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Node } from "../schema.js";
+/**
+ * Add a node to a SysProM document. Returns a new document with the node appended.
+ *
+ * @throws If a node with the same ID already exists.
+ */
 export const addNodeOp = defineOperation({
     name: "addNode",
     description: "Add a node to the document. Throws if the ID already exists.",

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

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Append a new task to a change node's plan array. Returns a new document with the task added.
+ *
+ * @throws If the change node is not found.
+ */
 export declare const addPlanTaskOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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

@@ -1,6 +1,11 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument } from "../schema.js";
+/**
+ * Append a new task to a change node's plan array. Returns a new document with the task added.
+ *
+ * @throws If the change node is not found.
+ */
 export const addPlanTaskOp = defineOperation({
     name: "addPlanTask",
     description: "Append a new task to a change node's plan array. Returns a new document.",

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

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
+ *
+ * @throws If either endpoint node does not exist in the document.
+ */
 export declare const addRelationshipOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

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

@@ -1,6 +1,11 @@
 import * as z from "zod";
 import { defineOperation } from "./define-operation.js";
 import { SysProMDocument, Relationship } from "../schema.js";
+/**
+ * Add a relationship to a SysProM document. Returns a new document with the relationship appended.
+ *
+ * @throws If either endpoint node does not exist in the document.
+ */
 export const addRelationshipOp = defineOperation({
     name: "addRelationship",
     description: "Add a relationship to the document. Throws if either endpoint node does not exist.",

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

@@ -1,4 +1,9 @@
 import * as z from "zod";
+/**
+ * Check a SysProM document for quality issues and warnings beyond schema
+ * validation — missing rationale, context, scope, descriptions, orphan nodes,
+ * and dangling scope references.
+ */
 export declare const checkOp: import("./define-operation.js").DefinedOperation<z.ZodObject<{
     doc: z.ZodObject<{
         $schema: z.ZodOptional<z.ZodString>;

package/dist/src/operations/check.js

@@ -50,6 +50,11 @@ function performCheck(doc) {
     }
     return { warnings, info };
 }
+/**
+ * Check a SysProM document for quality issues and warnings beyond schema
+ * validation — missing rationale, context, scope, descriptions, orphan nodes,
+ * and dangling scope references.
+ */
 export const checkOp = defineOperation({
     name: "check",
     description: "Check a SysProM document for issues and warnings. Performs quality/lint checks beyond schema validation.",

package/dist/src/operations/define-operation.d.ts

@@ -1,14 +1,45 @@
 import * as z from "zod";
+/**
+ * Definition of a SysProM operation — a named, typed function with Zod schemas
+ * for input validation and output description.
+ *
+ * @typeParam TInput - Zod schema type for the operation's input.
+ * @typeParam TOutput - Zod schema type for the operation's output.
+ */
 export interface OperationDef<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> {
+    /** Machine-readable operation name (e.g. `"addNode"`). */
     name: string;
+    /** Human-readable description of what the operation does. */
     description: string;
+    /** Zod schema used to validate the operation's input. */
     input: TInput;
+    /** Zod schema describing the operation's output shape. */
     output: TOutput;
+    /** The implementation function. */
     fn: (input: z.infer<TInput>) => z.infer<TOutput>;
 }
+/**
+ * A callable operation with attached metadata. Can be invoked directly as a
+ * function, and also exposes `.def`, `.inputSchema`, and `.outputSchema` for
+ * introspection.
+ *
+ * @typeParam TInput - Zod schema type for the operation's input.
+ * @typeParam TOutput - Zod schema type for the operation's output.
+ */
 export type DefinedOperation<TInput extends z.ZodType = z.ZodType, TOutput extends z.ZodType = z.ZodType> = ((input: z.infer<TInput>) => z.infer<TOutput>) & {
+    /** The full operation definition including name, description, and schemas. */
     def: OperationDef<TInput, TOutput>;
+    /** Zod schema for validating input before execution. */
     inputSchema: TInput;
+    /** Zod schema describing the output shape. */
     outputSchema: TOutput;
 };
+/**
+ * Create a callable operation from a definition. The returned function validates
+ * input against the Zod schema before delegating to the implementation.
+ *
+ * @param def - The operation definition with name, schemas, and implementation.
+ * @returns A callable function with `.def`, `.inputSchema`, and `.outputSchema` attached.
+ * @throws If the input fails Zod validation.
+ */
 export declare function defineOperation<TInput extends z.ZodType, TOutput extends z.ZodType>(def: OperationDef<TInput, TOutput>): DefinedOperation<TInput, TOutput>;