@popoverai/dotrequirements 0.11.0

package/dist/harness/finalize.js

@@ -0,0 +1,299 @@
+/**
+ * Finalize function for the test harness.
+ *
+ * Called after tests complete (e.g., in Vitest globalTeardown) to:
+ * 1. Read tracking data
+ * 2. Generate local coverage report
+ * 3. Report to Convex cloud (if configured)
+ * 4. Clean up tracking data
+ *
+ * Implements: HARNESS-FINALIZE-1, HARNESS-FINALIZE-2, HARNESS-FINALIZE-3, HARNESS-FINALIZE-4
+ */
+import { execSync } from 'child_process';
+import { findRequirementsDir, findProjectRoot, getTestRunId, cleanupTestRunId, readTrackingEntries, deleteTrackingFile, readLookupCache, readCoverageCache, updateCoverageCache, needsReporting, } from './cache.js';
+import { loadEnvFile, getProjectCredentials } from '../utils/env.js';
+import { isLocalOnlyProject } from '../utils/local-project.js';
+/**
+ * Aggregate tracking entries by requirement key
+ */
+function aggregateEntries(entries) {
+    const byKey = new Map();
+    for (const entry of entries) {
+        const existing = byKey.get(entry.requirementKey) || [];
+        existing.push(entry);
+        byKey.set(entry.requirementKey, existing);
+    }
+    return byKey;
+}
+/**
+ * Get the current git branch
+ */
+function getCurrentBranch(cwd) {
+    try {
+        const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        }).trim();
+        return branch;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Print local coverage report to console
+ *
+ * HARNESS-FINALIZE-1: Shows which requirements were tested
+ */
+function printLocalReport(testedKeys, lookup) {
+    const allKeys = lookup ? Object.keys(lookup.requirements) : [];
+    const untestedKeys = allKeys.filter(key => !testedKeys.includes(key));
+    const total = allKeys.length;
+    const tested = testedKeys.length;
+    const coverage = total > 0 ? ((tested / total) * 100).toFixed(1) : '0.0';
+    let report = '\n=== Requirements Coverage Report ===\n';
+    report += `\nTotal Requirements: ${total}\n`;
+    report += `Tested Requirements: ${tested}\n`;
+    report += `Untested Requirements: ${untestedKeys.length}\n`;
+    report += `Coverage: ${coverage}%\n`;
+    // Show tested requirements
+    if (testedKeys.length > 0) {
+        report += '\n✓ Tested Requirements:\n';
+        for (const key of testedKeys) {
+            const req = lookup?.requirements[key];
+            if (req) {
+                const label = req.label || '';
+                const content = req.content || '';
+                const preview = content.length > 60 ? content.substring(0, 60) + '...' : content;
+                const labelPart = label ? ` (${label})` : '';
+                report += `  - ${key}${labelPart}: ${preview}\n`;
+            }
+            else {
+                report += `  - ${key}\n`;
+            }
+        }
+    }
+    // Show untested requirements
+    if (untestedKeys.length > 0) {
+        report += '\n✗ Untested Requirements:\n';
+        for (const key of untestedKeys) {
+            const req = lookup?.requirements[key];
+            if (req) {
+                const label = req.label || '';
+                const content = req.content || '';
+                const preview = content.length > 60 ? content.substring(0, 60) + '...' : content;
+                const labelPart = label ? ` (${label})` : '';
+                report += `  - ${key}${labelPart}: ${preview}\n`;
+            }
+            else {
+                report += `  - ${key}\n`;
+            }
+        }
+    }
+    report += '\n====================================\n';
+    console.log(report);
+}
+/**
+ * Production Convex deployment URL
+ */
+const CONVEX_URL = 'https://data.dotrequirements.io';
+/**
+ * Report coverage to Convex cloud
+ *
+ * HARNESS-FINALIZE-2: Cloud reporting with error tolerance
+ * HARNESS-FINALIZE-3: Coverage records include requirement, file, line, branch
+ */
+async function reportToConvex(projectRoot, testRunId, aggregated) {
+    try {
+        // Load credentials
+        loadEnvFile(projectRoot);
+        const credentials = getProjectCredentials();
+        if (!credentials) {
+            console.log('\nℹ️  Skipping cloud coverage reporting (DOTREQUIREMENTS_PROJECT_ID or DOTREQUIREMENTS_PROJECT_SECRET not configured)');
+            return { sent: false, count: 0 };
+        }
+        const { projectId, projectSecret } = credentials;
+        // Skip for local-only projects
+        if (isLocalOnlyProject(projectId)) {
+            return { sent: false, count: 0 };
+        }
+        const requirementsDir = findRequirementsDir(projectRoot);
+        // Get all tracked requirement keys
+        const requirementKeys = Array.from(aggregated.keys());
+        // Use coverage cache for deduplication
+        const coverageCache = readCoverageCache(requirementsDir);
+        const keysToReport = requirementKeys.filter(key => needsReporting(key, coverageCache));
+        if (keysToReport.length === 0) {
+            console.log('\n✓ Coverage unchanged since last run (skipping cloud report)');
+            // Still update the cache
+            updateCoverageCache(requirementsDir, testRunId, requirementKeys);
+            return { sent: false, count: 0 };
+        }
+        const branch = getCurrentBranch(projectRoot);
+        // Build coverage payload
+        // HARNESS-FINALIZE-3: Include requirement path, test file, line, branch
+        const coverage = keysToReport.map(key => {
+            const entries = aggregated.get(key);
+            // Use the first access location
+            const firstEntry = entries[0];
+            const location = firstEntry.callerLocation;
+            // Parse "filename.ts:42" format
+            let testFile;
+            let testLine;
+            if (location !== 'unknown') {
+                const match = location.match(/^(.+):(\d+)$/);
+                if (match) {
+                    testFile = match[1];
+                    testLine = parseInt(match[2], 10);
+                }
+                else {
+                    testFile = location;
+                }
+            }
+            return {
+                requirementKey: key,
+                testFile,
+                testLine,
+            };
+        });
+        // Send to Convex
+        // Note: projectId from env is always a slug (e.g., "reduced-cephalopod-288"),
+        // not a Convex ID. Use projectSlug field for authentication and slug for target.
+        const response = await fetch(`${CONVEX_URL}/api/mutation`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                path: 'testCoverage/mutations:recordCoverage',
+                args: {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: {
+                        type: 'project',
+                        slug: projectId,
+                    },
+                    branch,
+                    coverage,
+                },
+                format: 'json',
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            console.warn(`\n⚠️  Failed to report coverage to cloud: ${response.status} ${error}`);
+            return { sent: false, count: 0, error: `${response.status} ${error}` };
+        }
+        // Check for Convex-level errors in the response body
+        // Convex returns 200 OK even for validation errors, with the error in the body
+        const responseText = await response.text();
+        let responseData;
+        try {
+            responseData = JSON.parse(responseText);
+        }
+        catch {
+            // Not JSON, treat as success
+        }
+        if (responseData && typeof responseData === 'object' && 'status' in responseData) {
+            const convexResponse = responseData;
+            if (convexResponse.status === 'error') {
+                const errorMsg = convexResponse.errorMessage || 'Unknown Convex error';
+                console.warn(`\n⚠️  Failed to report coverage to cloud: ${errorMsg}`);
+                return { sent: false, count: 0, error: errorMsg };
+            }
+        }
+        console.log(`\n✓ Reported ${keysToReport.length} requirement(s) to cloud (branch: ${branch})`);
+        // Update coverage cache
+        updateCoverageCache(requirementsDir, testRunId, requirementKeys);
+        return { sent: true, count: keysToReport.length };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`\n⚠️  Error reporting coverage to cloud: ${errorMessage}`);
+        return { sent: false, count: 0, error: errorMessage };
+    }
+}
+/**
+ * Finalize the test run after all tests complete.
+ *
+ * This function should be called once after tests complete (e.g., in globalTeardown).
+ * It reads tracking data, generates reports, and cleans up.
+ *
+ * HARNESS-FINALIZE-1: After finalize() runs, developers see which requirements were tested
+ * HARNESS-FINALIZE-2: After finalize() runs, coverage data is available in the cloud
+ * HARNESS-FINALIZE-3: Cloud coverage records identify which requirement was tested and where
+ * HARNESS-FINALIZE-4: Finalize cleans up after itself
+ */
+export async function finalize(options = {}) {
+    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, printLocalReport: shouldPrintLocal = true, cleanup: shouldCleanup = true, } = options;
+    // Priority 1: Use environment variable (cross-process persistence from globalSetup)
+    let projectRoot = process.env.DOTREQUIREMENTS_PROJECT_ROOT || null;
+    // Priority 2: Find from cwd
+    if (!projectRoot) {
+        projectRoot = findProjectRoot(cwd);
+    }
+    if (!projectRoot) {
+        console.log('Could not find .requirements directory');
+        return {
+            requirementsTested: 0,
+            totalRequirements: 0,
+            coveragePercent: 0,
+            cloudReportSent: false,
+            requirementsReportedToCloud: 0,
+        };
+    }
+    const requirementsDir = findRequirementsDir(projectRoot);
+    // Get test run ID
+    const testRunId = getTestRunId(requirementsDir);
+    if (!testRunId) {
+        console.log('No test run ID found - was prepare() called?');
+        return {
+            requirementsTested: 0,
+            totalRequirements: 0,
+            coveragePercent: 0,
+            cloudReportSent: false,
+            requirementsReportedToCloud: 0,
+        };
+    }
+    // Read tracking entries
+    const entries = readTrackingEntries(requirementsDir);
+    // Aggregate by requirement key
+    const aggregated = aggregateEntries(entries);
+    const testedKeys = Array.from(aggregated.keys());
+    // Read lookup cache for report
+    const lookup = readLookupCache(requirementsDir);
+    const totalRequirements = lookup ? Object.keys(lookup.requirements).length : 0;
+    const coveragePercent = totalRequirements > 0
+        ? (testedKeys.length / totalRequirements) * 100
+        : 0;
+    // HARNESS-FINALIZE-1: Print local report
+    if (shouldPrintLocal) {
+        printLocalReport(testedKeys, lookup);
+    }
+    // HARNESS-FINALIZE-2, HARNESS-FINALIZE-3: Report to cloud
+    let cloudResult = { sent: false, count: 0 };
+    if (shouldReportToCloud) {
+        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated);
+    }
+    // HARNESS-FINALIZE-4: Clean up tracking data
+    if (shouldCleanup && !cloudResult.error) {
+        // HARNESS-FINALIZE-4.0: Remove tracking data from this test run
+        deleteTrackingFile(requirementsDir);
+        // Clean up test run ID file
+        cleanupTestRunId(requirementsDir);
+        // HARNESS-FINALIZE-4.1: Lookup cache is preserved (no deletion)
+    }
+    // HARNESS-FINALIZE-4.2: On error, tracking data is preserved for debugging
+    return {
+        requirementsTested: testedKeys.length,
+        totalRequirements,
+        coveragePercent,
+        cloudReportSent: cloudResult.sent,
+        requirementsReportedToCloud: cloudResult.count,
+        cloudError: cloudResult.error,
+    };
+}
+//# sourceMappingURL=finalize.js.map

