@popoverai/dotrequirements 0.26.1 → 0.26.2

package/dist/push/core.js

@@ -12,8 +12,10 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
+import YAML from "yaml";
 import { api } from "../convex.js";
 import { buildRequirementsFile, getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
+import { extractFrontmatterBlock, stripFrontmatterBlock, } from "../schema/parser-core.js";
 /** Base URL of the web app, where synced documents are reviewed. */
 export const WEB_APP_URL = "https://app.dotrequirements.io";
 // ============================================================================
@@ -23,15 +25,63 @@ export const WEB_APP_URL = "https://app.dotrequirements.io";
  * Extract markdown content from a file, stripping YAML frontmatter.
  */
 export function extractMarkdownContent(rawContent) {
-    // Match YAML frontmatter: starts with ---, ends with ---
-    const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n*/);
-    if (frontmatterMatch) {
-        return rawContent.slice(frontmatterMatch[0].length);
+    // Shared CRLF-normalizing helper (SYNC-FORMAT-1): the stripped body is
+    // pushed as the document's canonical markdownContent (SYNC-ARCH-1), so a
+    // CRLF-authored file must not leak its frontmatter fence into the cloud
+    // body.
+    return stripFrontmatterBlock(rawContent);
+}
+/**
+ * DOC-HEADER-14: parse the frontmatter block as the user wrote it, keeping
+ * keys the schema doesn't recognize (Zod strip-mode parsing discards them).
+ */
+function extractRawFrontmatter(rawContent) {
+    // Shared helper normalizes CRLF (SYNC-FORMAT-1) so a Windows-saved file's
+    // custom keys survive the rewrite too (DOC-HEADER-14).
+    const frontmatterBlock = extractFrontmatterBlock(rawContent);
+    if (frontmatterBlock === undefined) {
+        return undefined;
+    }
+    try {
+        const parsed = YAML.parse(frontmatterBlock);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // Unparseable frontmatter would have failed schema parsing already;
+        // treat as no extra keys to preserve.
     }
-    return rawContent;
+    return undefined;
+}
+/**
+ * DOC-HEADER-14: merge the validated (and push-updated) metadata over the raw
+ * frontmatter so unrecognized keys survive the rewrite while the fields the
+ * push owns (document ID, pulledAt, defaultPrefix, version) stay updated.
+ */
+function mergeMetadataWithRawFrontmatter(metadata, rawFrontmatter) {
+    if (!rawFrontmatter) {
+        return metadata;
+    }
+    const merged = { ...rawFrontmatter, ...metadata };
+    const rawDocument = rawFrontmatter.document;
+    if (metadata.document &&
+        rawDocument &&
+        typeof rawDocument === "object" &&
+        !Array.isArray(rawDocument)) {
+        merged.document = {
+            ...rawDocument,
+            ...metadata.document,
+        };
+    }
+    return merged;
 }
 /**
  * Parse files for push. Returns parsed files with metadata and content.
+ *
+ * Throws (via `parseRequirementsFromFile`) if any file is syntactically
+ * invalid. Callers that need one bad file not to abort the batch should parse
+ * files individually and collect failures (see the MCP push handler, #45).
  */
 export function parseFilesForPush(filePaths) {
     const parsedFiles = [];
@@ -46,12 +96,16 @@ export function parseFilesForPush(filePaths) {
         const markdownContent = extractMarkdownContent(rawContent);
         // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified
         const doc = parsed.metadata.document;
+        let inferredDefaultPrefix = false;
         if (doc && !doc.defaultPrefix && flatRequirements.length > 0) {
             const firstReq = flatRequirements[0];
             if (firstReq) {
                 const parsedKey = parseRequirementKey(firstReq.id);
                 if (parsedKey) {
                     doc.defaultPrefix = parsedKey.prefix;
+                    // DOC-HEADER-11.4: remember the prefix was inferred, not authored —
+                    // the metadata mutation above makes the two indistinguishable later
+                    inferredDefaultPrefix = true;
                 }
             }
         }
@@ -60,11 +114,67 @@ export function parseFilesForPush(filePaths) {
             metadata: parsed.metadata,
             markdownContent,
             requirementCount: flatRequirements.length,
+            // DOC-HEADER-14: keep the user's frontmatter (unrecognized keys included)
+            rawFrontmatter: extractRawFrontmatter(rawContent),
+            inferredDefaultPrefix,
         });
         totalRequirements += flatRequirements.length;
     }
+    // SYNC-FAIL-3.0: abort before any cloud write when two files claim the
+    // same document
+    assertNoDuplicateDocumentIds(parsedFiles);
     return { parsedFiles, totalRequirements };
 }
