@popoverai/dotrequirements 0.11.0

package/dist/schema/conversions.js

@@ -0,0 +1,201 @@
+/**
+ * Convert between Convex flat representation and hierarchical RequirementNode trees.
+ */
+/**
+ * Construct a requirement key from prefix and index.
+ * E.g., ("REQ", 123) -> "REQ-123"
+ */
+export function constructKey(prefix, index) {
+    return `${prefix}-${index}`;
+}
+/**
+ * Parse a requirement key into prefix and index.
+ * E.g., "REQ-123" -> { prefix: "REQ", index: 123 }
+ * Returns null if key doesn't match expected format.
+ */
+export function parseKey(key) {
+    const match = key.match(/^([A-Z0-9_]+)-(\d+)$/);
+    if (!match)
+        return null;
+    return { prefix: match[1], index: parseInt(match[2], 10) };
+}
+/**
+ * Build a hierarchical tree from flat Convex requirements.
+ * Uses position paths to reconstruct parent-child relationships.
+ */
+export function convexToRequirements(convexReqs) {
+    // Separate roots from children
+    const roots = convexReqs.filter(r => !r.rootId);
+    // Build a map of all requirements by their position path for each root
+    const reqsByRoot = new Map();
+    for (const req of convexReqs) {
+        if (req.rootId) {
+            let rootMap = reqsByRoot.get(req.rootId);
+            if (!rootMap) {
+                rootMap = new Map();
+                reqsByRoot.set(req.rootId, rootMap);
+            }
+            rootMap.set(req.position || '', req);
+        }
+    }
+    // Build trees for each root
+    return roots.map(root => buildTreeFromPositions(root, reqsByRoot.get(root._id)));
+}
+/**
+ * Recursively build a RequirementNode tree from position-based flat structure.
+ */
+function buildTreeFromPositions(convexReq, positionMap) {
+    // Derive the key from prefix and index
+    const key = constructKey(convexReq.prefix, convexReq.index);
+    const node = {
+        id: key,
+        label: convexReq.label,
+        content: convexReq.content,
+        children: [],
+        metadata: {
+            convexId: convexReq._id,
+            rootId: convexReq.rootId,
+            position: convexReq.position,
+            updatedAt: convexReq.updatedAt,
+            externalLinks: convexReq.externalLinks,
+            // Store prefix/index for round-trip
+            prefix: convexReq.prefix,
+            index: convexReq.index,
+            documentId: convexReq.documentId,
+        },
+    };
+    if (!positionMap) {
+        return node;
+    }
+    // Find direct children based on position paths
+    // If this is a root (no position), find children at positions like ".0", ".1"
+    // If this has position ".0", find children at positions like ".0.0", ".0.1"
+    const currentPosition = convexReq.position || '';
+    const childPositionPattern = currentPosition
+        ? new RegExp(`^${currentPosition.replace(/\./g, '\\.')}\\.\\d+$`)
+        : /^\.\d+$/;
+    const children = [];
+    for (const [pos, req] of positionMap.entries()) {
+        if (childPositionPattern.test(pos)) {
+            children.push(req);
+        }
+    }
+    // Sort children by position
+    const sortedChildren = children.sort((a, b) => {
+        return comparePositions(a.position || '', b.position || '');
+    });
+    // Recursively build child nodes
+    node.children = sortedChildren.map(child => buildTreeFromPositions(child, positionMap));
+    return node;
+}
+/**
+ * Compare position strings for sorting.
+ * Positions are like ".0", ".1", ".0.0", ".0.1"
+ */
+function comparePositions(a, b) {
+    const aParts = a.split('.').filter(Boolean).map(Number);
+    const bParts = b.split('.').filter(Boolean).map(Number);
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const aVal = aParts[i] ?? -1;
+        const bVal = bParts[i] ?? -1;
+        if (aVal !== bVal)
+            return aVal - bVal;
+    }
+    return 0;
+}
+/**
+ * Flatten a hierarchical structure back to Convex flat format.
+ * Generates position paths for each node.
+ */
+export function requirementsToConvex(nodes, projectId, documentId) {
+    const result = [];
+    for (const node of nodes) {
+        flattenNode(node, projectId, undefined, undefined, result, documentId);
+    }
+    return result;
+}
+/**
+ * Recursively flatten a RequirementNode into Convex format.
+ */
+function flattenNode(node, projectId, rootId, position, result, documentId) {
+    // Determine if this is a root or child
+    const isRoot = !rootId && !position;
+    // Generate convex ID from metadata or create placeholder
+    const convexId = node.metadata?.convexId || `temp_${node.id}`;
+    // Get prefix/index from metadata (if from round-trip) or parse from node.id
+    let prefix;
+    let index;
+    if (node.metadata?.prefix && typeof node.metadata?.index === 'number') {
+        // Round-trip case: use stored prefix/index
+        prefix = node.metadata.prefix;
+        index = node.metadata.index;
+    }
+    else {
+        // Parse from node.id (e.g., "REQ-123" -> { prefix: "REQ", index: 123 })
+        const parsed = parseKey(node.id);
+        if (parsed) {
+            prefix = parsed.prefix;
+            index = parsed.index;
+        }
+        else {
+            // Fallback: use node.id as prefix with index 0 (shouldn't happen with valid keys)
+            prefix = node.id;
+            index = 0;
+        }
+    }
+    const convexReq = {
+        _id: convexId,
+        prefix,
+        index,
+        documentId,
+        label: node.label,
+        content: node.content,
+        projectId,
+        rootId: isRoot ? undefined : rootId,
+        position: isRoot ? undefined : position,
+        metadata: node.metadata,
+        externalLinks: node.metadata?.externalLinks,
+        updatedAt: node.metadata?.updatedAt || Date.now(),
+    };
+    result.push(convexReq);
+    // Process children
+    node.children.forEach((child, childIdx) => {
+        const childPosition = position ? `${position}.${childIdx}` : `.${childIdx}`;
+        const childRootId = isRoot ? convexId : rootId;
+        flattenNode(child, projectId, childRootId, childPosition, result, documentId);
+    });
+}
+/**
+ * Build metadata from project info and pull time.
+ * DOC-HEADER-11.3: When pulling, include defaultPrefix in the frontmatter.
+ */
+export function buildMetadata(projectId, version = 1, document) {
+    return {
+        projectId,
+        pulledAt: new Date().toISOString(),
+        version,
+        document,
+    };
+}
+/**
+ * Extract unique requirement keys from Convex data.
+ * Useful for detecting duplicates or tracking which requirements exist.
+ */
+export function extractRequirementKeys(convexReqs) {
+    return new Set(convexReqs.map(r => constructKey(r.prefix, r.index)));
+}
+/**
+ * Group Convex requirements by their root.
+ * Returns a map of rootId → children.
+ */
+export function groupByRoot(convexReqs) {
+    const groups = new Map();
+    for (const req of convexReqs) {
+        const key = req.rootId || undefined;
+        const group = groups.get(key) || [];
+        group.push(req);
+        groups.set(key, group);
+    }
+    return groups;
+}
+//# sourceMappingURL=conversions.js.map