package/dist/harness/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Test Harness for dot•requirements.
+ *
+ * This module provides the test harness for tracking requirement coverage.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * // In globalSetup (e.g., vitest.setup.ts)
+ * import { prepare } from '@popoverai/dotrequirements/test';
+ * export default function() {
+ *   prepare();
+ * }
+ *
+ * // In tests
+ * import { requirement } from '@popoverai/dotrequirements/test';
+ * describe(requirement('REQ-123'), () => {
+ *   it(requirement('REQ-123.0'), () => {
+ *     // test implementation
+ *   });
+ * });
+ *
+ * // In globalTeardown
+ * import { finalize } from '@popoverai/dotrequirements/test';
+ * export default async function() {
+ *   await finalize();
+ * }
+ * ```
+ */
+/**
+ * Options for the requirement() function.
+ */
+export interface RequirementOptions {
+    /** Explicit project root path for loading requirements (useful when cwd is changed) */
+    projectRoot?: string;
+}
+/**
+ * Main requirements function for test harness.
+ *
+ * HARNESS-REQUIREMENT-1: Test frameworks can use requirement() as test descriptions
+ * HARNESS-REQUIREMENT-2: Invalid requirement paths fail the individual test
+ * HARNESS-REQUIREMENT-3: Each requirement() call is recorded for coverage reporting
+ * HARNESS-REQUIREMENT-4: Developers can run tests without calling prepare() first
+ * HARNESS-REQUIREMENT-5: A single test can exercise multiple requirements
+ *
+ * Supports both numeric and label-based paths.
+ * Accepts multiple requirement refs to track coverage for multiple requirements in one test.
+ *
+ * Examples:
+ * - requirement('REQ-123') - Returns root requirement content
+ * - requirement('REQ-123.0') - Returns first child (numeric path)
+ * - requirement('REQ-123.given') - Returns first "given" child (label path)
+ * - requirement('REQ-123.given#1') - Returns second "given" child
+ * - requirement('REQ-123.0.1') - Returns nested child
+ * - requirement('REQ-123.then.and') - Returns first "and" under first "then"
+ * - requirement('REQ-AUTH', 'REQ-SECURITY') - Tracks both, returns first
+ * - requirement('REQ-123', { projectRoot: '/path/to/project' }) - Explicit project root
+ *
+ * @param args - One or more requirement reference paths, optionally followed by options
+ * @returns A formatted string with the first requirement's label and content
+ */
+export declare function requirement(...args: (string | RequirementOptions)[]): string;
+export { prepare } from './prepare.js';
+export type { PrepareOptions, PrepareResult } from './prepare.js';
+export { finalize } from './finalize.js';
+export type { FinalizeOptions, FinalizeResult } from './finalize.js';
+export { clearTracking } from './tracking.js';
+export { initTestRun, finalizeTestRun, } from './tracking.js';
+export type { Requirement } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/harness/index.js

@@ -0,0 +1,103 @@
+/**
+ * Test Harness for dot•requirements.
+ *
+ * This module provides the test harness for tracking requirement coverage.
+ *
+ * Usage:
+ *
+ * ```typescript
+ * // In globalSetup (e.g., vitest.setup.ts)
+ * import { prepare } from '@popoverai/dotrequirements/test';
+ * export default function() {
+ *   prepare();
+ * }
+ *
+ * // In tests
+ * import { requirement } from '@popoverai/dotrequirements/test';
+ * describe(requirement('REQ-123'), () => {
+ *   it(requirement('REQ-123.0'), () => {
+ *     // test implementation
+ *   });
+ * });
+ *
+ * // In globalTeardown
+ * import { finalize } from '@popoverai/dotrequirements/test';
+ * export default async function() {
+ *   await finalize();
+ * }
+ * ```
+ */
+import { getRequirement, loadRequirements } from './requirementsLoader.js';
+import { ensureTestRun, trackRequirement, saveTrackingData } from './tracking.js';
+/**
+ * Main requirements function for test harness.
+ *
+ * HARNESS-REQUIREMENT-1: Test frameworks can use requirement() as test descriptions
+ * HARNESS-REQUIREMENT-2: Invalid requirement paths fail the individual test
+ * HARNESS-REQUIREMENT-3: Each requirement() call is recorded for coverage reporting
+ * HARNESS-REQUIREMENT-4: Developers can run tests without calling prepare() first
+ * HARNESS-REQUIREMENT-5: A single test can exercise multiple requirements
+ *
+ * Supports both numeric and label-based paths.
+ * Accepts multiple requirement refs to track coverage for multiple requirements in one test.
+ *
+ * Examples:
+ * - requirement('REQ-123') - Returns root requirement content
+ * - requirement('REQ-123.0') - Returns first child (numeric path)
+ * - requirement('REQ-123.given') - Returns first "given" child (label path)
+ * - requirement('REQ-123.given#1') - Returns second "given" child
+ * - requirement('REQ-123.0.1') - Returns nested child
+ * - requirement('REQ-123.then.and') - Returns first "and" under first "then"
+ * - requirement('REQ-AUTH', 'REQ-SECURITY') - Tracks both, returns first
+ * - requirement('REQ-123', { projectRoot: '/path/to/project' }) - Explicit project root
+ *
+ * @param args - One or more requirement reference paths, optionally followed by options
+ * @returns A formatted string with the first requirement's label and content
+ */
+export function requirement(...args) {
+    if (args.length === 0) {
+        throw new Error('requirement() requires at least one argument');
+    }
+    // Check if last argument is options object
+    const lastArg = args[args.length - 1];
+    const hasOptions = typeof lastArg === 'object' && lastArg !== null;
+    const options = hasOptions ? lastArg : {};
+    const requirementRefs = (hasOptions ? args.slice(0, -1) : args);
+    if (requirementRefs.length === 0) {
+        throw new Error('requirement() requires at least one requirement reference');
+    }
+    // If projectRoot provided, reload requirements from that path
+    if (options.projectRoot) {
+        loadRequirements({ projectRoot: options.projectRoot });
+    }
+    // Ensure test run is initialized
+    ensureTestRun();
+    // Track all requirements for coverage at the full path level
+    // e.g., 'REQ-123.given' is tracked as 'REQ-123.given', not just 'REQ-123'
+    for (const ref of requirementRefs) {
+        trackRequirement(ref);
+    }
+    // Save after tracking all requirements (no-op in new JSONL approach)
+    saveTrackingData();
+    // HARNESS-REQUIREMENT-2: Invalid requirement paths fail the individual test
+    const firstRef = requirementRefs[0];
+    const req = getRequirement(firstRef);
+    if (!req) {
+        throw new Error(`Requirement ${firstRef} not found`);
+    }
+    // HARNESS-REQUIREMENT-1: Format output as human-readable string
+    // Root requirements use 'requirementHeader' label which should not be shown in output
+    if (!req.label || req.label === 'requirementHeader') {
+        return req.content;
+    }
+    const label = req.label.charAt(0).toUpperCase() + req.label.slice(1);
+    return `${label}: ${req.content}`;
+}
+// Export new lifecycle functions
+export { prepare } from './prepare.js';
+export { finalize } from './finalize.js';
+// Export tracking utilities
+export { clearTracking } from './tracking.js';
+// Deprecated exports - use prepare() and finalize() instead
+export { initTestRun, finalizeTestRun, } from './tracking.js';
+//# sourceMappingURL=index.js.map

package/dist/harness/localReporting.d.ts

@@ -0,0 +1,6 @@
+import { TrackedRequirement } from "./tracking.js";
+/**
+ * Generate a simple console report showing which requirements were tested
+ */
+export declare function reportLocalCoverage(trackedReqs?: Map<string, TrackedRequirement>): void;
+//# sourceMappingURL=localReporting.d.ts.map

package/dist/harness/localReporting.js

@@ -0,0 +1,49 @@
+import { getAllRequirements } from "./requirementsLoader.js";
+/**
+ * Generate a simple console report showing which requirements were tested
+ */
+export function reportLocalCoverage(trackedReqs) {
+    const allRequirements = getAllRequirements();
+    // If no tracked requirements provided, return empty report
+    if (!trackedReqs) {
+        trackedReqs = new Map();
+    }
+    const allRequirementKeys = Array.from(allRequirements.keys());
+    const testedKeys = Array.from(trackedReqs.keys());
+    const untestedKeys = allRequirementKeys.filter((key) => !trackedReqs.has(key));
+    const coverage = allRequirementKeys.length > 0
+        ? ((testedKeys.length / allRequirementKeys.length) * 100).toFixed(1)
+        : "0.0";
+    let report = "\n=== Requirements Coverage Report ===\n";
+    report += `\nTotal Requirements: ${allRequirementKeys.length}\n`;
+    report += `Tested Requirements: ${testedKeys.length}\n`;
+    report += `Untested Requirements: ${untestedKeys.length}\n`;
+    report += `Coverage: ${coverage}%\n`;
+    // Show tested requirements
+    if (testedKeys.length > 0) {
+        report += "\n✓ Tested Requirements:\n";
+        testedKeys.forEach((key) => {
+            const req = allRequirements.get(key);
+            const label = req?.label || "";
+            const content = req?.content || "";
+            const preview = content.length > 60 ? content.substring(0, 60) + "..." : content;
+            const labelPart = label ? ` (${label})` : "";
+            report += `  - ${key}${labelPart}: ${preview}\n`;
+        });
+    }
+    // Show untested requirements
+    if (untestedKeys.length > 0) {
+        report += "\n✗ Untested Requirements:\n";
+        untestedKeys.forEach((key) => {
+            const req = allRequirements.get(key);
+            const label = req?.label || "";
+            const content = req?.content || "";
+            const preview = content.length > 60 ? content.substring(0, 60) + "..." : content;
+            const labelPart = label ? ` (${label})` : "";
+            report += `  - ${key}${labelPart}: ${preview}\n`;
+        });
+    }
+    report += "\n====================================\n";
+    console.log(report);
+}
+//# sourceMappingURL=localReporting.js.map

package/dist/harness/prepare.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Prepare function for the test harness.
+ *
+ * Called before tests run (e.g., in Vitest globalSetup) to:
+ * 1. Parse all .requirements.md files
+ * 2. Build lookup cache for fast path resolution
+ * 3. Initialize tracking for the test run
+ *
+ * Implements: HARNESS-PREPARE-1, HARNESS-PREPARE-2, HARNESS-PREPARE-3
+ */
+export interface PrepareOptions {
+    /** Working directory to start search from (defaults to cwd) */
+    cwd?: string;
+    /** Whether to log warnings (defaults to true) */
+    logWarnings?: boolean;
+}
+export interface PrepareResult {
+    /** Number of requirements files processed */
+    filesProcessed: number;
+    /** Number of requirements loaded into cache */
+    requirementsLoaded: number;
+    /** Files that had parse errors */
+    parseErrors: Array<{
+        file: string;
+        error: string;
+    }>;
+    /** The test run ID for this run */
+    testRunId: string;
+}
+/**
+ * Prepare the test harness for a test run.
+ *
+ * This function should be called once before tests run (e.g., in globalSetup).
+ * It parses all requirements files and builds a lookup cache for fast resolution.
+ *
+ * HARNESS-PREPARE-1: After prepare() runs, requirement paths resolve quickly
+ * HARNESS-PREPARE-2: When prepare() encounters invalid requirements, it warns but continues
+ * HARNESS-PREPARE-3: prepare() initializes the cache directory for tracking
+ */
+export declare function prepare(options?: PrepareOptions): PrepareResult;
+//# sourceMappingURL=prepare.d.ts.map

package/dist/harness/prepare.js

@@ -0,0 +1,83 @@
+/**
+ * Prepare function for the test harness.
+ *
+ * Called before tests run (e.g., in Vitest globalSetup) to:
+ * 1. Parse all .requirements.md files
+ * 2. Build lookup cache for fast path resolution
+ * 3. Initialize tracking for the test run
+ *
+ * Implements: HARNESS-PREPARE-1, HARNESS-PREPARE-2, HARNESS-PREPARE-3
+ */
+import { findProjectRootWithCredentials, findRequirementsDir, findRequirementsFiles, writeLookupCache, initTestRunId, clearTrackingFile, writeProjectRoot, } from './cache.js';
+import { parseRequirementsFromFile, } from '../schema/index.js';
+/**
+ * Prepare the test harness for a test run.
+ *
+ * This function should be called once before tests run (e.g., in globalSetup).
+ * It parses all requirements files and builds a lookup cache for fast resolution.
+ *
+ * HARNESS-PREPARE-1: After prepare() runs, requirement paths resolve quickly
+ * HARNESS-PREPARE-2: When prepare() encounters invalid requirements, it warns but continues
+ * HARNESS-PREPARE-3: prepare() initializes the cache directory for tracking
+ */
+export function prepare(options = {}) {
+    const { cwd = process.cwd(), logWarnings = true } = options;
+    // Find the project root - prefer root with credentials (.env.local) for monorepo support
+    let projectRoot;
+    try {
+        projectRoot = findProjectRootWithCredentials(cwd);
+    }
+    catch {
+        throw new Error('Could not find .requirements directory or .env.local with credentials. ' +
+            'Please create a .requirements directory in your project root.');
+    }
+    // Set environment variable for cross-process persistence (globalSetup → test workers)
+    process.env.DOTREQUIREMENTS_PROJECT_ROOT = projectRoot;
+    const requirementsDir = findRequirementsDir(projectRoot);
+    // Find all requirements files
+    const files = findRequirementsFiles(projectRoot);
+    // Parse all files, collecting requirements and errors
+    const allRequirements = [];
+    const parseErrors = [];
+    for (const file of files) {
+        try {
+            const { requirements } = parseRequirementsFromFile(file);
+            allRequirements.push(...requirements);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            parseErrors.push({ file, error: errorMessage });
+            // HARNESS-PREPARE-2.0: Log warning with file path and error details
+            if (logWarnings) {
+                console.warn(`⚠️  Warning: Failed to parse ${file}: ${errorMessage}`);
+            }
+        }
+    }
+    // HARNESS-PREPARE-1: Write lookup cache for fast resolution
+    writeLookupCache(requirementsDir, allRequirements);
+    // Write project root to cache (for cross-process persistence in test workers)
+    writeProjectRoot(requirementsDir, projectRoot);
+    // HARNESS-PREPARE-3.0: Initialize cache directory (done by writeLookupCache)
+    // HARNESS-PREPARE-3.1: Clear any previous tracking data
+    clearTrackingFile(requirementsDir);
+    // Initialize test run ID
+    const testRunId = initTestRunId(requirementsDir);
+    // Count total requirements (including children)
+    let requirementsLoaded = 0;
+    function countRequirements(node) {
+        requirementsLoaded++;
+        for (const child of node.children) {
+            countRequirements(child);
+        }
+    }
+    for (const req of allRequirements) {
+        countRequirements(req);
+    }
+    return {
+        filesProcessed: files.length,
+        requirementsLoaded,
+        parseErrors,
+        testRunId,
+    };
+}
+//# sourceMappingURL=prepare.js.map