@popoverai/dotrequirements 0.26.1 → 0.27.0

package/dist/schema/conversions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
-import type { Metadata, RequirementNode } from "./schemas.js";
+import { type Metadata, type RequirementNode } from "./schemas.js";
 /**
  * Convex requirement type (flat structure with position paths).
  * This mirrors the Convex database schema.
@@ -31,7 +31,12 @@ export declare function constructKey(prefix: string, index: number): string;
 /**
  * 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.
+ * E.g., "SYNC-CLI-CREATE-1" -> { prefix: "SYNC-CLI-CREATE", index: 1 }
+ * Returns null if key doesn't match REQUIREMENT_KEY_PATTERN, which is the
+ * sole grammar authority here: the split below is mechanical. (Deliberately
+ * NOT delegated to parseRequirementKey — it case-normalizes and enforces a
+ * 30-char prefix cap this pattern doesn't, and pattern-passing keys must
+ * never fall back to the caller's prefix=node.id path.)
  */
 export declare function parseKey(key: string): {
     prefix: string;

package/dist/schema/conversions.js

@@ -1,6 +1,7 @@
 /**
  * Convert between Convex flat representation and hierarchical RequirementNode trees.
  */
+import { REQUIREMENT_KEY_PATTERN, } from "./schemas.js";
 /**
  * Construct a requirement key from prefix and index.
  * E.g., ("REQ", 123) -> "REQ-123"
@@ -11,13 +12,21 @@ export function constructKey(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.
+ * E.g., "SYNC-CLI-CREATE-1" -> { prefix: "SYNC-CLI-CREATE", index: 1 }
+ * Returns null if key doesn't match REQUIREMENT_KEY_PATTERN, which is the
+ * sole grammar authority here: the split below is mechanical. (Deliberately
+ * NOT delegated to parseRequirementKey — it case-normalizes and enforces a
+ * 30-char prefix cap this pattern doesn't, and pattern-passing keys must
+ * never fall back to the caller's prefix=node.id path.)
  */
 export function parseKey(key) {
-    const match = key.match(/^([A-Z0-9_]+)-(\d+)$/);
-    if (!match)
+    if (!REQUIREMENT_KEY_PATTERN.test(key))
         return null;
-    return { prefix: match[1], index: parseInt(match[2], 10) };
+    const splitAt = key.lastIndexOf("-");
+    return {
+        prefix: key.slice(0, splitAt),
+        index: parseInt(key.slice(splitAt + 1), 10),
+    };
 }
 /**
  * Build a hierarchical tree from flat Convex requirements.

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

@@ -15,6 +15,19 @@ 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"
+ *
+ * This is the canonical criterion grammar (SYNC-KEY-1.4). The web editor's
+ * markdown-conversion parser mirrors this exact behavior; keep them in sync.
+ *
+ * Two behaviors are load-bearing:
+ *  - Split on the FIRST delimiter only, so an arrow inside the content
+ *    ("maps A -> B") is preserved verbatim rather than being re-consumed as a
+ *    label boundary. Everything before the first delimiter is the (optional,
+ *    freeform — custom labels are supported, see MARKDOWN_SCHEMA) label;
+ *    everything after is content.
+ *  - An empty criterion ("0. → ") is a valid criterion with content "", not a
+ *    parse failure. Returning null here would make parseRequirementBlocksFromMarkdown
+ *    reject the whole block, and would drop the criterion (and its subtree) on load.
  */
 export declare function parseCriterionLine(line: string, delimiter?: string): ParsedCriterion | null;
 /**
@@ -40,6 +53,34 @@ export declare function extractRequirementBlocks(body: string): Array<{
     key: string;
     blockContent: string;
 }>;
+/**
+ * Split raw file content into its leading YAML frontmatter and body — both
+ * derived from ONE fence match, so the two halves are complementary by
+ * construction and can never disagree about where the fence closes.
+ *
+ * Normalizes CRLF first (SYNC-FORMAT-1): frontmatter isolation must accept
+ * the same line-ending styles the parser does. Callers must use this (or the
+ * wrappers below) instead of hand-rolled regexes so every consumer agrees on
+ * what "has frontmatter" means.
+ *
+ * Returns undefined when the content has no leading frontmatter fence.
+ */
+export declare function splitFrontmatter(content: string): {
+    yaml: string;
+    body: string;
+} | undefined;
+/**
+ * The frontmatter half of splitFrontmatter: the inner YAML text, or
+ * undefined when the file has no leading fence.
+ */
+export declare function extractFrontmatterBlock(content: string): string | undefined;
+/**
+ * The body half of splitFrontmatter: the (CRLF-normalized) content with the
+ * leading frontmatter fence removed, or the whole normalized content when
+ * there is no fence. Blank lines directly after the fence are consumed so
+ * the body starts at its first real line.
+ */
+export declare function stripFrontmatterBlock(content: string): string;
 /**
  * Parse requirement blocks from markdown content (without frontmatter).
  * Use this for web editor content that doesn't have YAML frontmatter.

package/dist/schema/parser-core.js

@@ -11,24 +11,48 @@ import { ValidationError, validateKey, } from "./schemas.js";
  */
 export const DEFAULT_DELIMITER = "→";
 export const DELIMITER_PATTERN = "(?:→|->)"; // Non-capturing group for both Unicode and ASCII
+// Compiled once for the common (default-delimiter) path so parseCriterionLine
+// doesn't rebuild the same RegExp on every line.
+const DEFAULT_DELIMITER_REGEX = new RegExp(DELIMITER_PATTERN);
 /**
  * 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"
+ *
+ * This is the canonical criterion grammar (SYNC-KEY-1.4). The web editor's
+ * markdown-conversion parser mirrors this exact behavior; keep them in sync.
+ *
+ * Two behaviors are load-bearing:
+ *  - Split on the FIRST delimiter only, so an arrow inside the content
+ *    ("maps A -> B") is preserved verbatim rather than being re-consumed as a
+ *    label boundary. Everything before the first delimiter is the (optional,
+ *    freeform — custom labels are supported, see MARKDOWN_SCHEMA) label;
+ *    everything after is content.
+ *  - An empty criterion ("0. → ") is a valid criterion with content "", not a
+ *    parse failure. Returning null here would make parseRequirementBlocksFromMarkdown
+ *    reject the whole block, and would drop the criterion (and its subtree) on load.
  */
 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) {
+    // Position prefix: "0.", "1.0.", "2.3.1." — required for a criterion line.
+    const positionMatch = line.match(/^\s*(\d+(?:\.\d+)*)\.\s*/);
+    if (!positionMatch) {
         return null;
     }
+    const rest = line.slice(positionMatch[0].length);
+    const delimiterMatch = rest.match(delimiter === DELIMITER_PATTERN
+        ? DEFAULT_DELIMITER_REGEX
+        : new RegExp(delimiter));
+    if (!delimiterMatch || delimiterMatch.index === undefined) {
+        return null;
+    }
+    const label = rest.slice(0, delimiterMatch.index).trim();
+    const content = rest
+        .slice(delimiterMatch.index + delimiterMatch[0].length)
+        .trim();
     return {
-        position: match[1],
-        label: match[2] ? match[2].trim() : "", // Preserve original case, empty if no label
-        content: match[3].trim(),
+        position: positionMatch[1],
+        label, // Preserve original case; freeform (empty when no label)
+        content, // May be "" for an empty criterion
     };
 }
 /**
@@ -95,30 +119,48 @@ export function parseRequirementBlock(key, blockContent) {
         }
         const criterion = parseCriterionLine(line);
         if (!criterion) {
-            // Check if this looks like another requirement key (KEY: content format)
+            // Only a line whose prefix is shaped like a requirement KEY (uppercase
+            // prefix + "-<digits>", per REQUIREMENT_KEY_PATTERN) suggests a second
+            // requirement in the block; a stray "https://..." must not be
+            // misdiagnosed as one.
             const trimmedLine = line.trim();
-            if (/^[\w-]+:\s*.+/.test(trimmedLine)) {
+            if (/^[A-Z][A-Z-]*-\d+:\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);
         }
+        // SYNC-FORMAT-2.1: a duplicate position is structural ambiguity — reject
+        // it instead of silently dropping the earlier criterion.
+        if (criteriaByPosition.has(criterion.position)) {
+            throw new ValidationError(`Duplicate criterion position "${criterion.position}" at line ${i + 1} — each position may appear only once per requirement`, key);
+        }
         criteriaByPosition.set(criterion.position, criterion);
     }
     // Build tree from flat position paths
-    buildTreeFromPositions(root, key, criteriaByPosition);
+    const consumed = new Set();
+    buildTreeFromPositions(root, key, criteriaByPosition, consumed);
+    // SYNC-FORMAT-2.2: any criterion not attached to the tree references a
+    // missing parent position — reject it instead of silently dropping it.
+    for (const position of criteriaByPosition.keys()) {
+        if (!consumed.has(position)) {
+            const parentPosition = position.split(".").slice(0, -1).join(".");
+            throw new ValidationError(`Orphaned criterion position "${position}" — parent position "${parentPosition}" does not exist`, key);
+        }
+    }
     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) {
+function buildTreeFromPositions(root, rootKey, criteriaByPosition, consumed) {
     // 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, 10) - parseInt(b, 10));
     for (const position of topLevelPositions) {
         const criterion = criteriaByPosition.get(position);
+        consumed.add(position);
         const childNode = {
             id: `${rootKey}.${position}`,
             label: criterion.label,
@@ -126,14 +168,14 @@ function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
             children: [],
         };
         // Recursively build children
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition, consumed);
         root.children.push(childNode);
     }
 }
 /**
  * Recursively build children for a given position.
  */