package/dist/schema/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Markdown Requirements Schema
+ *
+ * This module provides types, validation, parsing, and building utilities
+ * for the Markdown requirements format.
+ */
+export { MetadataSchema, RequirementNodeSchema, RequirementsFileSchema, ParsedCriterionSchema, RequirementPrefixSchema, RequirementKeySchema, REQUIREMENT_PREFIX_PATTERN, REQUIREMENT_KEY_PATTERN, ValidationError, validateMetadata, validateRequirementNode, validateRequirementsFile, validatePrefix, validateKey, validateForPush, CONVEX_ID_PATTERN, normalizePrefix, parseRequirementKey, buildRequirementKey, } from './schemas.js';
+export type { Metadata, RequirementNode, RequirementsFile, ParsedCriterion, RequirementPrefix, RequirementKey, PushValidationResult, } from './schemas.js';
+export { parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser.js';
+export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsFile, } from './builder.js';
+export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
+export type { ConvexRequirement, } from './conversions.js';
+export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/schema/index.js

@@ -0,0 +1,24 @@
+/**
+ * Markdown Requirements Schema
+ *
+ * This module provides types, validation, parsing, and building utilities
+ * for the Markdown requirements format.
+ */
+// Schemas and types
+export { 
+// Zod schemas
+MetadataSchema, RequirementNodeSchema, RequirementsFileSchema, ParsedCriterionSchema, RequirementPrefixSchema, RequirementKeySchema, 
+// Patterns (for external validation)
+REQUIREMENT_PREFIX_PATTERN, REQUIREMENT_KEY_PATTERN, 
+// Validation
+ValidationError, validateMetadata, validateRequirementNode, validateRequirementsFile, validatePrefix, validateKey, validateForPush, CONVEX_ID_PATTERN, 
+// Prefix/key utilities
+normalizePrefix, parseRequirementKey, buildRequirementKey, } from './schemas.js';
+// Parsing
+export { parseCriterionLine, parseRequirementBlock, parseRequirementsFile, parseRequirementsFromFile, flattenRequirementTree, findRequirementById, getAllRequirements, } from './parser.js';
+// Building
+export { buildRequirementsMarkdown, buildRequirementMarkdown, buildRequirementsFile, } from './builder.js';
+// Path resolution
+export { parseRequirementPath, parsePathSegment, findChildrenByLabel, resolvePathSegment, resolveRequirementPath, resolveToNumericPath, getAllLabelPaths, checkPathAmbiguity, } from './resolver.js';
+export { convexToRequirements, requirementsToConvex, buildMetadata, extractRequirementKeys, groupByRoot, constructKey, parseKey, } from './conversions.js';
+//# sourceMappingURL=index.js.map

