@popoverai/dotrequirements 0.11.0

package/dist/harness/cache.js

@@ -0,0 +1,342 @@
+/**
+ * Cache management for the test harness.
+ *
+ * Manages the .requirements/.cache/ directory with:
+ * - lookup.json: Pre-resolved requirements for fast path resolution
+ * - tracking.jsonl: Append-only tracking of requirement() calls (cross-process safe)
+ * - coverage.json: Deduplication cache for cloud reporting
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { globSync } from 'glob';
+import { findUpSync } from 'find-up';
+import { brandPlain } from '../utils/brand.js';
+// Cache directory structure
+const CACHE_DIR = '.cache';
+const LOOKUP_FILE = 'lookup.json';
+const TRACKING_FILE = 'tracking.jsonl';
+const COVERAGE_FILE = 'coverage.json';
+const PROJECT_ROOT_FILE = 'project-root';
+// Test run ID file (outside cache, in .requirements/)
+const TEST_RUN_ID_FILE = '.test-run-id';
+/**
+ * Find the nearest .requirements directory by walking up from startDir
+ */
+export function findRequirementsDir(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const requirementsDir = path.join(currentDir, '.requirements');
+        if (fs.existsSync(requirementsDir) && fs.statSync(requirementsDir).isDirectory()) {
+            return requirementsDir;
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            // Reached filesystem root without finding .requirements
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * Find the project root (directory containing .requirements)
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    const requirementsDir = findRequirementsDir(startDir);
+    return requirementsDir ? path.dirname(requirementsDir) : null;
+}
+/**
+ * Get the cache directory path, creating it if necessary
+ */
+export function getCacheDir(requirementsDir, create = false) {
+    const cacheDir = path.join(requirementsDir, CACHE_DIR);
+    if (create && !fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+    }
+    return cacheDir;
+}
+/**
+ * Check if an .env.local file has dotrequirements credentials.
+ */
+function hasDotrequirementsCredentials(envPath) {
+    const envContent = fs.readFileSync(envPath, 'utf-8');
+    const hasProjectId = envContent.includes('DOTREQUIREMENTS_PROJECT_ID=');
+    const hasProjectSecret = envContent.includes('DOTREQUIREMENTS_PROJECT_SECRET=');
+    return hasProjectId && hasProjectSecret;
+}
+/**
+ * Find the dotrequirements project root by looking for .env.local with credentials.
+ * Falls back to finding .requirements directory if no credentials found.
+ */
+export function findProjectRootWithCredentials(startDir = process.cwd()) {
+    let searchDir = startDir;
+    while (true) {
+        const envPath = findUpSync('.env.local', { cwd: searchDir });
+        if (!envPath) {
+            // No .env.local found - try to find project root by .requirements directory
+            const projectRoot = findProjectRoot(startDir);
+            if (projectRoot) {
+                return projectRoot;
+            }
+            throw new Error(`Could not find ${brandPlain} project root. ` +
+                `Expected to find .env.local with credentials or a .requirements directory.`);
+        }
+        // Check if this .env.local has dotrequirements credentials
+        if (hasDotrequirementsCredentials(envPath)) {
+            return path.dirname(envPath);
+        }
+        // No credentials - continue searching from parent directory
+        const envDir = path.dirname(envPath);
+        const parentDir = path.dirname(envDir);
+        // If we've reached the root, stop
+        if (parentDir === envDir) {
+            // Try .requirements as fallback
+            const projectRoot = findProjectRoot(startDir);
+            if (projectRoot) {
+                return projectRoot;
+            }
+            throw new Error(`Could not find ${brandPlain} project root. ` +
+                `Found .env.local files but none contained credentials.`);
+        }
+        searchDir = parentDir;
+    }
+}
+/**
+ * Find all *.requirements.md files under project root
+ */
+export function findRequirementsFiles(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));
+}
+/**
+ * Write the lookup cache with all pre-parsed requirements
+ */
+export function writeLookupCache(requirementsDir, requirements) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const lookupPath = path.join(cacheDir, LOOKUP_FILE);
+    const lookup = {
+        generatedAt: new Date().toISOString(),
+        requirements: {},
+    };
+    // Recursively flatten the requirement trees
+    function flatten(node) {
+        lookup.requirements[node.id] = {
+            id: node.id,
+            label: node.label,
+            content: node.content,
+        };
+        for (const child of node.children) {
+            flatten(child);
+        }
+    }
+    for (const req of requirements) {
+        flatten(req);
+    }
+    fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
+}
+/**
+ * Read the lookup cache, returning null if not found or invalid
+ */
+export function readLookupCache(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir);
+    const lookupPath = path.join(cacheDir, LOOKUP_FILE);
+    if (!fs.existsSync(lookupPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(lookupPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Generate and store a unique test run ID
+ */
+export function initTestRunId(requirementsDir) {
+    const testRunId = `${Date.now()}-${process.pid}`;
+    const testRunIdPath = path.join(requirementsDir, TEST_RUN_ID_FILE);
+    fs.writeFileSync(testRunIdPath, testRunId);
+    return testRunId;
+}
+/**
+ * Get the current test run ID, or null if not initialized
+ */
+export function getTestRunId(requirementsDir) {
+    const testRunIdPath = path.join(requirementsDir, TEST_RUN_ID_FILE);
+    if (!fs.existsSync(testRunIdPath)) {
+        return null;
+    }
+    return fs.readFileSync(testRunIdPath, 'utf-8').trim();
+}
+/**
+ * Clean up the test run ID file
+ */
+export function cleanupTestRunId(requirementsDir) {
+    const testRunIdPath = path.join(requirementsDir, TEST_RUN_ID_FILE);
+    if (fs.existsSync(testRunIdPath)) {
+        fs.unlinkSync(testRunIdPath);
+    }
+}
+/**
+ * Write the project root to cache (for cross-process persistence).
+ * This allows test workers to find the lookup cache even after cwd changes.
+ */
+export function writeProjectRoot(requirementsDir, projectRoot) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const projectRootPath = path.join(cacheDir, PROJECT_ROOT_FILE);
+    fs.writeFileSync(projectRootPath, projectRoot);
+}
+/**
+ * Read the project root from cache, returning null if not found.
+ */
+export function readProjectRoot(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir);
+    const projectRootPath = path.join(cacheDir, PROJECT_ROOT_FILE);
+    if (!fs.existsSync(projectRootPath)) {
+        return null;
+    }
+    return fs.readFileSync(projectRootPath, 'utf-8').trim();
+}
+/**
+ * Try to find the project root from any known .requirements cache directory.
+ * Walks up from cwd looking for .requirements/.cache/project-root file.
+ */
+export function findCachedProjectRoot(startDir = process.cwd()) {
+    let currentDir = path.resolve(startDir);
+    while (true) {
+        const requirementsDir = path.join(currentDir, '.requirements');
+        const projectRootPath = path.join(requirementsDir, CACHE_DIR, PROJECT_ROOT_FILE);
+        if (fs.existsSync(projectRootPath)) {
+            return fs.readFileSync(projectRootPath, 'utf-8').trim();
+        }
+        const parentDir = path.dirname(currentDir);
+        if (parentDir === currentDir) {
+            return null;
+        }
+        currentDir = parentDir;
+    }
+}
+/**
+ * Clear tracking data for a new test run
+ */
+export function clearTrackingFile(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const trackingPath = path.join(cacheDir, TRACKING_FILE);
+    if (fs.existsSync(trackingPath)) {
+        fs.unlinkSync(trackingPath);
+    }
+}
+/**
+ * Append a tracking entry to the JSONL file (cross-process safe)
+ */
+export function appendTrackingEntry(requirementsDir, entry) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const trackingPath = path.join(cacheDir, TRACKING_FILE);
+    const line = JSON.stringify(entry) + '\n';
+    fs.appendFileSync(trackingPath, line);
+}
+/**
+ * Read all tracking entries from the JSONL file
+ */
+export function readTrackingEntries(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir);
+    const trackingPath = path.join(cacheDir, TRACKING_FILE);
+    if (!fs.existsSync(trackingPath)) {
+        return [];
+    }
+    const content = fs.readFileSync(trackingPath, 'utf-8');
+    const entries = [];
+    for (const line of content.split('\n')) {
+        if (line.trim()) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // Skip invalid lines
+            }
+        }
+    }
+    return entries;
+}
+/**
+ * Delete the tracking file after finalize
+ */
+export function deleteTrackingFile(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir);
+    const trackingPath = path.join(cacheDir, TRACKING_FILE);
+    if (fs.existsSync(trackingPath)) {
+        fs.unlinkSync(trackingPath);
+    }
+}
+/**
+ * Read the coverage cache for cloud deduplication
+ */
+export function readCoverageCache(requirementsDir) {
+    const cacheDir = getCacheDir(requirementsDir);
+    const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    if (!fs.existsSync(coveragePath)) {
+        return { current: null, previous: null };
+    }
+    try {
+        const content = fs.readFileSync(coveragePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return { current: null, previous: null };
+    }
+}
+/**
+ * Update the coverage cache after reporting
+ */
+export function updateCoverageCache(requirementsDir, testRunId, requirementKeys) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    const existing = readCoverageCache(requirementsDir);
+    const newCache = {
+        current: {
+            testRunId,
+            timestamp: Date.now(),
+            requirementKeys,
+        },
+        previous: existing.current,
+    };
+    fs.writeFileSync(coveragePath, JSON.stringify(newCache, null, 2));
+}
+/**
+ * Check if a requirement needs reporting based on coverage cache
+ */
+export function needsReporting(requirementKey, cache) {
+    const STALENESS_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
+    // If no current run, everything needs reporting
+    if (!cache.current) {
+        return true;
+    }
+    // If requirement wasn't in current run, it needs reporting
+    if (!cache.current.requirementKeys.includes(requirementKey)) {
+        return true;
+    }
+    // If current run is stale (>4 hours old), needs reporting
+    const age = Date.now() - cache.current.timestamp;
+    if (age > STALENESS_THRESHOLD_MS) {
+        return true;
+    }
+    // Otherwise, skip reporting (already reported recently)
+    return false;
+}
+//# sourceMappingURL=cache.js.map