-function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition) {
+function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByPosition, consumed) {
     // Find direct children (e.g., if parent is "1", find "1.0", "1.1", etc.)
     const childPositions = Array.from(criteriaByPosition.keys())
         .filter((pos) => {
@@ -158,6 +200,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
     });
     for (const position of childPositions) {
         const criterion = criteriaByPosition.get(position);
+        consumed.add(position);
         const childNode = {
             id: `${rootKey}.${position}`,
             label: criterion.label,
@@ -165,7 +208,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
             children: [],
         };
         // Recursively build grandchildren
-        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition);
+        buildChildrenFromPositions(childNode, position, rootKey, criteriaByPosition, consumed);
         parent.children.push(childNode);
     }
 }
@@ -175,6 +218,7 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
  */
 export function extractRequirementBlocks(body) {
     const blocks = [];
+    const seenKeys = new Set();
     // Find all ```dotrequirements code blocks
     const blockRegex = /```dotrequirements\n([\s\S]*?)```/gm;
     let match = blockRegex.exec(body);
@@ -190,17 +234,65 @@ export function extractRequirementBlocks(body) {
         // locally instead of erroring server-side. Validation only — the original
         // key is preserved (normalization happens downstream).
         validateKey(key);
+        // SYNC-FORMAT-2.0: a duplicate key is structural ambiguity — reject it
+        // instead of producing two requirements with the same key.
+        if (seenKeys.has(key)) {
+            throw new ValidationError(`Duplicate requirement key "${key}" — each requirement key may appear in only one block`, key);
+        }
+        seenKeys.add(key);
         blocks.push({ key, blockContent: blockContent.trim() });
         match = blockRegex.exec(body);
     }
     return blocks;
 }