package/dist/schema/parser-core.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Core parsing functions for dotrequirements format.
+ *
+ * This module contains pure parsing functions with no Node.js dependencies,
+ * making it safe to import in Convex runtime or browser environments.
+ */
+import { RequirementNode, ParsedCriterion } from './schemas.js';
+/**
+ * Default delimiter for requirements.
+ * Can be overridden for organization-specific preferences.
+ */
+export declare const DEFAULT_DELIMITER = "\u2192";
+export declare const DELIMITER_PATTERN = "(?:\u2192|->)";
+/**
+ * Parse a criterion line in "position. Label → content" format.
+ * Example: "0. Given → user has valid credentials"
+ * Also supports optional label: "0. → user has valid credentials"
+ */
+export declare function parseCriterionLine(line: string, delimiter?: string): ParsedCriterion | null;
+/**
+ * Parse the first line of a dotrequirements block (the root requirement).
+ * Format: "KEY: content" or "Label → content" or "→ content"
+ */
+export declare function parseRootLine(line: string, delimiter?: string): {
+    key?: string;
+    label: string;
+    content: string;
+};
+/**
+ * Parse a dotrequirements fenced block into a RequirementNode tree.
+ * First line is the requirement content (with optional arrow format).
+ * Subsequent lines are criteria with position paths.
+ */
+export declare function parseRequirementBlock(key: string, blockContent: string): RequirementNode;
+/**
+ * Extract requirement blocks from Markdown body (no frontmatter).
+ * Returns an array of { key, blockContent } for each dotrequirements block found.
+ */
+export declare function extractRequirementBlocks(body: string): Array<{
+    key: string;
+    blockContent: string;
+}>;
+/**
+ * Parse requirement blocks from markdown content (without frontmatter).
+ * Use this for web editor content that doesn't have YAML frontmatter.
+ */
+export declare function parseRequirementBlocksFromMarkdown(markdownContent: string): RequirementNode[];
+/**
+ * Flatten a requirement tree into a list of all nodes.
+ * Useful for searching or displaying all requirements.
+ */
+export declare function flattenRequirementTree(node: RequirementNode): RequirementNode[];
+/**
+ * Find a requirement by its ID in a tree.
+ */
+export declare function findRequirementById(nodes: RequirementNode[], id: string): RequirementNode | undefined;
+/**
+ * Get all requirements from multiple files as a flat list.
+ */
+export declare function getAllRequirements(requirements: RequirementNode[]): RequirementNode[];
+//# sourceMappingURL=parser-core.d.ts.map

package/dist/schema/parser-core.js