+/**
+ * SYNC-FAIL-4.0: parse files one at a time so a single invalid file cannot
+ * abort the batch — its failure is collected per file while the valid files
+ * still parse. Shared by the CLI push command and the MCP push handler (#45)
+ * so their isolation semantics cannot drift.
+ *
+ * Note: cross-file checks that need the whole batch (e.g. SYNC-FAIL-3
+ * duplicate document IDs) are enforced downstream in dryRunPush, not here.
+ */
+export function parseFilesForPushIndividually(filePaths) {
+    const parsedFiles = [];
+    let totalRequirements = 0;
+    const parseFailures = [];
+    for (const filePath of filePaths) {
+        try {
+            const result = parseFilesForPush([filePath]);
+            parsedFiles.push(...result.parsedFiles);
+            totalRequirements += result.totalRequirements;
+        }
+        catch (error) {
+            parseFailures.push({
+                filePath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return { parsedFiles, totalRequirements, parseFailures };
+}
+/**
+ * SYNC-FAIL-3: two ParsedFiles carrying the same document.id would both push
+ * as updates to one cloud document — last writer wins and the first spec is
+ * silently destroyed. Abort instead, naming both files and the shared id.
+ */
+export function assertNoDuplicateDocumentIds(parsedFiles) {
+    const filesByDocId = new Map();
+    for (const file of parsedFiles) {
+        const docId = file.metadata.document?.id;
+        if (!docId)
+            continue;
+        const existingPath = filesByDocId.get(docId);
+        if (existingPath) {
+            throw new Error(`Two files claim the same document ID "${docId}":\n` +
+                `  ${existingPath}\n` +
+                `  ${file.filePath}\n` +
+                `Each file must map to its own cloud document. Remove the "id:" line ` +
+                `from the copy's frontmatter so it pushes as a new document, then push again.`);
+        }
+        filesByDocId.set(docId, file.filePath);
+    }
+}
 // ============================================================================
 // Dry Run
 // ============================================================================
@@ -72,6 +182,9 @@ export function parseFilesForPush(filePaths) {
  * Execute dry run phase: validate all files against Convex and detect conflicts.
  */
 export async function dryRunPush(parsedFiles, credentials) {
+    // SYNC-FAIL-3.0: callers that assemble ParsedFiles themselves (e.g. the
+    // MCP handler parses files one at a time) still abort before any cloud write
+    assertNoDuplicateDocumentIds(parsedFiles);
     const client = new ConvexHttpClient(credentials.convexUrl);
     const dryRunResults = [];
     // Phase 1: Dry run to categorize all files
@@ -174,6 +287,7 @@ export async function executePush(dryRunResult, credentials) {
     const errors = [];
     const importWarnings = [];
     const synced = [];
+    const writeBackWarnings = [];
     for (const { file, result } of pushableFiles) {
         const doc = file.metadata.document;
         const fileName = path.basename(file.filePath);
@@ -211,18 +325,31 @@ export async function executePush(dryRunResult, credentials) {
                 doc.id = pushResult;
                 file.metadata.pulledAt = new Date().toISOString();
                 file.metadata.version = 1;
-                const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 created++;
             }
             else {
                 // Update pulledAt to reflect this push
                 file.metadata.pulledAt = new Date().toISOString();
                 file.metadata.version = (file.metadata.version || 0) + 1;
-                const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 updated++;
             }
+            // SYNC-FAIL-2: the local write-back is separate from the cloud save —
+            // the cloud document already exists at this point, so a write-back
+            // failure is a warning on a synced document, never a push failure
+            // (which would invite a retry that mints a duplicate cloud document).
+            try {
+                // DOC-HEADER-14: unrecognized frontmatter keys survive the rewrite
+                const updatedContent = buildRequirementsFile(mergeMetadataWithRawFrontmatter(file.metadata, file.rawFrontmatter), file.markdownContent);
+                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
+            }
+            catch (writeErr) {
+                writeBackWarnings.push({
+                    fileName,
+                    filePath: file.filePath,
+                    documentId: pushResult,
+                    error: writeErr instanceof Error ? writeErr.message : String(writeErr),
+                });
+            }
             // SYNC-LAND-1: every synced document gets its web URL in the result
             synced.push({
                 fileName,
@@ -231,10 +358,21 @@ export async function executePush(dryRunResult, credentials) {
             });
         }
         catch (err) {
-            errors.push({ fileName, error: errorDisplayMessage(err) });
+            errors.push({
+                fileName,
+                filePath: file.filePath,
+                error: errorDisplayMessage(err),
+            });
         }
     }
-    return { created, updated, errors, importWarnings, synced };
+    return {
+        created,
+        updated,
+        errors,
+        importWarnings,
+        synced,
+        writeBackWarnings,
+    };
 }
 /**
  * Servers throw ConvexError({kind, message}) for expected failures (e.g.

package/dist/push/index.d.ts

@@ -4,5 +4,5 @@
  * Shared push logic for syncing local requirements files to the cloud.
  * Used by both CLI push command and MCP push_requirements tool.
  */
-export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, WEB_APP_URL, } from "./core.js";
+export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type ParseFailure, type PushCredentials, type PushResult, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -6,5 +6,5 @@
  */
 export { dryRunPush, executePush, 
 // Functions
-extractMarkdownContent, parseFilesForPush, WEB_APP_URL, } from "./core.js";
+extractMarkdownContent, parseFilesForPush, parseFilesForPushIndividually, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/requirements/cloud-coverage.d.ts

@@ -27,9 +27,19 @@ export interface ProjectCoverageRecord {
     untested: string[];
 }
 /**
- * Query cloud for coverage on a single requirement.
+ * Query cloud for coverage on a single requirement, optionally filtered by
+ * branch or recorded-since timestamp.
+ *
+ * The hosted query takes no branch/since parameters, so the filters are
+ * applied client-side over the per-branch rollup (`allBranches`). When no
+ * entries match, the returned record has `lastTestedAt: null` and an empty
+ * `allBranches` so callers can report "no records match" instead of falling
+ * back to coverage from other branches or times (REPORT-CLOUD-1.7).
  */
-export declare function getRequirementCoverage(requirementKey: string, projectId: string, projectSecret: string, convexUrl: string): Promise<RequirementCoverageRecord>;
+export declare function getRequirementCoverage(requirementKey: string, projectId: string, projectSecret: string, convexUrl: string, options?: {
+    branch?: string;
+    sinceTimestamp?: number;
+}): Promise<RequirementCoverageRecord>;
 /**
  * Query cloud for project-wide coverage summary, optionally filtered by
  * branch or recorded-since timestamp.

package/dist/requirements/cloud-coverage.js

@@ -4,9 +4,16 @@
  * tool and the CLI `report` verb's `--source cloud` mode.
  */
 /**
- * Query cloud for coverage on a single requirement.
+ * Query cloud for coverage on a single requirement, optionally filtered by
+ * branch or recorded-since timestamp.
+ *
+ * The hosted query takes no branch/since parameters, so the filters are
+ * applied client-side over the per-branch rollup (`allBranches`). When no
+ * entries match, the returned record has `lastTestedAt: null` and an empty
+ * `allBranches` so callers can report "no records match" instead of falling
+ * back to coverage from other branches or times (REPORT-CLOUD-1.7).
  */
-export async function getRequirementCoverage(requirementKey, projectId, projectSecret, convexUrl) {
+export async function getRequirementCoverage(requirementKey, projectId, projectSecret, convexUrl, options) {
     const response = await fetch(`${convexUrl}/api/query`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
@@ -27,7 +34,27 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
     if (json.status === "error") {
         throw new Error(`Convex query failed: ${json.errorMessage}`);
     }
-    return json.value;
+    const record = json.value;
+    const { branch, sinceTimestamp } = options ?? {};
+    if (branch === undefined && sinceTimestamp === undefined) {
+        return record;
+    }
+    const matching = record.allBranches.filter((b) => (branch === undefined || b.branch === branch) &&
+        (sinceTimestamp === undefined || b.lastTestedAt > sinceTimestamp));
+    let newest;
+    for (const b of matching) {
+        if (!newest || b.lastTestedAt > newest.lastTestedAt) {
+            newest = b;
+        }
+    }
+    return {
+        requirementKey: record.requirementKey,
+        lastTestedAt: newest?.lastTestedAt ?? null,
+        branch: newest?.branch ?? null,
+        testFile: newest?.testFile ?? null,
+        testLine: newest?.testLine ?? null,
+        allBranches: matching,
+    };
 }
 /**
  * Query cloud for project-wide coverage summary, optionally filtered by

package/dist/requirements/grep.d.ts

@@ -19,9 +19,14 @@ export declare function findTestsForRequirement(workspaceRoot: string, requireme
  */
 export declare function findRequirementsInFile(filePath: string): Promise<TestReference[]>;
 /**
- * Find all requirement references in the entire workspace
+ * Find all requirement references in the entire workspace.
  *
- * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ * Backed by AST parsing (the same extraction used by
+ * getReferencedRequirementIds) rather than line-oriented grep, so that:
+ *  - commented-out `requirement(...)` calls are NOT counted as live references, and
+ *  - `requirement(...)` calls wrapped across multiple lines are found, and
+ *  - every string-literal argument of a multi-arg `requirement("A", "B")` call
+ *    is captured (not just the first).
  */
 export declare function findAllTestReferences(workspaceRoot: string): Promise<TestReference[]>;
 /**

package/dist/requirements/grep.js

@@ -37,12 +37,16 @@ export async function findTestsForRequirement(workspaceRoot, requirementId) {
                 "ts",
                 "--type",
                 "js",
-                "--type",
-                "tsx",
-                "--type",
-                "jsx",
                 workspaceRoot,
-            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // ripgrep returns non-zero on no matches
+            ], { maxBuffer: 10 * 1024 * 1024 }).catch((err) => {
+                // ripgrep exits non-zero on no matches (code 1). A code-2 failure is a
+                // real error (bad flag, unreadable path) — surface its stderr rather
+                // than silently treating it as "no matches".
+                if (err?.code && err.code !== 1 && err.stderr) {
+                    console.error(`ripgrep error: ${err.stderr}`);
+                }
+                return { stdout: "" };
+            });
             output = stdout;
         }
         else {
@@ -75,6 +79,7 @@ export async function findRequirementsInFile(filePath) {
     const t = await import("@babel/types");
     const fs = await import("node:fs");
     const pathModule = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
     const results = [];
     // Resolve relative paths from current working directory
     let resolvedPath = pathModule.isAbsolute(filePath)
@@ -82,7 +87,11 @@ export async function findRequirementsInFile(filePath) {
         : pathModule.resolve(process.cwd(), filePath);
     // If file doesn't exist and path is relative, try resolving from CLI package root
     if (!pathModule.isAbsolute(filePath) && !fs.existsSync(resolvedPath)) {
-        const cliPackageRoot = pathModule.resolve(__dirname, "../..");
+        // This module is bundled as ESM ("type":"module"), where the CommonJS
+        // module-directory global is undefined and throws ReferenceError. Derive
+        // the directory from import.meta.url instead.
+        const moduleDir = pathModule.dirname(fileURLToPath(import.meta.url));
+        const cliPackageRoot = pathModule.resolve(moduleDir, "../..");
         const alternativePath = pathModule.resolve(cliPackageRoot, filePath);
         if (fs.existsSync(alternativePath)) {
             resolvedPath = alternativePath;
@@ -137,52 +146,71 @@ export async function findRequirementsInFile(filePath) {
     }
 }
 /**
- * Find all requirement references in the entire workspace
+ * Find all requirement references in the entire workspace.
  *
- * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ * Backed by AST parsing (the same extraction used by
+ * getReferencedRequirementIds) rather than line-oriented grep, so that:
+ *  - commented-out `requirement(...)` calls are NOT counted as live references, and
+ *  - `requirement(...)` calls wrapped across multiple lines are found, and
+ *  - every string-literal argument of a multi-arg `requirement("A", "B")` call
+ *    is captured (not just the first).
  */
 export async function findAllTestReferences(workspaceRoot) {
-    const useRg = await hasRipgrep();
-    // Pattern to match any requirement() call
-    const pattern = `requirement\\s*\\(\\s*['"\`][^'"\`]+`;
-    try {
-        let output;
-        if (useRg) {
-            // Using execFile with array args to avoid shell injection
-            const { stdout } = await execFileAsync("rg", [
-                "-n",
-                "--column",
-                pattern,
-                "--type",
-                "ts",
-                "--type",
-                "js",
-                "--type",
-                "tsx",
-                "--type",
-                "jsx",
-                workspaceRoot,
-            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // ripgrep returns non-zero on no matches
-            output = stdout;
-        }
-        else {
-            const { stdout } = await execFileAsync("grep", [
-                "-rn",
-                "--include=*.ts",
-                "--include=*.tsx",
-                "--include=*.js",
-                "--include=*.jsx",
-                "-E",
-                pattern,
-                workspaceRoot,
-            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // grep returns non-zero on no matches
-            output = stdout;
+    const { glob } = await import("glob");
+    const { parse } = await import("@babel/parser");
+    const traverse = await import("@babel/traverse");
+    const t = await import("@babel/types");
+    const fs = await import("node:fs");
+    // Find all test files using glob (same pattern as getReferencedRequirementIds)
+    const testFiles = await glob("**/*.{test,spec}.{js,jsx,ts,tsx}", {
+        cwd: workspaceRoot,
+        absolute: true,
+        ignore: ["**/node_modules/**", "**/dist/**", "**/build/**"],
+    });
+    const results = [];
+    for (const file of testFiles) {
+        try {
+            const code = fs.readFileSync(file, "utf-8");
+            const codeLines = code.split("\n");
+            const ast = parse(code, {
+                sourceType: "module",
+                plugins: ["typescript", "jsx"],
+                errorRecovery: true,
+            });
+            // Handle both ES module and CommonJS exports for traverse
+            // biome-ignore lint/suspicious/noExplicitAny: see earlier comment on babel/traverse CJS/ESM interop
+            let traverseFunc = traverse;
+            if (typeof traverseFunc !== "function") {
+                traverseFunc = traverseFunc.default;
+            }
+            if (typeof traverseFunc !== "function") {
+                traverseFunc = traverseFunc.default;
+            }
+            traverseFunc(ast, {
+                // biome-ignore lint/suspicious/noExplicitAny: babel-traverse visitor `path` is a deeply-generic NodePath whose precise type depends on what handler you're inside; `any` is the documented practice for plugin code.
+                CallExpression(path) {
+                    const callee = path.node.callee;
+                    if (t.isIdentifier(callee) && callee.name === "requirement") {
+                        const loc = path.node.loc;
+                        // Capture every string-literal argument (multi-requirement calls).
+                        for (const arg of path.node.arguments) {
+                            if (t.isStringLiteral(arg) && loc) {
+                                results.push({
+                                    file,
+                                    line: loc.start.line,
+                                    column: loc.start.column + 1, // 1-indexed
+                                    requirementId: arg.value,
+                                    context: (codeLines[loc.start.line - 1] || "").trim(),
+                                });
+                            }
+                        }
+                    }
+                },
+            });
         }
-        return parseGrepOutput(output, "", useRg);
-    }
-    catch {
-        return [];
+        catch { }
     }
+    return results;
 }
 /**
  * Parse grep/ripgrep output into TestReference objects

package/dist/schema/builder.d.ts

@@ -1,7 +1,7 @@
 /**
  * Build Markdown requirements files from structured data.
  */
-import type { Metadata, RequirementNode } from "./schemas.js";
+import { type Metadata, type RequirementNode } from "./schemas.js";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.

package/dist/schema/builder.js

@@ -2,6 +2,7 @@
  * Build Markdown requirements files from structured data.
  */
 import YAML from "yaml";
+import { ValidationError, } from "./schemas.js";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.
@@ -17,6 +18,16 @@ function buildFrontmatter(metadata) {
     });
     return `---\n${yamlStr.trim()}\n---`;
 }
+/**
+ * SYNC-FORMAT-3.0: content with an embedded newline cannot be represented on
+ * a single block line — the parser would reject (or misparse) the output.
+ * Fail the build instead of emitting markdown that breaks the round-trip.
+ */
+function assertSingleLineContent(node) {
+    if (node.content.includes("\n")) {
+        throw new ValidationError(`Requirement content for "${node.id}" contains an embedded newline — content must be a single line`, node.id);
+    }
+}
 /**
  * Build the children portion of a requirement block (without the root line).
  */
@@ -27,6 +38,7 @@ function buildChildrenBlock(children) {
             const position = parentPosition === "" ? `${index}` : `${parentPosition}.${index}`;
             const depth = position.split(".").length - 1;
             const indent = "  ".repeat(depth + 1); // 2 spaces per level
+            assertSingleLineContent(child);
             // Include label if present, otherwise just delimiter
             const labelPart = child.label
                 ? `${child.label.charAt(0).toUpperCase() + child.label.slice(1)} `
@@ -45,6 +57,7 @@ function buildChildrenBlock(children) {
  * Build a complete requirement section (heading + block).
  */
 function buildRequirementSection(node, title) {
+    assertSingleLineContent(node);
     const displayTitle = title || node.content;
     // Heading now just has the title, no key
     let section = `## ${displayTitle}\n\n`;

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

@@ -40,6 +40,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.