+/**
+ * Split raw file content into its leading YAML frontmatter and body — both
+ * derived from ONE fence match, so the two halves are complementary by
+ * construction and can never disagree about where the fence closes.
+ *
+ * Normalizes CRLF first (SYNC-FORMAT-1): frontmatter isolation must accept
+ * the same line-ending styles the parser does. Callers must use this (or the
+ * wrappers below) instead of hand-rolled regexes so every consumer agrees on
+ * what "has frontmatter" means.
+ *
+ * Returns undefined when the content has no leading frontmatter fence.
+ */
+export function splitFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    const match = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
+    if (!match) {
+        return undefined;
+    }
+    return { yaml: match[1], body: normalized.slice(match[0].length) };
+}
+/**
+ * The frontmatter half of splitFrontmatter: the inner YAML text, or
+ * undefined when the file has no leading fence.
+ */
+export function extractFrontmatterBlock(content) {
+    return splitFrontmatter(content)?.yaml;
+}
+/**
+ * The body half of splitFrontmatter: the (CRLF-normalized) content with the
+ * leading frontmatter fence removed, or the whole normalized content when
+ * there is no fence. Blank lines directly after the fence are consumed so
+ * the body starts at its first real line.
+ */
+export function stripFrontmatterBlock(content) {
+    const split = splitFrontmatter(content);
+    if (split === undefined) {
+        return content.replace(/\r\n/g, "\n");
+    }
+    return split.body.replace(/^\n+/, "");
+}
 /**
  * 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);
+    // SYNC-FORMAT-1: normalize Windows (CRLF) line endings so content parses
+    // identically regardless of line-ending style.
+    const blocks = extractRequirementBlocks(markdownContent.replace(/\r\n/g, "\n"));
     const requirements = [];
     for (const { key, blockContent } of blocks) {
         try {
@@ -208,7 +300,10 @@ export function parseRequirementBlocksFromMarkdown(markdownContent) {
             requirements.push(reqNode);
         }
         catch (error) {
-            throw new ValidationError(`Failed to parse requirement ${key}`, key, error);
+            // Include the inner message so structural errors (duplicate position,
+            // orphaned position, ...) stay identifiable at the top level.
+            const detail = error instanceof Error && error.message ? `: ${error.message}` : "";
+            throw new ValidationError(`Failed to parse requirement ${key}${detail}`, key, error);
         }
     }
     return requirements;

package/dist/schema/parser.d.ts

@@ -1,19 +1,14 @@
 /**
  * Parse Markdown requirements files into typed structures.
+ *
+ * File-level concerns only: frontmatter isolation, metadata validation, and
+ * disk IO. All block and criterion parsing delegates to the
+ * environment-agnostic parser-core module, which the web editor and Convex
+ * also consume — one parser, so the CLI and the cloud cannot drift on what a
+ * requirements file means (SYNC-FORMAT-2.3).
  */
-import { type ParsedCriterion, type RequirementNode, type RequirementsFile } 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;
+import { type RequirementNode, type RequirementsFile } from "./schemas.js";
+export { findRequirementById, flattenRequirementTree, getAllRequirements, parseCriterionLine, parseRequirementBlock, } from "./parser-core.js";
 /**
  * Parse a complete requirements Markdown file.
  */
@@ -28,17 +23,4 @@ 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