package/dist/harness/convexReporting.d.ts

@@ -0,0 +1,15 @@
+import { TrackedRequirement } from "./tracking.js";
+/**
+ * Get the current git branch, or null if not in a git repo
+ */
+export declare function getCurrentBranch(cwd?: string): string;
+/**
+ * Report coverage to Convex (async, fire-and-forget)
+ *
+ * @param cwd - Working directory to find .env.local and write cache
+ * @param trackedReqs - Optional tracked requirements map. If not provided, falls back to in-memory tracking.
+ *                      When called from finalizeTestRun (globalTeardown), this should be passed explicitly
+ *                      since the in-memory map is empty in a separate process context.
+ */
+export declare function reportCoverageToConvex(cwd?: string, trackedReqs?: Map<string, TrackedRequirement>): Promise<void>;
+//# sourceMappingURL=convexReporting.d.ts.map

package/dist/harness/convexReporting.js

@@ -0,0 +1,136 @@
+import { execSync } from "child_process";
+import { getTrackedRequirements } from "./tracking.js";
+import { saveCache, getRequirementsToReport } from "./coverageCache.js";
+import { isLocalOnlyProject } from "../utils/local-project.js";
+import { loadEnvFile, getProjectCredentials } from "../utils/env.js";
+/**
+ * Get the current git branch, or null if not in a git repo
+ */
+export function getCurrentBranch(cwd = process.cwd()) {
+    try {
+        const branch = execSync("git rev-parse --abbrev-ref HEAD", {
+            cwd,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "ignore"], // Suppress stderr
+        }).trim();
+        return branch;
+    }
+    catch (error) {
+        // Not in a git repo or git not available
+        return "unknown";
+    }
+}
+/**
+ * Production Convex deployment URL
+ */
+const CONVEX_URL = 'https://data.dotrequirements.io';
+/**
+ * Extract file path and line number from caller location string
+ */
+function parseCallerLocation(location) {
+    // Location format: "filename.ts:123" or "unknown"
+    if (location === "unknown") {
+        return { testFile: undefined, testLine: undefined };
+    }
+    const match = location.match(/^(.+):(\d+)$/);
+    if (match) {
+        return {
+            testFile: match[1],
+            testLine: parseInt(match[2], 10),
+        };
+    }
+    return { testFile: location, testLine: undefined };
+}
+/**
+ * Report coverage to Convex (async, fire-and-forget)
+ *
+ * @param cwd - Working directory to find .env.local and write cache
+ * @param trackedReqs - Optional tracked requirements map. If not provided, falls back to in-memory tracking.
+ *                      When called from finalizeTestRun (globalTeardown), this should be passed explicitly
+ *                      since the in-memory map is empty in a separate process context.
+ */
+export async function reportCoverageToConvex(cwd = process.cwd(), trackedReqs) {
+    try {
+        // Load credentials from .env.local (standard credential discovery)
+        loadEnvFile(cwd);
+        const credentials = getProjectCredentials();
+        // Skip if credentials are missing
+        if (!credentials) {
+            console.log("\nℹ️  Skipping cloud coverage reporting (DOTREQUIREMENTS_PROJECT_ID or DOTREQUIREMENTS_PROJECT_SECRET not configured)");
+            return;
+        }
+        const { projectId, projectSecret } = credentials;
+        // AUTHZ-1.2: Skip cloud reporting for local-only projects (silent)
+        if (isLocalOnlyProject(projectId)) {
+            // Silently skip - local-only projects track coverage in-memory only
+            return;
+        }
+        // Use provided trackedReqs or fall back to in-memory tracking
+        const reqs = trackedReqs ?? getTrackedRequirements();
+        const requirementKeys = Array.from(reqs.keys());
+        // Use caching to filter out requirements that don't need reporting
+        const keysToReport = getRequirementsToReport(requirementKeys, cwd);
+        if (keysToReport.length === 0) {
+            console.log("\n✓ Coverage unchanged since last run (skipping cloud report)");
+            // Still update the cache with current timestamp
+            saveCache({
+                timestamp: Date.now(),
+                requirementKeys,
+            }, cwd);
+            return;
+        }
+        const branch = getCurrentBranch(cwd);
+        // Build coverage payload
+        const coverage = keysToReport.map((key) => {
+            const tracked = reqs.get(key);
+            // Use the first access location (most likely the test that called requirement())
+            const firstAccess = tracked.accessedAt[0] || "unknown";
+            const { testFile, testLine } = parseCallerLocation(firstAccess);
+            return {
+                requirementKey: key,
+                testFile,
+                testLine,
+            };
+        });
+        // Send to Convex
+        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;
+        }
+        const result = await response.json();
+        console.log(`\n✓ Reported ${keysToReport.length} requirement(s) to cloud (branch: ${branch})`);
+        // Update cache with current test run
+        saveCache({
+            timestamp: Date.now(),
+            requirementKeys,
+        }, cwd);
+    }
+    catch (error) {
+        // Don't throw - reporting failures shouldn't break tests
+        console.warn(`\n⚠️  Error reporting coverage to cloud: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=convexReporting.js.map

package/dist/harness/coverageCache.d.ts

@@ -0,0 +1,30 @@
+export interface TestRun {
+    testRunId: string;
+    timestamp: number;
+    requirementKeys: string[];
+}
+export interface CoverageCache {
+    current: TestRun | null;
+    previous: TestRun | null;
+}
+/**
+ * Load the coverage cache from disk
+ */
+export declare function loadCache(cwd?: string): CoverageCache;
+/**
+ * Save a new test run to the cache, rotating current → previous
+ */
+export declare function saveCache(testRun: Omit<TestRun, "testRunId">, cwd?: string): void;
+/**
+ * Check if a requirement needs reporting based on cache state
+ * Returns true if:
+ * - Requirement was not covered in previous run, OR
+ * - Previous run was more than 4 hours ago
+ */
+export declare function needsReporting(requirementKey: string, cache: CoverageCache): boolean;
+/**
+ * Get the list of requirements that need reporting
+ * (new or changed since last run, or stale)
+ */
+export declare function getRequirementsToReport(currentRequirementKeys: string[], cwd?: string): string[];
+//# sourceMappingURL=coverageCache.d.ts.map

package/dist/harness/coverageCache.js

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { v4 as uuidv4 } from "uuid";
+const CACHE_FILE = ".requirements/.coverage-cache.json";
+const STALENESS_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
+/**
+ * Load the coverage cache from disk
+ */
+export function loadCache(cwd = process.cwd()) {
+    const cachePath = join(cwd, CACHE_FILE);
+    if (!existsSync(cachePath)) {
+        return { current: null, previous: null };
+    }
+    try {
+        const content = readFileSync(cachePath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // If cache is corrupt, start fresh
+        console.warn("Warning: Coverage cache is corrupt, starting fresh");
+        return { current: null, previous: null };
+    }
+}
+/**
+ * Save a new test run to the cache, rotating current → previous
+ */
+export function saveCache(testRun, cwd = process.cwd()) {
+    const cache = loadCache(cwd);
+    const cachePath = join(cwd, CACHE_FILE);
+    const newCache = {
+        current: {
+            testRunId: uuidv4(),
+            ...testRun,
+        },
+        previous: cache.current,
+    };
+    writeFileSync(cachePath, JSON.stringify(newCache, null, 2), "utf-8");
+}
+/**
+ * Check if a requirement needs reporting based on cache state
+ * Returns true if:
+ * - Requirement was not covered in previous run, OR
+ * - Previous run was more than 4 hours ago
+ */
+export function needsReporting(requirementKey, cache) {
+    // If no previous run, everything needs reporting
+    if (!cache.current) {
+        return true;
+    }
+    // If requirement wasn't in current run, it needs reporting
+    if (!cache.current.requirementKeys.includes(requirementKey)) {
+        return true;
+    }
+    // If current run is stale (>4 hours old), needs reporting
+    const age = Date.now() - cache.current.timestamp;
+    if (age > STALENESS_THRESHOLD_MS) {
+        return true;
+    }
+    // Otherwise, skip reporting (already reported recently)
+    return false;
+}
+/**
+ * Get the list of requirements that need reporting
+ * (new or changed since last run, or stale)
+ */
+export function getRequirementsToReport(currentRequirementKeys, cwd = process.cwd()) {
+    const cache = loadCache(cwd);
+    return currentRequirementKeys.filter((key) => needsReporting(key, cache));
+}
+//# sourceMappingURL=coverageCache.js.map

package/dist/harness/finalize.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 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
+ */
+export interface FinalizeOptions {
+    /** Working directory to start search from (defaults to cwd) */
+    cwd?: string;
+    /** Whether to report to cloud (defaults to true) */
+    reportToCloud?: boolean;
+    /** Whether to print local report (defaults to true) */
+    printLocalReport?: boolean;
+    /** Whether to clean up tracking data on success (defaults to true) */
+    cleanup?: boolean;
+}
+export interface FinalizeResult {
+    /** Number of unique requirements exercised */
+    requirementsTested: number;
+    /** Total requirements available */
+    totalRequirements: number;
+    /** Coverage percentage */
+    coveragePercent: number;
+    /** Whether cloud report was sent */
+    cloudReportSent: boolean;
+    /** Number of requirements reported to cloud (may be less due to deduplication) */
+    requirementsReportedToCloud: number;
+    /** Error if cloud reporting failed */
+    cloudError?: string;
+}
+/**
+ * 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 declare function finalize(options?: FinalizeOptions): Promise<FinalizeResult>;
+//# sourceMappingURL=finalize.d.ts.map