@popoverai/dotrequirements 0.22.0 → 0.24.0

package/dist/schema/parser.d.ts

@@ -1,7 +1,7 @@
 /**
  * Parse Markdown requirements files into typed structures.
  */
-import { RequirementNode, RequirementsFile, ParsedCriterion } from './schemas.js';
+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"
@@ -18,14 +18,14 @@ export declare function parseRequirementBlock(key: string, blockContent: string)
  * Parse a complete requirements Markdown file.
  */
 export declare function parseRequirementsFile(markdownContent: string): {
-    metadata: RequirementsFile['_meta'];
+    metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
 };
 /**
  * Parse requirements file from disk.
  */
 export declare function parseRequirementsFromFile(filePath: string): {
-    metadata: RequirementsFile['_meta'];
+    metadata: RequirementsFile["_meta"];
     requirements: RequirementNode[];
 };
 /**

package/dist/schema/parser.js

@@ -1,15 +1,10 @@
 /**
  * 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
+import * as fs from "node:fs";
+import YAML from "yaml";
+import { ValidationError, validateMetadata, } from "./schemas.js";
+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"
@@ -26,7 +21,7 @@ export function parseCriterionLine(line, delimiter = DELIMITER_PATTERN) {
     }
     return {
         position: match[1],
-        label: match[2] ? match[2].trim() : '', // Preserve original case, empty if no label
+        label: match[2] ? match[2].trim() : "", // Preserve original case, empty if no label
         content: match[3].trim(),
     };
 }
@@ -41,7 +36,7 @@ function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
     const keyMatch = trimmed.match(/^([\w-]+):\s*(.+)$/);
     if (keyMatch) {
         return {
-            label: '', // Keys use empty string for unlabeled requirements
+            label: "", // Keys use empty string for unlabeled requirements
             content: keyMatch[2].trim(),
         };
     }
@@ -51,12 +46,12 @@ function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
     if (!match) {
         // If no delimiter found, treat entire line as content with empty label
         return {
-            label: '',
+            label: "",
             content: trimmed,
         };
     }
     return {
-        label: match[1] ? match[1].trim() : '',
+        label: match[1] ? match[1].trim() : "",
         content: match[2].trim(),
     };
 }
@@ -66,20 +61,20 @@ function parseRootLine(line, delimiter = DELIMITER_PATTERN) {
  * Subsequent lines are criteria with position paths.
  */
 export function parseRequirementBlock(key, blockContent) {
-    const lines = blockContent.trim().split('\n');
+    const lines = blockContent.trim().split("\n");
     if (lines.length === 0) {
-        throw new ValidationError('Empty requirement block', key);
+        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);
+        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',
+        label: "requirementHeader",
         content: rootParsed.content,
         children: [],
     };
