sysprom 1.2.1 → 1.2.3

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

@@ -11,6 +11,10 @@ export interface ParseResult {
  * @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;
 /**
@@ -18,6 +22,10 @@ export declare function parseConstitution(content: string, idPrefix: string): Pa
  * @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;
 /**
@@ -25,6 +33,10 @@ export declare function parseSpec(content: string, idPrefix: string): ParseResul
  * @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;
 /**
@@ -32,6 +44,10 @@ export declare function parsePlan(content: string, idPrefix: string): ParseResul
  * @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;
 /**
@@ -39,6 +55,10 @@ export declare function parseTasks(content: string, idPrefix: string): ParseResu
  * @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;
 /**
@@ -47,5 +67,9 @@ export declare function parseChecklist(content: string, idPrefix: string): Parse
  * @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;

package/dist/src/speckit/parse.js

@@ -7,6 +7,10 @@ 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");
@@ -53,6 +57,10 @@ 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 = {};
@@ -70,6 +78,10 @@ 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 = [];
@@ -92,6 +104,10 @@ 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 = [];
@@ -109,6 +125,10 @@ function flattenSections(sections) {
  * @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));
@@ -117,6 +137,10 @@ function findSection(sections, predicate) {
  * 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();
@@ -146,6 +170,10 @@ function mapStatusValue(value) {
  * @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");
@@ -160,6 +188,10 @@ function extractValue(body, key) {
  * @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);
@@ -254,6 +286,10 @@ export function parseConstitution(content, idPrefix) {
  * @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);
@@ -443,6 +479,10 @@ export function parseSpec(content, idPrefix) {
  * @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);
@@ -541,6 +581,10 @@ export function parsePlan(content, idPrefix) {
  * @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);
@@ -652,6 +696,10 @@ export function parseTasks(content, idPrefix) {
  * @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);
@@ -707,6 +755,10 @@ export function parseChecklist(content, idPrefix) {
  * @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 = [];

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

@@ -77,6 +77,10 @@ export interface TaskCount {
  * @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;
 /**
@@ -94,19 +98,27 @@ export declare function initDocument(prefix: string, name: string): SysProMDocum
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @param name - Name for the new item.
- * @param parentId - Parent task ID.
- * @returns The result.
+ * @param parentId - Optional parent change node ID for nesting.
+ * @returns The updated document with the new task added.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export declare function addTask(doc: SysProMDocument, prefix: string, name?: string, parentId?: string): SysProMDocument;
 /**
  * Check if a change node's task is complete.
  *
  * If no subsystem or no change children in subsystem:
- *   - All items in node.plan must have done === true AND at least one item must exist
+ *   - 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.
+ *   - All children must be recursively done AND own plan items (if any) must be done.
+ * @param node - The change node to evaluate.
+ * @returns Whether all tasks in the node's plan are complete.
+ * @example
+ * ```ts
+ * isTaskDone(changeNode); // => true if all plan items done
+ * ```
  */
 export declare function isTaskDone(node: Node): boolean;
 /**
@@ -116,37 +128,53 @@ export declare function isTaskDone(node: Node): boolean;
  * 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.
+ * @param prefix - ID prefix identifying the plan (e.g. "PLAN").
+ * @returns Comprehensive status of all plan components.
+ * @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.
+ * @param prefix - ID prefix identifying the plan (e.g. "PLAN").
+ * @returns Per-phase progress with task counts and percentages.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export declare function planProgress(doc: SysProMDocument, prefix: string): PhaseProgress[];
 /**
  * Validate readiness to enter the given phase (1-indexed).
  *
  * Always checks:
- *   - Each capability ({prefix}-US-*) has a change node that implements it
- *   - Each capability has non-placeholder acceptance criteria
- *   - Each invariant ({prefix}-FR-*) has a change node that implements it
+ *   - Each capability ({prefix}-US-*) has a change node that implements it.
+ *   - Each capability has non-placeholder acceptance criteria.
+ *   - Each invariant ({prefix}-FR-*) has a change node that implements it.
  *
  * Additionally for phase N > 1:
- *   - All tasks in phase N-1 must be done
+ *   - 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

@@ -7,6 +7,10 @@ import { textToString } from "../text.js";
  * @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;
@@ -16,6 +20,10 @@ function findNode(doc, id) {
  * @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)
@@ -27,6 +35,10 @@ function findNodeInSubsystem(subsystem, id) {
  * @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);
@@ -36,6 +48,10 @@ function findNodesByType(doc, type) {
  * @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)
@@ -48,6 +64,10 @@ function findNodesByTypeInSubsystem(subsystem, type) {
  * @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)
@@ -66,6 +86,10 @@ function findRelationshipsFrom(subsystem, fromId, relationType) {
  * @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)
@@ -83,6 +107,10 @@ function findRelationshipsTo(subsystem, toId, relationType) {
  * 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)
@@ -95,6 +123,10 @@ function hasAcceptanceCriteria(description) {
  * @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: [] };
@@ -150,6 +182,10 @@ function sortChangesByOrder(subsystem, changeNodes) {
  * @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 = [
@@ -220,8 +256,12 @@ export function initDocument(prefix, name) {
  * @param doc - The SysProM document.
  * @param prefix - Plan prefix.
  * @param name - Name for the new item.
- * @param parentId - Parent task ID.
- * @returns The result.
+ * @param parentId - Optional parent change node ID for nesting.
+ * @returns The updated document with the new task added.
+ * @example
+ * ```ts
+ * const updated = addTask(doc, "PLAN", "Implement auth");
+ * ```
  */
 export function addTask(doc, prefix, name, parentId) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -283,9 +323,13 @@ export function addTask(doc, prefix, name, parentId) {
  * @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.
+ * @param parentId - ID of the parent change node to nest under.
+ * @param name - Human-readable task name.
+ * @returns The updated document with the nested task added.
+ * @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
@@ -412,11 +456,15 @@ function addTaskToParent(doc, protImpl, prefix, parentId, name) {
  * Check if a change node's task is complete.
  *
  * If no subsystem or no change children in subsystem:
- *   - All items in node.plan must have done === true AND at least one item must exist
+ *   - 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.
+ *   - All children must be recursively done AND own plan items (if any) must be done.
+ * @param node - The change node to evaluate.
+ * @returns Whether all tasks in the node's plan are complete.
+ * @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
@@ -447,6 +495,10 @@ export function isTaskDone(node) {
  * 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;
@@ -473,8 +525,12 @@ 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.
+ * @param prefix - ID prefix identifying the plan (e.g. "PLAN").
+ * @returns Comprehensive status of all plan components.
+ * @example
+ * ```ts
+ * const status = planStatus(doc, "PLAN");
+ * ```
  */
 export function planStatus(doc, prefix) {
     const constitution = findNode(doc, `${prefix}-CONST`);
@@ -574,8 +630,12 @@ 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.
+ * @param prefix - ID prefix identifying the plan (e.g. "PLAN").
+ * @returns Per-phase progress with task counts and percentages.
+ * @example
+ * ```ts
+ * const phases = planProgress(doc, "PLAN");
+ * ```
  */
 export function planProgress(doc, prefix) {
     const protImpl = findNode(doc, `${prefix}-PROT-IMPL`);
@@ -611,16 +671,20 @@ export function planProgress(doc, prefix) {
  * Validate readiness to enter the given phase (1-indexed).
  *
  * Always checks:
- *   - Each capability ({prefix}-US-*) has a change node that implements it
- *   - Each capability has non-placeholder acceptance criteria
- *   - Each invariant ({prefix}-FR-*) has a change node that implements it
+ *   - Each capability ({prefix}-US-*) has a change node that implements it.
+ *   - Each capability has non-placeholder acceptance criteria.
+ *   - Each invariant ({prefix}-FR-*) has a change node that implements it.
  *
  * Additionally for phase N > 1:
- *   - All tasks in phase N-1 must be done
+ *   - 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

@@ -30,12 +30,24 @@ export interface SpecKitFeature {
  * 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[];
 /**
@@ -44,11 +56,19 @@ export declare function listFeatures(project: SpecKitProject): SpecKitFeature[];
  * @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

@@ -5,6 +5,14 @@ import { join } from "node:path";
  * 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"));
@@ -34,6 +42,10 @@ 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) {
@@ -70,6 +82,10 @@ export function listFeatures(project) {
  * @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);
@@ -92,6 +108,10 @@ 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;
@@ -100,6 +120,10 @@ export function resolveConstitution(project) {
  * 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 {
@@ -115,6 +139,10 @@ function checkDir(path) {
  * @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"
@@ -145,6 +173,10 @@ function parseFeatureDirectory(dir, dirName) {
  * @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

@@ -2,18 +2,32 @@
  * 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.
  * @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.
  * @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;
 /**
@@ -21,5 +35,10 @@ export declare function textToMarkdown(value: string | string[]): string;
  * 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[];