@popoverai/dotrequirements 0.11.0

package/dist/schema/parser.js

@@ -0,0 +1,295 @@
+/**
+ * Parse Markdown requirements files into typed structures.
+ */
+import YAML from 'yaml';
+import * as fs from 'fs';
+import { ValidationError, validateMetadata, } from './schemas.js';
+/**
+ * Default delimiter for requirements.
+ * Can be overridden for organization-specific preferences.
+ */
+const DEFAULT_DELIMITER = '→';
+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"
+ */
+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 {
+            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) {
+            throw new ValidationError(`Invalid criterion format at line ${i + 1}: "${line.trim()}"`, 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 YAML frontmatter from Markdown content.
+ * Returns { frontmatter, body } where frontmatter is the parsed YAML object.
+ */
+function extractFrontmatter(content) {
+    // Match YAML frontmatter: ---\n...\n---
+    const frontmatterRegex = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+    const match = content.match(frontmatterRegex);
+    if (!match) {
+        throw new ValidationError('Missing YAML frontmatter (should start with ---)');
+    }
+    const [, frontmatterYaml, body] = match;
+    let frontmatter;
+    try {
+        frontmatter = YAML.parse(frontmatterYaml);
+    }
+    catch (error) {
+        throw new ValidationError('Failed to parse YAML frontmatter', undefined, error);
+    }
+    return { frontmatter, body: body.trim() };
+}
+/**
+ * Extract requirement blocks from Markdown body.
+ * Returns a map of requirement key -> { title, blockContent }
+ *
+ * The KEY is extracted from the first line inside the code block.
+ * Headings are optional and only used for human readability.
+ */
+function extractRequirementBlocks(body) {
+    const blocks = new Map();
+    // 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];
+        // Try to find a heading immediately before this block for the title
+        // Look backwards from the match position to find the nearest heading
+        const textBeforeBlock = body.substring(0, match.index);
+        const headingMatch = textBeforeBlock.match(/^#{2,6}\s+([^\n]+)\s*$/m);
+        const title = headingMatch ? headingMatch[1].trim() : key;
+        blocks.set(key, { title, blockContent: blockContent.trim() });
+    }
+    return blocks;
+}
+/**
+ * Parse a complete requirements Markdown file.
+ */
+export function parseRequirementsFile(markdownContent) {
+    // Extract frontmatter and body
+    const { frontmatter, body } = extractFrontmatter(markdownContent);
+    // Validate metadata from frontmatter
+    const metadata = validateMetadata(frontmatter);
+    // Extract requirement blocks
+    const blocks = extractRequirementBlocks(body);
+    if (blocks.size === 0) {
+        throw new ValidationError('No requirement blocks found in document');
+    }
+    // Parse each requirement block
+    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 {
+        metadata,
+        requirements,
+    };
+}
+/**
+ * Parse requirements file from disk.
+ */
+export function parseRequirementsFromFile(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return parseRequirementsFile(content);
+    }
+    catch (error) {
+        if (error instanceof ValidationError) {
+            throw error;
+        }
+        throw new ValidationError(`Failed to read file: ${filePath}`, undefined, error);
+    }
+}
+/**
+ * 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.js.map

package/dist/schema/resolver.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Resolve label-based requirement paths to numeric paths.
+ * Supports: REQ123.given, REQ123.when.then, REQ123.given#1
+ */
+import { RequirementNode } from './schemas.js';
+/**
+ * Parse a requirement path into segments.
+ * E.g., "REQ123.given.then" → ["REQ123", "given", "then"]
+ * E.g., "REQ123.given#1" → ["REQ123", "given#1"]
+ */
+export declare function parseRequirementPath(path: string): string[];
+/**
+ * Parse a path segment that may include disambiguation.
+ * E.g., "given" → { label: "given", index: 0 }
+ * E.g., "given#2" → { label: "given", index: 2 }
+ */
+export declare function parsePathSegment(segment: string): {
+    label: string;
+    index: number;
+};
+/**
+ * Find children matching a label.
+ * Returns all children with the given label.
+ * Label matching is case-insensitive and kebab-case is normalized to spaces.
+ */
+export declare function findChildrenByLabel(node: RequirementNode, label: string): RequirementNode[];
+/**
+ * Resolve a label-based path segment to a numeric index.
+ * Returns the child node and its numeric index.
+ */
+export declare function resolvePathSegment(node: RequirementNode, segment: string): {
+    child: RequirementNode;
+    index: number;
+} | null;
+/**
+ * Resolve a complete requirement path to a node.
+ *
+ * Examples:
+ * - "REQ123" → Root requirement
+ * - "REQ123.0" → First child (numeric)
+ * - "REQ123.given" → First child with label "given"
+ * - "REQ123.given#1" → Second child with label "given"
+ * - "REQ123.when.then" → First "then" under first "when"
+ */
+export declare function resolveRequirementPath(requirements: RequirementNode[], path: string): RequirementNode | null;
+/**
+ * Resolve a path and return the full numeric path.
+ *
+ * Examples:
+ * - "REQ123.given" → "REQ123.0" (if "given" is first child)
+ * - "REQ123.when.then" → "REQ123.2.1" (numeric path)
+ */
+export declare function resolveToNumericPath(requirements: RequirementNode[], path: string): string | null;
+/**
+ * Get all possible label-based paths for a requirement.
+ * Useful for display/debugging.
+ *
+ * Returns paths like: ["REQ123", "REQ123.given", "REQ123.when", ...]
+ */
+export declare function getAllLabelPaths(node: RequirementNode, prefix?: string): string[];
+/**
+ * Check if a path is ambiguous (multiple matches for a label).
+ * Returns the number of matches, or 0 if unambiguous.
+ */
+export declare function checkPathAmbiguity(requirements: RequirementNode[], path: string): number;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/schema/resolver.js

@@ -0,0 +1,185 @@
+/**
+ * Resolve label-based requirement paths to numeric paths.
+ * Supports: REQ123.given, REQ123.when.then, REQ123.given#1
+ */
+/**
+ * Parse a requirement path into segments.
+ * E.g., "REQ123.given.then" → ["REQ123", "given", "then"]
+ * E.g., "REQ123.given#1" → ["REQ123", "given#1"]
+ */
+export function parseRequirementPath(path) {
+    return path.split('.');
+}
+/**
+ * Parse a path segment that may include disambiguation.
+ * E.g., "given" → { label: "given", index: 0 }
+ * E.g., "given#2" → { label: "given", index: 2 }
+ */
+export function parsePathSegment(segment) {
+    const match = segment.match(/^(\w+)(?:#(\d+))?$/);
+    if (!match) {
+        throw new Error(`Invalid path segment: ${segment}`);
+    }
+    return {
+        label: match[1],
+        index: match[2] ? parseInt(match[2]) : 0,
+    };
+}
+/**
+ * Normalize a label for comparison.
+ * Converts kebab-case to spaces and lowercases.
+ * Examples: "Several-words" -> "several words", "AC" -> "ac"
+ */
+function normalizeLabel(label) {
+    return label.replace(/-/g, ' ').toLowerCase();
+}
+/**
+ * Find children matching a label.
+ * Returns all children with the given label.
+ * Label matching is case-insensitive and kebab-case is normalized to spaces.
+ */
+export function findChildrenByLabel(node, label) {
+    const normalizedLabel = normalizeLabel(label);
+    return node.children.filter(child => normalizeLabel(child.label) === normalizedLabel);
+}
+/**
+ * Resolve a label-based path segment to a numeric index.
+ * Returns the child node and its numeric index.
+ */
+export function resolvePathSegment(node, segment) {
+    // Check if segment is numeric (direct index)
+    if (/^\d+$/.test(segment)) {
+        const index = parseInt(segment);
+        if (index < node.children.length) {
+            return {
+                child: node.children[index],
+                index,
+            };
+        }
+        return null;
+    }
+    // Parse label with optional disambiguation
+    const { label, index: disambiguationIndex } = parsePathSegment(segment);
+    // Find all children with this label
+    const matches = findChildrenByLabel(node, label);
+    if (matches.length === 0) {
+        return null;
+    }
+    if (disambiguationIndex >= matches.length) {
+        return null;
+    }
+    // Get the Nth match
+    const targetChild = matches[disambiguationIndex];
+    // Find the actual numeric index of this child in the parent
+    const numericIndex = node.children.indexOf(targetChild);
+    return {
+        child: targetChild,
+        index: numericIndex,
+    };
+}
+/**
+ * Resolve a complete requirement path to a node.
+ *
+ * Examples:
+ * - "REQ123" → Root requirement
+ * - "REQ123.0" → First child (numeric)
+ * - "REQ123.given" → First child with label "given"
+ * - "REQ123.given#1" → Second child with label "given"
+ * - "REQ123.when.then" → First "then" under first "when"
+ */
+export function resolveRequirementPath(requirements, path) {
+    const segments = parseRequirementPath(path);
+    if (segments.length === 0) {
+        return null;
+    }
+    // First segment should be the root requirement ID
+    const rootId = segments[0];
+    let currentNode = requirements.find(r => r.id === rootId);
+    if (!currentNode) {
+        return null;
+    }
+    // If only one segment, return the root
+    if (segments.length === 1) {
+        return currentNode;
+    }
+    // Traverse the path
+    for (let i = 1; i < segments.length; i++) {
+        const segment = segments[i];
+        const resolved = resolvePathSegment(currentNode, segment);
+        if (!resolved) {
+            return null;
+        }
+        currentNode = resolved.child;
+    }
+    return currentNode;
+}
+/**
+ * Resolve a path and return the full numeric path.
+ *
+ * Examples:
+ * - "REQ123.given" → "REQ123.0" (if "given" is first child)
+ * - "REQ123.when.then" → "REQ123.2.1" (numeric path)
+ */
+export function resolveToNumericPath(requirements, path) {
+    const node = resolveRequirementPath(requirements, path);
+    return node ? node.id : null;
+}
+/**
+ * Get all possible label-based paths for a requirement.
+ * Useful for display/debugging.
+ *
+ * Returns paths like: ["REQ123", "REQ123.given", "REQ123.when", ...]
+ */
+export function getAllLabelPaths(node, prefix = '') {
+    const currentPath = prefix ? `${prefix}.${node.label}` : node.id;
+    const paths = [currentPath];
+    for (const child of node.children) {
+        paths.push(...getAllLabelPaths(child, currentPath));
+    }
+    return paths;
+}
+/**
+ * Check if a path is ambiguous (multiple matches for a label).
+ * Returns the number of matches, or 0 if unambiguous.
+ */
+export function checkPathAmbiguity(requirements, path) {
+    const segments = parseRequirementPath(path);
+    if (segments.length === 0) {
+        return 0;
+    }
+    const rootId = segments[0];
+    let currentNode = requirements.find(r => r.id === rootId);
+    if (!currentNode) {
+        return 0;
+    }
+    if (segments.length === 1) {
+        return 0; // Root is never ambiguous
+    }
+    // Check each segment for ambiguity
+    for (let i = 1; i < segments.length; i++) {
+        const segment = segments[i];
+        // Numeric segments are never ambiguous
+        if (/^\d+$/.test(segment)) {
+            const index = parseInt(segment);
+            if (index >= currentNode.children.length) {
+                return 0; // Invalid path
+            }
+            currentNode = currentNode.children[index];
+            continue;
+        }
+        // Check for label disambiguation (#N)
+        const { label, index } = parsePathSegment(segment);
+        const matches = findChildrenByLabel(currentNode, label);
+        // If this is the last segment and there are multiple matches, it's ambiguous
+        if (i === segments.length - 1 && matches.length > 1 && index === 0) {
+            return matches.length;
+        }
+        // Otherwise, continue traversing
+        if (index >= matches.length) {
+            return 0; // Invalid path
+        }
+        currentNode = matches[index];
+    }
+    return 0; // Path is unambiguous
+}
+//# sourceMappingURL=resolver.js.map