@@ -88,7 +83,7 @@ export function parseRequirementBlock(key, blockContent) {
     for (let i = 1; i < lines.length; i++) {
         const line = lines[i];
         // Skip empty lines and comments
-        if (!line.trim() || line.trim().startsWith('#')) {
+        if (!line.trim() || line.trim().startsWith("#")) {
             continue;
         }
         const criterion = parseCriterionLine(line);
@@ -108,8 +103,8 @@ export function parseRequirementBlock(key, blockContent) {
 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));
+        .filter((pos) => !pos.includes("."))
+        .sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
     for (const position of topLevelPositions) {
         const criterion = criteriaByPosition.get(position);
         const childNode = {
@@ -129,9 +124,9 @@ function buildTreeFromPositions(root, rootKey, criteriaByPosition) {
 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('.');
+        .filter((pos) => {
+        const parts = pos.split(".");
+        const parentParts = parentPosition.split(".");
         // Must be exactly one level deeper
         if (parts.length !== parentParts.length + 1) {
             return false;
@@ -145,8 +140,8 @@ function buildChildrenFromPositions(parent, parentPosition, rootKey, criteriaByP
         return true;
     })
         .sort((a, b) => {
-        const aLast = parseInt(a.split('.').pop());
-        const bLast = parseInt(b.split('.').pop());
+        const aLast = parseInt(a.split(".").pop(), 10);
+        const bLast = parseInt(b.split(".").pop(), 10);
         return aLast - bLast;
     });
     for (const position of childPositions) {
@@ -171,7 +166,7 @@ function extractFrontmatter(content) {
     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 ---)');
+        throw new ValidationError("Missing YAML frontmatter (should start with ---)");
     }
     const [, frontmatterYaml, body] = match;
     let frontmatter;
@@ -179,7 +174,7 @@ function extractFrontmatter(content) {
         frontmatter = YAML.parse(frontmatterYaml);
     }
     catch (error) {
-        throw new ValidationError('Failed to parse YAML frontmatter', undefined, error);
+        throw new ValidationError("Failed to parse YAML frontmatter", undefined, error);
     }
     return { frontmatter, body: body.trim() };
 }
@@ -194,8 +189,8 @@ 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) {
+    let match = blockRegex.exec(body);
+    while (match !== null) {
         const blockContent = match[1];
         // Extract key from first line of block (format: "KEY: content")
         const firstLineMatch = blockContent.match(/^([\w-]+):\s*(.+)/);
@@ -209,6 +204,7 @@ function extractRequirementBlocks(body) {
         const headingMatch = textBeforeBlock.match(/^#{2,6}\s+([^\n]+)\s*$/m);
         const title = headingMatch ? headingMatch[1].trim() : key;
         blocks.set(key, { title, blockContent: blockContent.trim() });
+        match = blockRegex.exec(body);
     }
     return blocks;
 }
@@ -223,7 +219,7 @@ export function parseRequirementsFile(markdownContent) {
     // Extract requirement blocks
     const blocks = extractRequirementBlocks(body);
     if (blocks.size === 0) {
-        throw new ValidationError('No requirement blocks found in document');
+        throw new ValidationError("No requirement blocks found in document");
     }
     // Parse each requirement block
     const requirements = [];
@@ -246,7 +242,7 @@ export function parseRequirementsFile(markdownContent) {
  */
 export function parseRequirementsFromFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
+        const content = fs.readFileSync(filePath, "utf-8");
         return parseRequirementsFile(content);
     }
     catch (error) {

package/dist/schema/resolver.d.ts

@@ -2,7 +2,7 @@
  * Resolve label-based requirement paths to numeric paths.
  * Supports: REQ123.given, REQ123.when.then, REQ123.given#1
  */
-import { RequirementNode } from './schemas.js';
+import type { RequirementNode } from "./schemas.js";
 /**
  * Parse a requirement path into segments.
  * E.g., "REQ123.given.then" → ["REQ123", "given", "then"]

package/dist/schema/resolver.js

@@ -8,7 +8,7 @@
  * E.g., "REQ123.given#1" → ["REQ123", "given#1"]
  */
 export function parseRequirementPath(path) {
-    return path.split('.');
+    return path.split(".");
 }
 /**
  * Parse a path segment that may include disambiguation.
@@ -22,7 +22,7 @@ export function parsePathSegment(segment) {
     }
     return {
         label: match[1],
-        index: match[2] ? parseInt(match[2]) : 0,
+        index: match[2] ? parseInt(match[2], 10) : 0,
     };
 }
 /**
@@ -31,7 +31,7 @@ export function parsePathSegment(segment) {
  * Examples: "Several-words" -> "several words", "AC" -> "ac"
  */
 function normalizeLabel(label) {
-    return label.replace(/-/g, ' ').toLowerCase();
+    return label.replace(/-/g, " ").toLowerCase();
 }
 /**
  * Find children matching a label.
@@ -40,7 +40,7 @@ function normalizeLabel(label) {
  */
 export function findChildrenByLabel(node, label) {
     const normalizedLabel = normalizeLabel(label);
-    return node.children.filter(child => normalizeLabel(child.label) === normalizedLabel);
+    return node.children.filter((child) => normalizeLabel(child.label) === normalizedLabel);
 }
 /**
  * Resolve a label-based path segment to a numeric index.
@@ -49,7 +49,7 @@ export function findChildrenByLabel(node, label) {
 export function resolvePathSegment(node, segment) {
     // Check if segment is numeric (direct index)
     if (/^\d+$/.test(segment)) {
-        const index = parseInt(segment);
+        const index = parseInt(segment, 10);
         if (index < node.children.length) {
             return {
                 child: node.children[index],
@@ -94,7 +94,7 @@ export function resolveRequirementPath(requirements, path) {
     }
     // First segment should be the root requirement ID
     const rootId = segments[0];
-    let currentNode = requirements.find(r => r.id === rootId);
+    let currentNode = requirements.find((r) => r.id === rootId);
     if (!currentNode) {
         return null;
     }
@@ -130,7 +130,7 @@ export function resolveToNumericPath(requirements, path) {
  *
  * Returns paths like: ["REQ123", "REQ123.given", "REQ123.when", ...]
  */
-export function getAllLabelPaths(node, prefix = '') {
+export function getAllLabelPaths(node, prefix = "") {
     const currentPath = prefix ? `${prefix}.${node.label}` : node.id;
     const paths = [currentPath];
     for (const child of node.children) {
@@ -148,7 +148,7 @@ export function checkPathAmbiguity(requirements, path) {
         return 0;
     }
     const rootId = segments[0];
-    let currentNode = requirements.find(r => r.id === rootId);
+    let currentNode = requirements.find((r) => r.id === rootId);
     if (!currentNode) {
         return 0;
     }
@@ -160,7 +160,7 @@ export function checkPathAmbiguity(requirements, path) {
         const segment = segments[i];
         // Numeric segments are never ambiguous
         if (/^\d+$/.test(segment)) {
-            const index = parseInt(segment);
+            const index = parseInt(segment, 10);
             if (index >= currentNode.children.length) {
                 return 0; // Invalid path
             }

package/dist/schema/scenario.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq acceptance-test`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+import type { RequirementNode } from "./schemas.js";
+/**
+ * One step in a scenario. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Step` type.
+ */
+export interface ScenarioStep {
+    step: "arrange" | "act" | "assert";
+    description: string;
+    url?: string;
+    key?: string;
+}
+/**
+ * One entry in the `Scenario.variables` map. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Variable` type — the `value` is what
+ * gets substituted into the scenario, and the optional `description` gives
+ * the agent extra context about what the substitution represents.
+ */
+export interface ScenarioVariable {
+    value: string;
+    description?: string;
+}
+export type ScenarioVariables = Record<string, ScenarioVariable>;
+/**
+ * A scenario passed to `runScenario`. Structurally compatible with
+ * `@popoverai/browser-automation`'s `Scenario` type.
+ */
+export interface Scenario {
+    baseUrl: string;
+    steps: ScenarioStep[];
+    variables?: ScenarioVariables;
+}
+/**
+ * One requirement contributing an assertion to a scenario. The minimum shape
+ * the builder needs so callers sourcing requirements from different backends
+ * (Markdown files via `RequirementNode`, Convex rows, etc.) can all use it.
+ */
+export interface ScenarioAssertionSource {
+    /** Full requirement key including path, e.g. "LOGIN-1" or "LOGIN-1.0.1". */
+    id: string;
+    /** Requirement text; becomes the assertion's `description`. */
+    content: string;
+}
+export interface BuildScenarioOptions {
+    /**
+     * The requirements contributing assertions, in the order they should be
+     * evaluated. Every entry with non-empty `content` becomes one `assert` step.
+     */
+    assertions: ScenarioAssertionSource[];
+    /** Target URL the scenario runs against; becomes `Scenario.baseUrl`. */
+    baseUrl: string;
+    /**
+     * Optional Stagehand variable substitutions. Used to inject secrets
+     * (test-user credentials, bypass tokens) into assertion descriptions
+     * without exposing them to the language model in plaintext.
+     */
+    variables?: Record<string, string>;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export declare function buildScenarioFromRequirements(opts: BuildScenarioOptions): Scenario;
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export declare function requirementTreeToScenario(root: RequirementNode, opts: Omit<BuildScenarioOptions, "assertions">): Scenario;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/schema/scenario.js

@@ -0,0 +1,82 @@
+/**
+ * Scenario builder — turns a requirement tree into a browser-automation Scenario.
+ *
+ * Used by both the CLI (via `dotreq acceptance-test`) and the Convex Node action
+ * (`testCoverage/browserRun:run`) so the two paths produce identical scenarios
+ * for the same input.
+ *
+ * Naive passthrough: every requirement node with non-empty content becomes
+ * exactly one assertion keyed by its numeric-path id (e.g. "LOGIN-1" for the
+ * root, "LOGIN-1.0" for the first criterion). No arrange/act steps are
+ * emitted; Stagehand's hybrid agent is expected to infer setup from the
+ * assertion list. See BROWSER-RUN-3 in
+ * .requirements/testing-tab-browser-run.requirements.md.
+ *
+ * Types here are defined locally to avoid adding `@popoverai/browser-automation`
+ * as a runtime dependency of this package. They are structurally compatible
+ * with browser-automation's exported `Scenario` / `Step` types and can be
+ * passed directly to `runScenario`.
+ */
+/**
+ * Pre-order flatten: root first, then each subtree's nodes in order.
+ * Inlined here (rather than imported from `parser.ts`) so this module stays
+ * free of Node-only dependencies and can be re-exported from the browser
+ * entry point.
+ */
+function flattenTree(node) {
+    const result = [node];
+    for (const child of node.children) {
+        result.push(...flattenTree(child));
+    }
+    return result;
+}
+/**
+ * Build a `Scenario` from a list of requirement assertion sources.
+ *
+ * Throws if the resulting scenario would have zero assertions
+ * (browser-automation rejects scenarios with no asserts).
+ */
+export function buildScenarioFromRequirements(opts) {
+    const { assertions, baseUrl, variables } = opts;
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        throw new Error("buildScenarioFromRequirements: baseUrl is required");
+    }
+    const steps = [];
+    for (const source of assertions) {
+        const description = source.content.trim();
+        if (description.length === 0)
+            continue;
+        steps.push({
+            step: "assert",
+            description,
+            key: source.id,
+        });
+    }
+    if (steps.length === 0) {
+        throw new Error("buildScenarioFromRequirements: requirement tree has no nodes with content; cannot build a scenario");
+    }
+    const scenario = { baseUrl, steps };
+    if (variables && Object.keys(variables).length > 0) {
+        // Callers pass a flat Record<string, string> for ergonomics; wrap each
+        // entry as `{ value }` so the scenario matches runScenario's expected
+        // Variables shape. Callers with richer values can set variables on the
+        // returned scenario directly before invocation.
+        scenario.variables = Object.fromEntries(Object.entries(variables).map(([key, value]) => [key, { value }]));
+    }
+    return scenario;
+}
+/**
+ * Convenience wrapper for callers that have a `RequirementNode` tree (root
+ * plus nested children). Flattens the tree to the order produced by
+ * `flattenRequirementTree` (pre-order: root first, then each subtree), then
+ * delegates to `buildScenarioFromRequirements`.
+ */
+export function requirementTreeToScenario(root, opts) {
+    const flat = flattenTree(root);
+    const assertions = flat.map((node) => ({
+        id: node.id,
+        content: node.content,
+    }));
+    return buildScenarioFromRequirements({ ...opts, assertions });
+}
+//# sourceMappingURL=scenario.js.map

package/dist/schema/schemas.d.ts

@@ -2,7 +2,7 @@
  * Zod schemas for Markdown requirements format.
  * TypeScript types are inferred from these schemas using z.infer<>.
  */
-import { z } from 'zod';
+import { z } from "zod";
 /**
  * Requirement prefix format: uppercase letters and hyphens, 1-30 chars.
  * First char must be a letter.
@@ -100,7 +100,7 @@ export declare const CONVEX_ID_PATTERN: RegExp;
  */
 export type PushValidationResult = {
     valid: true;
-    action: 'create' | 'update';
+    action: "create" | "update";
     warning?: string;
 } | {
     valid: false;
@@ -246,7 +246,7 @@ export declare const RequirementsFileSchema: z.ZodObject<{
     }>;
 }, z.ZodTypeAny, "passthrough">>;
 export type RequirementsFile = z.infer<typeof RequirementsFileSchema> & {
-    [key: string]: any;
+    [key: string]: unknown;
 };
 /**
  * Parsed criterion from Markdown (position. Label: content format)