@popoverai/dotrequirements 0.11.0

package/dist/harness/requirementsLoader.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Requirements loader for test harness.
+ * Loads requirements from .requirements/ directories using shared schema parsing.
+ *
+ * Project root discovery (in priority order):
+ * 1. Explicit projectRoot option passed to loadRequirements()
+ * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable
+ * 3. Cached project root file (.requirements/.cache/project-root) written by prepare()
+ */
+import { type RequirementNode } from '../schema/index.js';
+import { Requirement } from './types.js';
+export declare const loadedRequirements: Map<string, RequirementNode>;
+export interface LoadOptions {
+    /** Explicit project root path. Takes precedence over env var and cached file. */
+    projectRoot?: string;
+}
+/**
+ * Load all requirements from .requirements/ directories.
+ *
+ * Tries lookup cache first (fast path after prepare() was called).
+ * Falls back to parsing .requirements.md files on-demand.
+ *
+ * @param options.projectRoot - Explicit project root path (optional)
+ */
+export declare function loadRequirements(options?: LoadOptions): void;
+/**
+ * Get a requirement by ID (supports both numeric and label-based paths).
+ *
+ * Examples:
+ * - getRequirement('REQ-123') - Root requirement
+ * - getRequirement('REQ-123.0') - First child (numeric)
+ * - getRequirement('REQ-123.given') - First "given" child (label)
+ * - getRequirement('REQ-123.given#1') - Second "given" child (disambiguated)
+ * - getRequirement('REQ-123.0.1') - Nested child
+ */
+export declare function getRequirement(reqId: string): Requirement | undefined;
+/**
+ * Get all loaded requirements (flat map)
+ */
+export declare function getAllRequirements(): Map<string, Requirement>;
+/**
+ * Get all root requirement trees
+ */
+export declare function getAllRequirementTrees(): Map<string, Requirement>;
+//# sourceMappingURL=requirementsLoader.d.ts.map

package/dist/harness/requirementsLoader.js