@@ -0,0 +1,247 @@
+/**
+ * Core parsing functions for dotrequirements format.
+ *
+ * This module contains pure parsing functions with no Node.js dependencies,
+ * making it safe to import in Convex runtime or browser environments.
+ */
+import { ValidationError, } from './schemas.js';
+/**
+ * Default delimiter for requirements.
+ * Can be overridden for organization-specific preferences.
+ */
+export const DEFAULT_DELIMITER = '→';
+export const DELIMITER_PATTERN = '(?:→|->)'; // Non-capturing group for both Unicode and ASCII
+/**
+ * Parse a criterion line in "position. Label → content" format.
+ * Example: "0. Given → user has valid credentials"
+ * Also supports optional label: "0. → user has valid credentials"
+ */
+export function parseCriterionLine(line, delimiter = DELIMITER_PATTERN) {
+    // Match: position + period + space + optional(label + space) + delimiter + space + content
+    // Position can be: 0, 1.0, 2.3.1, etc.
+    // Label can contain any characters except the delimiter
+    const pattern = new RegExp(`^\\s*(\\d+(?:\\.\\d+)*)\\.\\s*(?:(.+?)\\s+)?${delimiter}\\s*(.+)$`);
+    const match = line.match(pattern);
+    if (!match) {
+        return null;
+    }
+    return {
+        position: match[1],
+        label: match[2] ? match[2].trim() : '', // Preserve original case, empty if no label
+        content: match[3].trim(),
+    };
+}
+/**
+ * Parse the first line of a dotrequirements block (the root requirement).
+ * Format: "KEY: content" or "Label → content" or "→ content"
+ */
+export function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
+    const trimmed = line.trim();
+    // Try to match: KEY + colon + content (explicit key format)
+    // KEY must be followed by colon (not arrow) to distinguish from "Label → content"
+    const keyMatch = trimmed.match(/^([\w-]+):\s*(.+)$/);
+    if (keyMatch) {
+        return {
+            key: keyMatch[1],
+            label: '', // Keys use empty string for unlabeled requirements
+            content: keyMatch[2].trim(),
+        };
+    }
+    // Match: optional(label + space) + delimiter + space + content
+    const pattern = new RegExp(`^(?:(.+?)\\s+)?${delimiter}\\s*(.+)$`);
+    const match = trimmed.match(pattern);
+    if (!match) {
+        // If no delimiter found, treat entire line as content with empty label
+        return {
+            label: '',
+            content: trimmed,
+        };
+    }
+    return {
+        label: match[1] ? match[1].trim() : '',
+        content: match[2].trim(),
+    };
+}
+/**
+ * Parse a dotrequirements fenced block into a RequirementNode tree.
+ * First line is the requirement content (with optional arrow format).
+ * Subsequent lines are criteria with position paths.
+ */
+export function parseRequirementBlock(key, blockContent) {
+    const lines = blockContent.trim().split('\n');
+    if (lines.length === 0) {
+        throw new ValidationError('Empty requirement block', key);
+    }
+    // First line is the requirement content
+    const rootParsed = parseRootLine(lines[0]);
+    if (!rootParsed.content) {
+        throw new ValidationError('Requirement content (first line) cannot be empty', key);
+    }
+    const root = {
+        id: key,
+        // Root requirements always use "requirementHeader" label for indexing/querying
+        // The markdown format doesn't preserve root labels, but we standardize on this value
+        label: 'requirementHeader',
+        content: rootParsed.content,
+        children: [],
+    };
+    // Parse criteria lines
+    const criteriaByPosition = new Map();
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        // Skip empty lines and comments
+        if (!line.trim() || line.trim().startsWith('#')) {
+            continue;
+        }
+        const criterion = parseCriterionLine(line);
+        if (!criterion) {
+            // Check if this looks like another requirement key (KEY: content format)
+            const trimmedLine = line.trim();
+            if (/^[\w-]+:\s*.+/.test(trimmedLine)) {
+                throw new ValidationError(`Multiple requirements in single block. Found "${trimmedLine.split(':')[0]}" at line ${i + 1}, but each requirement must have its own \`\`\`dotrequirements code block.`, key);
+            }
+            throw new ValidationError(`Invalid criterion format at line ${i + 1}: "${trimmedLine}". Expected format: "N. Label → content" (e.g., "0. Given → user is logged in")`, key);
+        }
+        criteriaByPosition.set(criterion.position, criterion);
+    }
+    // Build tree from flat position paths
+    buildTreeFromPositions(root, key, criteriaByPosition);
+    return root;
+}
+/**
+ * Build a tree structure from flat position paths.
+ * Positions like "0", "1", "1.0", "1.1", "1.1.0" define the hierarchy.
+ */
+function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
+    // Get all top-level children (single digit positions: "0", "1", "2")
+    const topLevelPositions = Array.from(criteriaByPosition.keys())
+        .filter(pos => !pos.includes('.'))
+        .sort((a, b) => parseInt(a) - parseInt(b));
+    for (const position of topLevelPositions) {
+        const criterion = criteriaByPosition.get(position);
+        const childNode = {
+            id: `${rootKey}.${position}`,
+            label: criterion.label,
+            content: criterion.content,
+            children: [],
+        };
+        // Recursively build children
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        root.children.push(childNode);
+    }
+}
+/**
+ * Recursively build children for a given position.
+ */
+function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition) {
+    // Find direct children (e.g., if parent is "1", find "1.0", "1.1", etc.)
+    const childPositions = Array.from(criteriaByPosition.keys())
+        .filter(pos => {
+        const parts = pos.split('.');
+        const parentParts = parentPosition.split('.');
+        // Must be exactly one level deeper
+        if (parts.length !== parentParts.length + 1) {
+            return false;
+        }
+        // All parent parts must match
+        for (let i = 0; i < parentParts.length; i++) {
+            if (parts[i] !== parentParts[i]) {
+                return false;
+            }
+        }
+        return true;
+    })
+        .sort((a, b) => {
+        const aLast = parseInt(a.split('.').pop());
+        const bLast = parseInt(b.split('.').pop());
+        return aLast - bLast;
+    });
+    for (const position of childPositions) {
+        const criterion = criteriaByPosition.get(position);
+        const childNode = {
+            id: `${rootKey}.${position}`,
+            label: criterion.label,
+            content: criterion.content,
+            children: [],
+        };
+        // Recursively build grandchildren
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        parent.children.push(childNode);
+    }
+}
+/**
+ * Extract requirement blocks from Markdown body (no frontmatter).
+ * Returns an array of { key, blockContent } for each dotrequirements block found.
+ */
+export function extractRequirementBlocks(body) {
+    const blocks = [];
+    // Find all ```dotrequirements code blocks
+    const blockRegex = /```dotrequirements\n([\s\S]*?)```/gm;
+    let match;
+    while ((match = blockRegex.exec(body)) !== null) {
+        const blockContent = match[1];
+        // Extract key from first line of block (format: "KEY: content")
+        const firstLineMatch = blockContent.match(/^([\w-]+):\s*(.+)/);
+        if (!firstLineMatch) {
+            throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
+        }
+        const key = firstLineMatch[1];
+        blocks.push({ key, blockContent: blockContent.trim() });
+    }
+    return blocks;
+}
+/**
+ * Parse requirement blocks from markdown content (without frontmatter).
+ * Use this for web editor content that doesn't have YAML frontmatter.
+ */
+export function parseRequirementBlocksFromMarkdown(markdownContent) {
+    const blocks = extractRequirementBlocks(markdownContent);
+    const requirements = [];
+    for (const { key, blockContent } of blocks) {
+        try {
+            const reqNode = parseRequirementBlock(key, blockContent);
+            requirements.push(reqNode);
+        }
+        catch (error) {
+            throw new ValidationError(`Failed to parse requirement ${key}`, key, error);
+        }
+    }
+    return requirements;
+}
+/**
+ * Flatten a requirement tree into a list of all nodes.
+ * Useful for searching or displaying all requirements.
+ */
+export function flattenRequirementTree(node) {
+    const result = [node];
+    for (const child of node.children) {
+        result.push(...flattenRequirementTree(child));
+    }
+    return result;
+}
+/**
+ * Find a requirement by its ID in a tree.
+ */
+export function findRequirementById(nodes, id) {
+    for (const node of nodes) {
+        if (node.id === id) {
+            return node;
+        }
+        const found = findRequirementById(node.children, id);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+/**
+ * Get all requirements from multiple files as a flat list.
+ */
+export function getAllRequirements(requirements) {
+    const all = [];
+    for (const req of requirements) {
+        all.push(...flattenRequirementTree(req));
+    }
+    return all;
+}
+//# sourceMappingURL=parser-core.js.map

package/dist/schema/parser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Parse Markdown requirements files into typed structures.
+ */
+import { RequirementNode, RequirementsFile, ParsedCriterion } from './schemas.js';
+/**
+ * Parse a criterion line in "position. Label → content" format.
+ * Example: "0. Given → user has valid credentials"
+ * Also supports optional label: "0. → user has valid credentials"
+ */
+export declare function parseCriterionLine(line: string, delimiter?: string): ParsedCriterion | null;
+/**
+ * Parse a dotrequirements fenced block into a RequirementNode tree.
+ * First line is the requirement content (with optional arrow format).
+ * Subsequent lines are criteria with position paths.
+ */
+export declare function parseRequirementBlock(key: string, blockContent: string): RequirementNode;
+/**
+ * Parse a complete requirements Markdown file.
+ */
+export declare function parseRequirementsFile(markdownContent: string): {
+    metadata: RequirementsFile['_meta'];
+    requirements: RequirementNode[];
+};
+/**
+ * Parse requirements file from disk.
+ */
+export declare function parseRequirementsFromFile(filePath: string): {
+    metadata: RequirementsFile['_meta'];
+    requirements: RequirementNode[];
+};
+/**
+ * Flatten a requirement tree into a list of all nodes.
+ * Useful for searching or displaying all requirements.
+ */
+export declare function flattenRequirementTree(node: RequirementNode): RequirementNode[];
+/**
+ * Find a requirement by its ID in a tree.
+ */
+export declare function findRequirementById(nodes: RequirementNode[], id: string): RequirementNode | undefined;
+/**
+ * Get all requirements from multiple files as a flat list.
+ */
+export declare function getAllRequirements(requirements: RequirementNode[]): RequirementNode[];
+//# sourceMappingURL=parser.d.ts.map