sysprom 1.2.0 → 1.2.2

package/dist/src/speckit/parse.js

@@ -5,6 +5,12 @@ import { join, basename } from "node:path";
 // ---------------------------------------------------------------------------
 /**
  * Parse markdown content into a hierarchical section tree by heading level.
+ * @param body - Markdown body text.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const sections = parseSections(markdownBody);
+ * ```
  */
 function parseSections(body) {
     const lines = body.split("\n");
@@ -49,6 +55,12 @@ function parseSections(body) {
 }
 /**
  * Extract bold key-value pairs from markdown like "**Key**: value" or "**Key**: value text".
+ * @param content - Markdown file content.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const meta = parseFrontMatterish(content);
+ * ```
  */
 function parseFrontMatterish(content) {
     const result = {};
@@ -64,6 +76,12 @@ function parseFrontMatterish(content) {
 }
 /**
  * Parse checkbox lines like "- [x] ID text" or "- [ ] ID text".
+ * @param body - Markdown body text.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const items = parseCheckboxes(body);
+ * ```
  */
 function parseCheckboxes(body) {
     const items = [];
@@ -84,6 +102,12 @@ function parseCheckboxes(body) {
 }
 /**
  * Flatten all sections in the tree into a single array for easier searching.
+ * @param sections - Parsed section tree.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const flat = flattenSections(sections);
+ * ```
  */
 function flattenSections(sections) {
     const result = [];
@@ -98,12 +122,25 @@ function flattenSections(sections) {
 }
 /**
  * Find the first section whose heading matches a predicate (searches entire tree).
+ * @param sections - Parsed section tree.
+ * @param predicate - Filter function.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const s = findSection(sections, (h) => h.startsWith("Phase"));
+ * ```
  */
 function findSection(sections, predicate) {
     return flattenSections(sections).find((s) => predicate(s.heading));
 }
 /**
  * Convert status-like strings to NodeStatus. Recognizes common spec-kit patterns.
+ * @param value - Raw status string.
+ * @returns The result.
+ * @example
+ * ```ts
+ * mapStatusValue("Draft"); // => "proposed"
+ * ```
  */
 function mapStatusValue(value) {
     const lower = value.toLowerCase().trim();
@@ -130,6 +167,13 @@ function mapStatusValue(value) {
 }
 /**
  * Extract a single line value from body text (e.g., "**Created**: 2025-01-01").
+ * @param body - Markdown body text.
+ * @param key - Front-matter key to extract.
+ * @returns The result.
+ * @example
+ * ```ts
+ * extractValue(body, "Created"); // => "2025-01-01"
+ * ```
  */
 function extractValue(body, key) {
     const pattern = new RegExp(`^\\*\\*${key}\\*\\*:\\s*(.+)$`, "m");
@@ -139,7 +183,16 @@ function extractValue(body, key) {
 // ---------------------------------------------------------------------------
 // constitution.md parser
 // ---------------------------------------------------------------------------
-/** 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 function parseConstitution(content, idPrefix) {
     const sections = parseSections(content);
     const nodes = [];
@@ -228,7 +281,16 @@ export function parseConstitution(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // spec.md parser
 // ---------------------------------------------------------------------------
-/** 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 function parseSpec(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -412,7 +474,16 @@ export function parseSpec(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // plan.md parser
 // ---------------------------------------------------------------------------
-/** 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 function parsePlan(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -505,7 +576,16 @@ export function parsePlan(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // tasks.md parser
 // ---------------------------------------------------------------------------
-/** 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 function parseTasks(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -611,7 +691,16 @@ export function parseTasks(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // checklist.md parser
 // ---------------------------------------------------------------------------
-/** 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 function parseChecklist(content, idPrefix) {
     const sections = parseSections(content);
     const allSections = flattenSections(sections);
@@ -660,7 +749,17 @@ export function parseChecklist(content, idPrefix) {
 // ---------------------------------------------------------------------------
 // Full feature directory parser
 // ---------------------------------------------------------------------------
-/** 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 function parseSpecKitFeature(featureDir, idPrefix, constitutionPath) {
     const nodes = [];
     const relationships = [];

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

@@ -74,6 +74,13 @@ export interface TaskCount {
  *   - {prefix}-CHK  governed_by  {prefix}-PROT-IMPL
  *
  * Tasks are not pre-scaffolded; use addTask to add them.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const doc = initDocument("PLAN", "My Plan");
+ * ```
  */
 export declare function initDocument(prefix: string, name: string): SysProMDocument;
 /**
@@ -88,6 +95,15 @@ export declare function initDocument(prefix: string, name: string): SysProMDocum
  *
  * Wires must_follow to previous sibling change node at the same level.
  * Default name: "Task N".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @param parentId - Parent task ID.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export declare function addTask(doc: SysProMDocument, prefix: string, name?: string, parentId?: string): SysProMDocument;
 /**
@@ -97,6 +113,12 @@ export declare function addTask(doc: SysProMDocument, prefix: string, name?: str
  *   - All items in node.plan must have done === true AND at least one item must exist
  * If subsystem has change children:
  *   - All children must be recursively done AND own plan items (if any) must be done
+ * @param node - The node to check.
+ * @returns The result.
+ * @example
+ * ```ts
+ * isTaskDone(changeNode); // => true if all plan items done
+ * ```
  */
 export declare function isTaskDone(node: Node): boolean;
 /**
@@ -104,16 +126,36 @@ export declare function isTaskDone(node: Node): boolean;
  *
  * Sums plan[] items from this node and recursively from all change nodes in
  * subsystem (and their subsystems).
+ * @param node - The node to check.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const { total, done } = countTasks(changeNode);
+ * ```
  */
 export declare function countTasks(node: Node): TaskCount;
 /**
  * Inspect a document and return workflow completeness for a given prefix.
  * Never throws — missing nodes are reported as "not defined".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const status = planStatus(doc, "PLAN");
+ * ```
  */
 export declare function planStatus(doc: SysProMDocument, prefix: string): PlanStatus;
 /**
  * Return per-task completion data.
  * Tasks (change nodes) are discovered from PROT-IMPL.subsystem, sorted topologically.
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export declare function planProgress(doc: SysProMDocument, prefix: string): PhaseProgress[];
 /**
@@ -126,5 +168,13 @@ export declare function planProgress(doc: SysProMDocument, prefix: string): Phas
  *
  * Additionally for phase N > 1:
  *   - All tasks in phase N-1 must be done
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param phase - Phase number (1-indexed).
+ * @returns Gate check result with readiness flag and issues.
+ * @example
+ * ```ts
+ * const result = checkGate(doc, "PLAN", 2);
+ * ```
  */
 export declare function checkGate(doc: SysProMDocument, prefix: string, phase: number): GateResult;

package/dist/src/speckit/plan.js

@@ -4,12 +4,26 @@ import { textToString } from "../text.js";
 // ============================================================================
 /**
  * Find a single node by ID, or null if not found.
+ * @param doc - The SysProM document.
+ * @param id - Node ID to find.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const node = findNode(doc, "PLAN-SPEC");
+ * ```
  */
 function findNode(doc, id) {
     return doc.nodes.find((n) => n.id === id) ?? null;
 }
 /**
  * Find a single node by ID in a subsystem, or null if not found.
+ * @param subsystem - The subsystem document.
+ * @param id - Node ID to find.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const node = findNodeInSubsystem(subsystem, "CH1");
+ * ```
  */
 function findNodeInSubsystem(subsystem, id) {
     if (!subsystem)
@@ -18,12 +32,26 @@ function findNodeInSubsystem(subsystem, id) {
 }
 /**
  * Find all nodes of a specific type.
+ * @param doc - The SysProM document.
+ * @param type - Node type to filter by.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const changes = findNodesByType(doc, "change");
+ * ```
  */
 function findNodesByType(doc, type) {
     return doc.nodes.filter((n) => n.type === type);
 }
 /**
  * Find all nodes of a specific type in a subsystem.
+ * @param subsystem - The subsystem document.
+ * @param type - Node type to filter by.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const gates = findNodesByTypeInSubsystem(subsystem, "gate");
+ * ```
  */
 function findNodesByTypeInSubsystem(subsystem, type) {
     if (!subsystem)
@@ -32,6 +60,14 @@ function findNodesByTypeInSubsystem(subsystem, type) {
 }
 /**
  * Find relationships from a source node to nodes of a target type (within a subsystem).
+ * @param subsystem - The subsystem document.
+ * @param fromId - Source node ID.
+ * @param relationType - Relationship type filter.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsFrom(subsystem, "CH1");
+ * ```
  */
 function findRelationshipsFrom(subsystem, fromId, relationType) {
     if (!subsystem)
@@ -46,6 +82,14 @@ function findRelationshipsFrom(subsystem, fromId, relationType) {
 }
 /**
  * Find relationships to a target node (within a subsystem).
+ * @param subsystem - The subsystem document.
+ * @param toId - Target node ID.
+ * @param relationType - Relationship type filter.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const rels = findRelationshipsTo(subsystem, "CH2");
+ * ```
  */
 function findRelationshipsTo(subsystem, toId, relationType) {
     if (!subsystem)
@@ -61,6 +105,12 @@ function findRelationshipsTo(subsystem, toId, relationType) {
 /**
  * Detect if a text contains non-placeholder acceptance criteria.
  * Looks for GIVEN/WHEN/THEN patterns (case-insensitive).
+ * @param description - Task description text.
+ * @returns The result.
+ * @example
+ * ```ts
+ * hasAcceptanceCriteria("Given X When Y Then Z"); // => true
+ * ```
  */
 function hasAcceptanceCriteria(description) {
     if (!description)
@@ -70,6 +120,13 @@ function hasAcceptanceCriteria(description) {
 }
 /**
  * Sort change nodes topologically using must_follow relationships.
+ * @param subsystem - The subsystem document.
+ * @param changeNodes - Array of change nodes.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const sorted = sortChangesByOrder(subsystem, changeNodes);
+ * ```
  */
 function sortChangesByOrder(subsystem, changeNodes) {
     const subsystemToUse = subsystem ?? { nodes: [], relationships: [] };
@@ -122,6 +179,13 @@ function sortChangesByOrder(subsystem, changeNodes) {
  *   - {prefix}-CHK  governed_by  {prefix}-PROT-IMPL
  *
  * Tasks are not pre-scaffolded; use addTask to add them.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const doc = initDocument("PLAN", "My Plan");
+ * ```
  */
 export function initDocument(prefix, name) {
     const nodes = [
@@ -189,6 +253,15 @@ export function initDocument(prefix, name) {
  *
  * Wires must_follow to previous sibling change node at the same level.
  * Default name: "Task N".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param name - Name for the new item.
+ * @param parentId - Parent task ID.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export function addTask(doc, prefix, name, parentId) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -247,6 +320,16 @@ export function addTask(doc, prefix, name, parentId) {
 }
 /**
  * Helper function to recursively add a task to a parent change node's subsystem.
+ * @param doc - The SysProM document.
+ * @param protImpl - Implementation protocol node.
+ * @param prefix - Plan prefix.
+ * @param parentId - Parent task ID.
+ * @param name - Name for the new item.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const updated = addTaskToParent(doc, protImpl, "PLAN", "CH1");
+ * ```
  */
 function addTaskToParent(doc, protImpl, prefix, parentId, name) {
     // Find the parent change node in the subsystem tree
@@ -376,6 +459,12 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
  *   - All items in node.plan must have done === true AND at least one item must exist
  * If subsystem has change children:
  *   - All children must be recursively done AND own plan items (if any) must be done
+ * @param node - The node to check.
+ * @returns The result.
+ * @example
+ * ```ts
+ * isTaskDone(changeNode); // => true if all plan items done
+ * ```
  */
 export function isTaskDone(node) {
     // If the node has a subsystem with change children, check those recursively
@@ -404,6 +493,12 @@ export function isTaskDone(node) {
  *
  * Sums plan[] items from this node and recursively from all change nodes in
  * subsystem (and their subsystems).
+ * @param node - The node to check.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const { total, done } = countTasks(changeNode);
+ * ```
  */
 export function countTasks(node) {
     let total = 0;
@@ -429,6 +524,13 @@ export function countTasks(node) {
 /**
  * Inspect a document and return workflow completeness for a given prefix.
  * Never throws — missing nodes are reported as "not defined".
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const status = planStatus(doc, "PLAN");
+ * ```
  */
 export function planStatus(doc, prefix) {
     const constitution = findNode(doc, `${prefix}-CONST`);
@@ -527,6 +629,13 @@ export function planStatus(doc, prefix) {
 /**
  * Return per-task completion data.
  * Tasks (change nodes) are discovered from PROT-IMPL.subsystem, sorted topologically.
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @returns The result.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export function planProgress(doc, prefix) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -568,6 +677,14 @@ export function planProgress(doc, prefix) {
  *
  * Additionally for phase N > 1:
  *   - All tasks in phase N-1 must be done
+ * @param doc - The SysProM document.
+ * @param prefix - Plan prefix.
+ * @param phase - Phase number (1-indexed).
+ * @returns Gate check result with readiness flag and issues.
+ * @example
+ * ```ts
+ * const result = checkGate(doc, "PLAN", 2);
+ * ```
  */
 export function checkGate(doc, prefix, phase) {
     if (phase < 1) {

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

@@ -28,18 +28,47 @@ export interface SpecKitFeature {
 /**
  * Detect Spec-Kit project structure from a directory.
  * Looks for .specify/ and specs/ subdirectories.
+ * @param dir - Directory to scan.
+ * @returns Detected project structure.
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
  */
 export declare function detectSpecKitProject(dir: string): SpecKitProject;
 /**
  * List all features in the specs/ directory, sorted by number.
+ * @param project - The detected project.
+ * @returns Sorted list of features.
+ * @example
+ * ```ts
+ * const features = listFeatures(project);
+ * ```
  */
 export declare function listFeatures(project: SpecKitProject): SpecKitFeature[];
 /**
  * Get a specific feature by number or name.
  * Matches "001", "001-feature-name", or "feature-name".
+ * @param project - The detected project.
+ * @param idOrName - Feature ID, number, or name.
+ * @returns The matching feature, or null.
+ * @example
+ * ```ts
+ * const feature = getFeature(project, "001-auth");
+ * ```
  */
 export declare function getFeature(project: SpecKitProject, idOrName: string): SpecKitFeature | null;
 /**
  * Resolve the constitution.md file, checking .specify/memory/ first, then root.
+ * @param project - The detected project.
+ * @returns Path to constitution.md, or null.
+ * @example
+ * ```ts
+ * const path = resolveConstitution(project);
+ * ```
  */
 export declare function resolveConstitution(project: SpecKitProject): string | null;

package/dist/src/speckit/project.js

@@ -3,6 +3,16 @@ import { join } from "node:path";
 /**
  * Detect Spec-Kit project structure from a directory.
  * Looks for .specify/ and specs/ subdirectories.
+ * @param dir - Directory to scan.
+ * @returns Detected project structure.
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
+ * @example
+ * ```ts
+ * const project = detectSpecKitProject("./my-project");
+ * ```
  */
 export function detectSpecKitProject(dir) {
     const specifyDir = checkDir(join(dir, ".specify"));
@@ -30,6 +40,12 @@ export function detectSpecKitProject(dir) {
 }
 /**
  * List all features in the specs/ directory, sorted by number.
+ * @param project - The detected project.
+ * @returns Sorted list of features.
+ * @example
+ * ```ts
+ * const features = listFeatures(project);
+ * ```
  */
 export function listFeatures(project) {
     if (!project.specsDir) {
@@ -63,6 +79,13 @@ export function listFeatures(project) {
 /**
  * Get a specific feature by number or name.
  * Matches "001", "001-feature-name", or "feature-name".
+ * @param project - The detected project.
+ * @param idOrName - Feature ID, number, or name.
+ * @returns The matching feature, or null.
+ * @example
+ * ```ts
+ * const feature = getFeature(project, "001-auth");
+ * ```
  */
 export function getFeature(project, idOrName) {
     const features = listFeatures(project);
@@ -83,12 +106,24 @@ export function getFeature(project, idOrName) {
 }
 /**
  * Resolve the constitution.md file, checking .specify/memory/ first, then root.
+ * @param project - The detected project.
+ * @returns Path to constitution.md, or null.
+ * @example
+ * ```ts
+ * const path = resolveConstitution(project);
+ * ```
  */
 export function resolveConstitution(project) {
     return project.constitutionPath;
 }
 /**
  * Check if a directory exists, return path or null.
+ * @param path - Path to check.
+ * @returns The path if it exists as a directory, or null.
+ * @example
+ * ```ts
+ * const dir = checkDir("/path/to/dir");
+ * ```
  */
 function checkDir(path) {
     try {
@@ -101,6 +136,13 @@ function checkDir(path) {
 }
 /**
  * Parse a feature directory and extract metadata and file paths.
+ * @param dir - Directory to search.
+ * @param dirName - Subdirectory name pattern.
+ * @returns Array of matching directory paths.
+ * @example
+ * ```ts
+ * const feature = parseFeatureDirectory("./specs", "001-auth");
+ * ```
  */
 function parseFeatureDirectory(dir, dirName) {
     // Parse the directory name format: "NNN-feature-name"
@@ -128,6 +170,13 @@ function parseFeatureDirectory(dir, dirName) {
 }
 /**
  * Check if a file exists in a directory, return path or null.
+ * @param dir - Directory to search.
+ * @param filename - File name to find.
+ * @returns Array of matching file paths.
+ * @example
+ * ```ts
+ * const specPath = checkFile("./feature", "spec.md");
+ * ```
  */
 function checkFile(dir, filename) {
     const path = join(dir, filename);

package/dist/src/text.d.ts

@@ -1,23 +1,44 @@
-/** Normalise a text field (string | string[]) to a single string, joining with newlines.
+/**
+ * Normalise a text field (string | string[]) to a single string, joining with newlines.
  * @param value - The text field to normalise.
  * @returns A single string.
+ * @example
+ * ```ts
+ * textToString(["line 1", "line 2"]) // => "line 1\nline 2"
+ * textToString("hello") // => "hello"
+ * ```
  */
 export declare function textToString(value: string | string[]): string;
-/** Normalise a text field to an array of lines.
+/**
+ * Normalise a text field to an array of lines.
  * @param value - The text field to normalise.
  * @returns An array of lines.
+ * @example
+ * ```ts
+ * textToLines("hello") // => ["hello"]
+ * textToLines(["a", "b"]) // => ["a", "b"]
+ * ```
  */
 export declare function textToLines(value: string | string[]): string[];
-/** Format a text field for Markdown output — each line becomes a paragraph.
+/**
+ * Format a text field for Markdown output — each line becomes a paragraph.
  * @param value - The text field to format.
  * @returns Markdown-formatted string.
+ * @example
+ * ```ts
+ * textToMarkdown(["para 1", "para 2"]) // => "para 1\npara 2"
+ * ```
  */
 export declare function textToMarkdown(value: string | string[]): string;
 /**
  * Parse a Markdown text block back into the canonical text representation.
  * Single-line content stays as a string; multiline becomes an array.
- *
  * @param block - The Markdown text block to parse.
  * @returns A string for single-line content, or an array of lines for multiline.
+ * @example
+ * ```ts
+ * markdownToText("single line") // => "single line"
+ * markdownToText("line 1\nline 2") // => ["line 1", "line 2"]
+ * ```
  */
 export declare function markdownToText(block: string): string | string[];