@@ -0,0 +1,201 @@
+/**
+ * Requirements loader for test harness.
+ * Loads requirements from .requirements/ directories using shared schema parsing.
+ *
+ * Project root discovery (in priority order):
+ * 1. Explicit projectRoot option passed to loadRequirements()
+ * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable
+ * 3. Cached project root file (.requirements/.cache/project-root) written by prepare()
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { globSync } from 'glob';
+import { parseRequirementsFromFile, resolveRequirementPath, } from '../schema/index.js';
+import { findCachedProjectRoot, readLookupCache, } from './cache.js';
+// Cache: Maps full requirement IDs (e.g., "REQ-123.0.1") to RequirementNode
+export const loadedRequirements = new Map();
+// Cache: Maps root requirement IDs (e.g., "REQ-123") to their tree
+const requirementTrees = new Map();
+// Flag to track if we've warned about fallback parsing
+let warnedAboutFallback = false;
+/**
+ * Find the project root using the priority order:
+ * 1. Explicit projectRoot option
+ * 2. DOTREQUIREMENTS_PROJECT_ROOT env var
+ * 3. Cached project root file
+ */
+function findProjectRoot(options = {}) {
+    // Priority 1: Explicit option
+    if (options.projectRoot) {
+        return options.projectRoot;
+    }
+    // Priority 2: Environment variable
+    if (process.env.DOTREQUIREMENTS_PROJECT_ROOT) {
+        return process.env.DOTREQUIREMENTS_PROJECT_ROOT;
+    }
+    // Priority 3: Cached file (written by prepare())
+    return findCachedProjectRoot(process.cwd());
+}
+/**
+ * Find all *.requirements.md files under project root synchronously.
+ */
+function findRequirementsFilesSync(projectRoot) {
+    const pattern = '**/*.requirements.md';
+    const matches = globSync(pattern, {
+        cwd: projectRoot,
+        ignore: [
+            '**/node_modules/**',
+            '**/dist/**',
+            '**/.git/**',
+            '**/build/**',
+            '**/example/**',
+            '**/examples/**',
+            '**/__tests__/**',
+            '**/fixtures/**',
+            '**/.fixtures/**',
+        ],
+        dot: true, // Include dotfiles/dotdirs like .requirements/
+    });
+    return matches.map(m => path.join(projectRoot, m));
+}
+/**
+ * Try to load requirements from lookup cache (fast path).
+ * Returns true if cache was loaded, false if not available.
+ */
+function tryLoadFromCache(projectRoot) {
+    const requirementsDir = path.join(projectRoot, '.requirements');
+    if (!fs.existsSync(requirementsDir)) {
+        return false;
+    }
+    const cache = readLookupCache(requirementsDir);
+    if (!cache) {
+        return false;
+    }
+    // Load all requirements from cache into the flat map
+    for (const [id, req] of Object.entries(cache.requirements)) {
+        // Create a minimal RequirementNode structure
+        const node = {
+            id: req.id,
+            label: req.label,
+            content: req.content,
+            children: [], // Children are loaded separately by ID
+        };
+        loadedRequirements.set(id, node);
+        // If this is a root node (no dot in ID), add to trees cache
+        if (!id.includes('.')) {
+            requirementTrees.set(id, node);
+        }
+    }
+    return true;
+}
+/**
+ * Recursively flatten a requirement tree into the cache.
+ * Adds both the root and all children with their full IDs.
+ */
+function flattenRequirementTree(node) {
+    // Add this node to the flat cache
+    loadedRequirements.set(node.id, node);
+    // If this is a root node (no dot in ID), also add to trees cache
+    if (!node.id.includes('.')) {
+        requirementTrees.set(node.id, node);
+    }
+    // Recursively add children
+    for (const child of node.children) {
+        flattenRequirementTree(child);
+    }
+}
+/**
+ * Load all requirements from .requirements/ directories.
+ *
+ * Tries lookup cache first (fast path after prepare() was called).
+ * Falls back to parsing .requirements.md files on-demand.
+ *
+ * @param options.projectRoot - Explicit project root path (optional)
+ */
+export function loadRequirements(options = {}) {
+    // Clear existing cache when loading
+    loadedRequirements.clear();
+    requirementTrees.clear();
+    // Find project root
+    const projectRoot = findProjectRoot(options);
+    if (!projectRoot) {
+        throw new Error('Could not find project root. ' +
+            'Set DOTREQUIREMENTS_PROJECT_ROOT environment variable or run prepare() in globalSetup.');
+    }
+    // Try cache first (fast path)
+    if (tryLoadFromCache(projectRoot)) {
+        return;
+    }
+    // Fallback: Parse .requirements.md files on-demand
+    if (!warnedAboutFallback && !options.projectRoot) {
+        console.warn('⚠️  Performance warning: prepare() was not called. ' +
+            'Parsing requirements on-demand. Run prepare() in globalSetup for faster tests.');
+        warnedAboutFallback = true;
+    }
+    // Find all .requirements.md files under the project root
+    const requirementsFiles = findRequirementsFilesSync(projectRoot);
+    // Parse and flatten each file
+    for (const file of requirementsFiles) {
+        try {
+            const { requirements } = parseRequirementsFromFile(file);
+            // Flatten each requirement tree into the cache
+            for (const req of requirements) {
+                flattenRequirementTree(req);
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            console.error(`Error loading ${file}:`, errorMessage);
+        }
+    }
+}
+/**
+ * Get a requirement by ID (supports both numeric and label-based paths).
+ *
+ * Examples:
+ * - getRequirement('REQ-123') - Root requirement
+ * - getRequirement('REQ-123.0') - First child (numeric)
+ * - getRequirement('REQ-123.given') - First "given" child (label)
+ * - getRequirement('REQ-123.given#1') - Second "given" child (disambiguated)
+ * - getRequirement('REQ-123.0.1') - Nested child
+ */
+export function getRequirement(reqId) {
+    if (loadedRequirements.size === 0) {
+        loadRequirements();
+    }
+    // First try direct lookup (for numeric paths like "REQ-123.0.1")
+    const direct = loadedRequirements.get(reqId);
+    if (direct) {
+        return direct;
+    }
+    // If not found, try resolving label-based paths
+    // resolveRequirementPath expects an array of root requirements and the full path
+    const allTrees = Array.from(requirementTrees.values());
+    try {
+        const resolved = resolveRequirementPath(allTrees, reqId);
+        return resolved ?? undefined;
+    }
+    catch {
+        // Path resolution failed
+        return undefined;
+    }
+}
+/**
+ * Get all loaded requirements (flat map)
+ */
+export function getAllRequirements() {
+    if (loadedRequirements.size === 0) {
+        loadRequirements();
+    }
+    return loadedRequirements;
+}
+/**
+ * Get all root requirement trees
+ */
+export function getAllRequirementTrees() {
+    if (requirementTrees.size === 0) {
+        loadRequirements();
+    }
+    return requirementTrees;
+}
+//# sourceMappingURL=requirementsLoader.js.map

package/dist/harness/tracking.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tracking for the test harness.
+ *
+ * Tracks requirement() calls during test execution.
+ * Uses JSONL format for cross-process safety (parallel test workers).
+ *
+ * HARNESS-REQUIREMENT-3: Each requirement() call is recorded for coverage reporting
+ */
+export interface TrackedRequirement {
+    id: string;
+    fieldsAccessed: string[];
+    accessedAt: string[];
+}
+export declare function ensureTestRun(): string;
+export declare function getCallerLocation(): string;
+/**
+ * Track a requirement access.
+ *
+ * HARNESS-REQUIREMENT-3.0: After a test calls requirement(path), finalize() can report
+ * HARNESS-REQUIREMENT-3.1: Coverage record includes which file and line called requirement()
+ * HARNESS-REQUIREMENT-3.2: Works correctly when tests run in parallel processes
+ *
+ * @param reqId - Full requirement path (e.g., 'REQ-123.given' or 'REQ-123.0.1')
+ */
+export declare function trackRequirement(reqId: string): void;
+/**
+ * Save current tracking data.
+ *
+ * In the new JSONL-based approach, this is a no-op since tracking is
+ * written immediately via appendTrackingEntry. Kept for backward compatibility.
+ */
+export declare function saveTrackingData(): void;
+export declare function getTrackedRequirements(): Map<string, TrackedRequirement>;
+export declare function clearTracking(): void;
+/**
+ * Initialize a test run (called by globalSetup).
+ *
+ * @deprecated Use prepare() from './prepare.js' instead.
+ * This function is kept for backward compatibility.
+ */
+export declare function initTestRun(): void;
+/**
+ * Finalize test run and generate report (called by globalTeardown).
+ *
+ * @deprecated Use finalize() from './finalize.js' instead.
+ * This function is kept for backward compatibility.
+ */
+export declare function finalizeTestRun(): void;
+//# sourceMappingURL=tracking.d.ts.map

package/dist/harness/tracking.js

@@ -0,0 +1,179 @@
+/**
+ * Tracking for the test harness.
+ *
+ * Tracks requirement() calls during test execution.
+ * Uses JSONL format for cross-process safety (parallel test workers).
+ *
+ * HARNESS-REQUIREMENT-3: Each requirement() call is recorded for coverage reporting
+ */
+import * as path from 'path';
+import { findRequirementsDir, findProjectRoot, getTestRunId, appendTrackingEntry, getCacheDir, initTestRunId, clearTrackingFile, } from './cache.js';
+const trackedRequirements = new Map();
+// Test run tracking
+let testRunId = null;
+let requirementsDirCached = null;
+// Initialize test run
+export function ensureTestRun() {
+    if (!testRunId) {
+        // Priority 1: Use environment variable (cross-process persistence from globalSetup)
+        if (process.env.DOTREQUIREMENTS_PROJECT_ROOT) {
+            requirementsDirCached = path.join(process.env.DOTREQUIREMENTS_PROJECT_ROOT, '.requirements');
+        }
+        // Priority 2: Find from caller directory
+        if (!requirementsDirCached) {
+            const callerDir = getCallerDirectory();
+            requirementsDirCached = findRequirementsDir(callerDir || process.cwd());
+            // If not found from caller directory, try from cwd explicitly
+            if (!requirementsDirCached && callerDir) {
+                requirementsDirCached = findRequirementsDir(process.cwd());
+            }
+        }
+        if (!requirementsDirCached) {
+            throw new Error('Could not find .requirements directory. Please create one in your project root.');
+        }
+        // Try to read from shared test run ID file (set by prepare())
+        const existingRunId = getTestRunId(requirementsDirCached);
+        if (existingRunId) {
+            testRunId = existingRunId;
+        }
+        else {
+            // Fallback for standalone usage without prepare()
+            testRunId = `${Date.now()}-${process.pid}`;
+        }
+        // Ensure cache directory exists
+        getCacheDir(requirementsDirCached, true);
+    }
+    return testRunId;
+}
+// Get caller location for tracking
+export function getCallerLocation() {
+    const error = new Error();
+    const stack = error.stack?.split('\n') || [];
+    // Find the first stack frame that's not in our library files
+    for (let i = 2; i < stack.length; i++) {
+        const frame = stack[i];
+        if (!frame.includes('/harness/index.ts') &&
+            !frame.includes('/harness/index.js') &&
+            !frame.includes('/harness/tracking.ts') &&
+            !frame.includes('/harness/tracking.js')) {
+            // Extract filename and line number
+            const regex1 = /\((.+):(\d+):(\d+)\)/;
+            const regex2 = /at (.+):(\d+):(\d+)/;
+            const match = regex1.exec(frame) || regex2.exec(frame);
+            if (match) {
+                const filePath = match[1];
+                const lineNumber = match[2];
+                return `${path.basename(filePath)}:${lineNumber}`;
+            }
+        }
+    }
+    return 'unknown';
+}
+// Get caller's directory (full path) for finding .requirements
+function getCallerDirectory() {
+    const error = new Error();
+    const stack = error.stack?.split('\n') || [];
+    // Find the first stack frame that's not in our library files
+    for (let i = 2; i < stack.length; i++) {
+        const frame = stack[i];
+        if (!frame.includes('/harness/index.ts') &&
+            !frame.includes('/harness/index.js') &&
+            !frame.includes('/harness/tracking.ts') &&
+            !frame.includes('/harness/tracking.js')) {
+            // Extract filename
+            const regex1 = /\((.+):(\d+):(\d+)\)/;
+            const regex2 = /at (.+):(\d+):(\d+)/;
+            const match = regex1.exec(frame) || regex2.exec(frame);
+            if (match) {
+                const filePath = match[1];
+                return path.dirname(filePath);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Track a requirement access.
+ *
+ * HARNESS-REQUIREMENT-3.0: After a test calls requirement(path), finalize() can report
+ * HARNESS-REQUIREMENT-3.1: Coverage record includes which file and line called requirement()
+ * HARNESS-REQUIREMENT-3.2: Works correctly when tests run in parallel processes
+ *
+ * @param reqId - Full requirement path (e.g., 'REQ-123.given' or 'REQ-123.0.1')
+ */
+export function trackRequirement(reqId) {
+    const callerLocation = getCallerLocation();
+    const runId = ensureTestRun();
+    // Track in memory for backward compatibility
+    if (!trackedRequirements.has(reqId)) {
+        trackedRequirements.set(reqId, {
+            id: reqId,
+            fieldsAccessed: [], // Kept for backward compatibility
+            accessedAt: [],
+        });
+    }
+    const tracked = trackedRequirements.get(reqId);
+    tracked.accessedAt.push(callerLocation);
+    // Append to JSONL file for cross-process tracking
+    // HARNESS-REQUIREMENT-3.2: JSONL is append-only, safe for parallel workers
+    if (requirementsDirCached) {
+        const entry = {
+            requirementKey: reqId,
+            callerLocation,
+            timestamp: Date.now(),
+            testRunId: runId,
+        };
+        appendTrackingEntry(requirementsDirCached, entry);
+    }
+}
+/**
+ * Save current tracking data.
+ *
+ * In the new JSONL-based approach, this is a no-op since tracking is
+ * written immediately via appendTrackingEntry. Kept for backward compatibility.
+ */
+export function saveTrackingData() {
+    // No-op: JSONL entries are written immediately in trackRequirement()
+}
+// Get all tracked requirements (in-memory)
+export function getTrackedRequirements() {
+    return trackedRequirements;
+}
+// Clear tracking (for testing)
+export function clearTracking() {
+    trackedRequirements.clear();
+    testRunId = null;
+    requirementsDirCached = null;
+}
+/**
+ * Initialize a test run (called by globalSetup).
+ *
+ * @deprecated Use prepare() from './prepare.js' instead.
+ * This function is kept for backward compatibility.
+ */
+export function initTestRun() {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+        throw new Error('Could not find .requirements directory. Please create one in your project root.');
+    }
+    const reqDir = findRequirementsDir();
+    // Initialize test run ID
+    initTestRunId(reqDir);
+    // Clear previous tracking data
+    clearTrackingFile(reqDir);
+}
+/**
+ * Finalize test run and generate report (called by globalTeardown).
+ *
+ * @deprecated Use finalize() from './finalize.js' instead.
+ * This function is kept for backward compatibility.
+ */
+export function finalizeTestRun() {
+    // Import and call the new finalize function
+    // Using dynamic import to avoid circular dependencies
+    const { finalize } = require('./finalize.js');
+    finalize().catch((error) => {
+        console.error('Error in finalizeTestRun:', error.message);
+    });
+}
+//# sourceMappingURL=tracking.js.map

package/dist/harness/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Type definitions for test harness.
+ * Uses shared schema types for consistency with CLI and MCP.
+ */
+import type { RequirementNode } from '../schema/index.js';
+export type { RequirementNode as Requirement };
+export interface CriteriaDetail {
+    reqId: string;
+    totalCriteria: number;
+    testedCriteria: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/harness/types.js

@@ -0,0 +1,6 @@
+/**
+ * Type definitions for test harness.
+ * Uses shared schema types for consistency with CLI and MCP.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mcp/convexClient.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Load Convex configuration from .env file or environment variables
+ */
+interface ConvexConfig {
+    convexUrl: string;
+    projectId: string;
+    projectSecret: string;
+}
+export declare function loadConvexConfig(cwd?: string): ConvexConfig | null;
+/**
+ * Query Convex for requirement coverage
+ */
+export declare function getRequirementCoverage(requirementKey: string, projectId: string, projectSecret: string, convexUrl: string): Promise<{
+    requirementKey: string;
+    lastTestedAt: number | null;
+    branch: string | null;
+    testFile: string | null;
+    testLine: number | null;
+    allBranches: Array<{
+        branch: string;
+        lastTestedAt: number;
+        testFile?: string;
+        testLine?: number;
+    }>;
+}>;
+/**
+ * Query Convex for project coverage summary
+ */
+export declare function getProjectCoverage(projectId: string, projectSecret: string, convexUrl: string, options?: {
+    branch?: string;
+    sinceTimestamp?: number;
+}): Promise<{
+    tested: Array<{
+        requirementKey: string;
+        lastTestedAt: number;
+        branch: string;
+        testFile?: string;
+        testLine?: number;
+    }>;
+    untested: string[];
+}>;
+export {};
+//# sourceMappingURL=convexClient.d.ts.map

package/dist/mcp/convexClient.js

@@ -0,0 +1,101 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+/**
+ * Production Convex deployment URL
+ */
+const CONVEX_URL = 'https://data.dotrequirements.io';
+export function loadConvexConfig(cwd = process.cwd()) {
+    let projectId;
+    let projectSecret;
+    // Try to load from .env files (.env.local takes precedence over .env)
+    const envFiles = ['.env.local', '.env'];
+    for (const envFile of envFiles) {
+        const envPath = join(cwd, envFile);
+        if (existsSync(envPath)) {
+            const envContent = readFileSync(envPath, 'utf-8');
+            const lines = envContent.split('\n');
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_ID=')) {
+                    projectId = trimmed.split('=')[1].trim().replace(/['"]/g, '');
+                }
+                if (trimmed.startsWith('DOTREQUIREMENTS_PROJECT_SECRET=')) {
+                    projectSecret = trimmed.split('=')[1].trim().replace(/['"]/g, '');
+                }
+            }
+            // If we found values, stop looking (precedence: .env.local > .env)
+            if (projectId && projectSecret) {
+                break;
+            }
+        }
+    }
+    // Environment variables take precedence
+    if (process.env.DOTREQUIREMENTS_PROJECT_ID) {
+        projectId = process.env.DOTREQUIREMENTS_PROJECT_ID;
+    }
+    if (process.env.DOTREQUIREMENTS_PROJECT_SECRET) {
+        projectSecret = process.env.DOTREQUIREMENTS_PROJECT_SECRET;
+    }
+    if (!projectId || !projectSecret) {
+        return null;
+    }
+    return { convexUrl: CONVEX_URL, projectId, projectSecret };
+}
+/**
+ * Query Convex for requirement coverage
+ */
+export async function getRequirementCoverage(requirementKey, projectId, projectSecret, convexUrl) {
+    const response = await fetch(`${convexUrl}/api/query`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            path: 'testCoverage/queries:getRequirementCoverage',
+            args: {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: {
+                    type: 'project',
+                    slug: projectId,
+                },
+                requirementKey,
+            },
+            format: 'json',
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to query coverage: ${response.statusText}`);
+    }
+    return await response.json();
+}
+/**
+ * Query Convex for project coverage summary
+ */
+export async function getProjectCoverage(projectId, projectSecret, convexUrl, options) {
+    const response = await fetch(`${convexUrl}/api/query`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            path: 'testCoverage/queries:getProjectCoverage',
+            args: {
+                projectAuth: {
+                    projectSlug: projectId,
+                    projectSecret,
+                },
+                target: {
+                    type: 'project',
+                    slug: projectId,
+                },
+                branch: options?.branch,
+                sinceTimestamp: options?.sinceTimestamp,
+            },
+            format: 'json',
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to query coverage: ${response.statusText}`);
+    }
+    return await response.json();
+}
+//# sourceMappingURL=convexClient.js.map

package/dist/mcp/grep.d.ts

@@ -0,0 +1,24 @@
+import type { TestReference } from './types.js';
+/**
+ * Find all test files that reference a specific requirement ID
+ *
+ * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ */
+export declare function findTestsForRequirement(workspaceRoot: string, requirementId: string): Promise<TestReference[]>;
+/**
+ * Find all requirement references in a specific file using AST parsing
+ */
+export declare function findRequirementsInFile(filePath: string): Promise<TestReference[]>;
+/**
+ * Find all requirement references in the entire workspace
+ *
+ * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ */
+export declare function findAllTestReferences(workspaceRoot: string): Promise<TestReference[]>;
+/**
+ * Get all unique requirement IDs referenced in tests
+ * Normalizes child IDs (e.g., AUTH-VALID-LOGIN.0) to root IDs (e.g., AUTH-VALID-LOGIN)
+ * Uses AST parsing instead of grep for reliability across environments
+ */
+export declare function getReferencedRequirementIds(workspaceRoot: string): Promise<Set<string>>;
+//# sourceMappingURL=grep.d.ts.map