@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/requirements/cloud-coverage.js

@@ -0,0 +1,60 @@
+/**
+ * Cloud-coverage library — hosted endpoints for querying persisted test
+ * coverage from dot•requirements cloud. Shared between the MCP `report`
+ * tool and the CLI `report` verb's `--source cloud` mode.
+ */
+/**
+ * Query cloud for coverage on a single requirement.
+ */
+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}`);
+    }
+    const json = (await response.json());
+    if (json.status === "error") {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
+}
+/**
+ * Query cloud for project-wide coverage summary, optionally filtered by
+ * branch or recorded-since timestamp.
+ */
+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}`);
+    }
+    const json = (await response.json());
+    if (json.status === "error") {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
+}
+//# sourceMappingURL=cloud-coverage.js.map

package/dist/requirements/coverage.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Local-coverage library — reads the test-harness cache produced by
+ * `dotreq harness prepare` + your test run, and turns it into a structured
+ * coverage report. Shared between the CLI `report` verb's local mode and
+ * the MCP `report` tool's `source: "local"` mode.
+ *
+ * Cloud-side coverage queries live next door in cloud-coverage.ts.
+ */
+export interface CoverageEntry {
+    key: string;
+    label: string | null;
+    content: string;
+    tested: boolean;
+    locations: string[];
+}
+export interface LocalReportSummary {
+    total: number;
+    tested: number;
+    untested: number;
+    coveragePercent: number;
+}
+export interface LocalReportResult {
+    entries: CoverageEntry[];
+    summary: LocalReportSummary;
+    /** Soft warnings the caller may want to surface (stale cache, empty
+     * tracking file, etc.). Hard errors throw instead. */
+    warnings: string[];
+}
+export declare class LocalReportCacheMissingError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a coverage report from the project's local test-harness cache.
+ *
+ * Throws {@link LocalReportCacheMissingError} when the cache is missing
+ * entirely (the caller hasn't run `dotreq harness prepare` yet). Soft
+ * issues — stale cache, missing or empty tracking file — are returned
+ * as `warnings` so the caller can decide where they belong (stderr for
+ * CLI, response body for MCP).
+ */
+export declare function buildLocalReport(opts: {
+    projectRoot: string;
+    requirementFilter?: string;
+}): LocalReportResult;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/requirements/coverage.js

@@ -0,0 +1,114 @@
+/**
+ * Local-coverage library — reads the test-harness cache produced by
+ * `dotreq harness prepare` + your test run, and turns it into a structured
+ * coverage report. Shared between the CLI `report` verb's local mode and
+ * the MCP `report` tool's `source: "local"` mode.
+ *
+ * Cloud-side coverage queries live next door in cloud-coverage.ts.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findRequirementsDir, isCacheStale, readTrackingEntries, } from "../harness/cache.js";
+export class LocalReportCacheMissingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LocalReportCacheMissingError";
+    }
+}
+/**
+ * Build a coverage report from the project's local test-harness cache.
+ *
+ * Throws {@link LocalReportCacheMissingError} when the cache is missing
+ * entirely (the caller hasn't run `dotreq harness prepare` yet). Soft
+ * issues — stale cache, missing or empty tracking file — are returned
+ * as `warnings` so the caller can decide where they belong (stderr for
+ * CLI, response body for MCP).
+ */
+export function buildLocalReport(opts) {
+    const requirementsDir = findRequirementsDir(opts.projectRoot);
+    if (!requirementsDir) {
+        throw new LocalReportCacheMissingError('No .requirements/ directory found. Run "dotrequirements init" to initialize your project.');
+    }
+    const cacheDir = path.join(requirementsDir, ".cache");
+    const lookupPath = path.join(cacheDir, "lookup.json");
+    if (!fs.existsSync(lookupPath)) {
+        throw new LocalReportCacheMissingError('No lookup cache found. Run "dotrequirements harness prepare" first to build the cache.');
+    }
+    const warnings = [];
+    const lookup = JSON.parse(fs.readFileSync(lookupPath, "utf-8"));
+    try {
+        const cacheStat = fs.statSync(lookupPath);
+        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+            warnings.push('Cache may be stale — requirements have changed since last prepare. Run "dotrequirements harness prepare" to rebuild.');
+        }
+    }
+    catch {
+        // ignore stat errors
+    }
+    const trackingPath = path.join(cacheDir, "tracking.jsonl");
+    const trackingExists = fs.existsSync(trackingPath);
+    const entries = readTrackingEntries(requirementsDir);
+    if (!trackingExists) {
+        warnings.push('No tracking data found. Run your tests first, or run "dotrequirements harness prepare" to start a new tracking session.');
+    }
+    else if (entries.length === 0) {
+        warnings.push("Tracking file is empty — no requirements were tracked during tests.");
+    }
+    const coverageEntries = buildCoverageEntries(lookup, entries, opts.requirementFilter);
+    const tested = coverageEntries.filter((c) => c.tested).length;
+    const total = coverageEntries.length;
+    const coveragePercent = total > 0 ? parseFloat(((tested / total) * 100).toFixed(1)) : 0;
+    return {
+        entries: coverageEntries,
+        summary: {
+            total,
+            tested,
+            untested: total - tested,
+            coveragePercent,
+        },
+        warnings,
+    };
+}
+function buildCoverageEntries(lookup, entries, filterKey) {
+    const locationsByKey = new Map();
+    for (const entry of entries) {
+        if (!locationsByKey.has(entry.requirementKey)) {
+            locationsByKey.set(entry.requirementKey, new Set());
+        }
+        locationsByKey.get(entry.requirementKey).add(entry.callerLocation);
+    }
+    const results = [];
+    for (const [key, req] of Object.entries(lookup.requirements)) {
+        if (req.isAlias)
+            continue;
+        if (filterKey && key !== filterKey && !key.startsWith(`${filterKey}.`)) {
+            continue;
+        }
+        const locations = new Set();
+        const keyLocations = locationsByKey.get(key);
+        if (keyLocations) {
+            keyLocations.forEach((l) => {
+                locations.add(l);
+            });
+        }
+        for (const [aliasKey, aliasReq] of Object.entries(lookup.requirements)) {
+            if (aliasReq.isAlias && aliasReq.id === req.id) {
+                const aliasLocations = locationsByKey.get(aliasKey);
+                if (aliasLocations) {
+                    aliasLocations.forEach((l) => {
+                        locations.add(l);
+                    });
+                }
+            }
+        }
+        results.push({
+            key,
+            label: req.label || null,
+            content: req.content,
+            tested: locations.size > 0,
+            locations: Array.from(locations),
+        });
+    }
+    return results;
+}
+//# sourceMappingURL=coverage.js.map

package/dist/requirements/grep.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A `requirement(...)` call site found in source code.
+ */
+export interface TestReference {
+    file: string;
+    line: number;
+    column: number;
+    requirementId: string;
+    context: string;
+}
+/**
+ * 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

package/dist/requirements/grep.js

@@ -0,0 +1,306 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Check if ripgrep is available
+ */
+async function hasRipgrep() {
+    try {
+        await execFileAsync("rg", ["--version"]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Find all test files that reference a specific requirement ID
+ *
+ * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ */
+export async function findTestsForRequirement(workspaceRoot, requirementId) {
+    const useRg = await hasRipgrep();
+    // Escape special regex characters in the ID
+    const escapedId = requirementId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    // Pattern to match requirement('ID'), requirement("ID"), or requirement(`ID`)
+    const pattern = `requirement\\s*\\(\\s*['"\`]${escapedId}`;
+    try {
+        let output;
+        if (useRg) {
+            // Use ripgrep for better performance
+            // Using execFile with array args to avoid shell injection
+            const { stdout } = await execFileAsync("rg", [
+                "-n",
+                "--column",
+                pattern,
+                "--type",
+                "ts",
+                "--type",
+                "js",
+                "--type",
+                "tsx",
+                "--type",
+                "jsx",
+                workspaceRoot,
+            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // ripgrep returns non-zero on no matches
+            output = stdout;
+        }
+        else {
+            // Fall back to grep using execFile
+            const { stdout } = await execFileAsync("grep", [
+                "-rn",
+                "--include=*.ts",
+                "--include=*.tsx",
+                "--include=*.js",
+                "--include=*.jsx",
+                "-E",
+                pattern,
+                workspaceRoot,
+            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // grep returns non-zero on no matches
+            output = stdout;
+        }
+        return parseGrepOutput(output, requirementId, useRg);
+    }
+    catch {
+        // Grep returns exit code 1 when no matches found
+        return [];
+    }
+}
+/**
+ * Find all requirement references in a specific file using AST parsing
+ */
+export async function findRequirementsInFile(filePath) {
+    const { parse } = await import("@babel/parser");
+    const traverse = await import("@babel/traverse");
+    const t = await import("@babel/types");
+    const fs = await import("node:fs");
+    const pathModule = await import("node:path");
+    const results = [];
+    // Resolve relative paths from current working directory
+    let resolvedPath = pathModule.isAbsolute(filePath)
+        ? filePath
+        : pathModule.resolve(process.cwd(), filePath);
+    // If file doesn't exist and path is relative, try resolving from CLI package root
+    if (!pathModule.isAbsolute(filePath) && !fs.existsSync(resolvedPath)) {
+        const cliPackageRoot = pathModule.resolve(__dirname, "../..");
+        const alternativePath = pathModule.resolve(cliPackageRoot, filePath);
+        if (fs.existsSync(alternativePath)) {
+            resolvedPath = alternativePath;
+        }
+    }
+    try {
+        const code = fs.readFileSync(resolvedPath, "utf-8");
+        const ast = parse(code, {
+            sourceType: "module",
+            plugins: ["typescript", "jsx"],
+            errorRecovery: true,
+        });
+        // Handle both ES module and CommonJS exports for traverse
+        // biome-ignore lint/suspicious/noExplicitAny: @babel/traverse ships a CJS default-export that's a callable, with .default property nested 1-2 levels. The interop dance requires escaping the function-vs-namespace type wall.
+        let traverseFunc = traverse;
+        if (typeof traverseFunc !== "function") {
+            traverseFunc = traverseFunc.default;
+        }
+        if (typeof traverseFunc !== "function") {
+            traverseFunc = traverseFunc.default;
+        }
+        traverseFunc(ast, {
+            // biome-ignore lint/suspicious/noExplicitAny: babel-traverse visitor `path` is a deeply-generic NodePath whose precise type depends on what handler you're inside; `any` is the documented practice for plugin code.
+            CallExpression(path) {
+                const callee = path.node.callee;
+                // Check if this is a requirement() call
+                if (t.isIdentifier(callee) && callee.name === "requirement") {
+                    const args = path.node.arguments;
+                    const loc = path.node.loc;
+                    // Extract all string literal arguments (supports multi-requirement calls)
+                    for (const arg of args) {
+                        if (t.isStringLiteral(arg)) {
+                            const requirementId = arg.value;
+                            if (loc) {
+                                results.push({
+                                    file: resolvedPath,
+                                    line: loc.start.line,
+                                    column: loc.start.column + 1, // 1-indexed
+                                    requirementId,
+                                    context: code.split("\n")[loc.start.line - 1] || "",
+                                });
+                            }
+                        }
+                    }
+                }
+            },
+        });
+        return results;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Find all requirement references in the entire workspace
+ *
+ * Uses execFile with array arguments to avoid command injection vulnerabilities.
+ */
+export async function findAllTestReferences(workspaceRoot) {
+    const useRg = await hasRipgrep();
+    // Pattern to match any requirement() call
+    const pattern = `requirement\\s*\\(\\s*['"\`][^'"\`]+`;
+    try {
+        let output;
+        if (useRg) {
+            // Using execFile with array args to avoid shell injection
+            const { stdout } = await execFileAsync("rg", [
+                "-n",
+                "--column",
+                pattern,
+                "--type",
+                "ts",
+                "--type",
+                "js",
+                "--type",
+                "tsx",
+                "--type",
+                "jsx",
+                workspaceRoot,
+            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // ripgrep returns non-zero on no matches
+            output = stdout;
+        }
+        else {
+            const { stdout } = await execFileAsync("grep", [
+                "-rn",
+                "--include=*.ts",
+                "--include=*.tsx",
+                "--include=*.js",
+                "--include=*.jsx",
+                "-E",
+                pattern,
+                workspaceRoot,
+            ], { maxBuffer: 10 * 1024 * 1024 }).catch(() => ({ stdout: "" })); // grep returns non-zero on no matches
+            output = stdout;
+        }
+        return parseGrepOutput(output, "", useRg);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Parse grep/ripgrep output into TestReference objects
+ */
+function parseGrepOutput(output, expectedId, isRipgrep, singleFilePath) {
+    const results = [];
+    const lines = output.trim().split("\n").filter(Boolean);
+    for (const line of lines) {
+        let match;
+        let file;
+        let lineNum;
+        let column;
+        let context;
+        if (isRipgrep) {
+            // ripgrep format: file:line:column:content
+            match = line.match(/^(.+?):(\d+):(\d+):(.*)$/);
+            if (!match)
+                continue;
+            file = match[1];
+            lineNum = parseInt(match[2], 10);
+            column = parseInt(match[3], 10);
+            context = match[4];
+        }
+        else {
+            // grep format: file:line:content (no column)
+            if (singleFilePath) {
+                match = line.match(/^(\d+):(.*)$/);
+                if (!match)
+                    continue;
+                file = singleFilePath;
+                lineNum = parseInt(match[1], 10);
+                context = match[2];
+                column = 1;
+            }
+            else {
+                match = line.match(/^(.+?):(\d+):(.*)$/);
+                if (!match)
+                    continue;
+                file = match[1];
+                lineNum = parseInt(match[2], 10);
+                context = match[3];
+                column = 1;
+            }
+        }
+        // Extract the requirement ID from the context
+        const idMatch = context.match(/requirement\s*\(\s*['"`]([^'"`]+)/);
+        const requirementId = idMatch ? idMatch[1] : expectedId;
+        results.push({
+            file,
+            line: lineNum,
+            column,
+            requirementId,
+            context: context.trim(),
+        });
+    }
+    return results;
+}
+/**
+ * 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 async function getReferencedRequirementIds(workspaceRoot) {
+    const { glob } = await import("glob");
+    const { parse } = await import("@babel/parser");
+    const traverse = await import("@babel/traverse");
+    const t = await import("@babel/types");
+    const fs = await import("node:fs");
+    // Find all test files using glob (same pattern as get_requirement tool)
+    const testFiles = await glob("**/*.{test,spec}.{js,jsx,ts,tsx}", {
+        cwd: workspaceRoot,
+        absolute: true,
+        ignore: ["**/node_modules/**", "**/dist/**", "**/build/**"],
+    });
+    const allRequirementIds = [];
+    // For each test file, parse AST and extract requirement IDs
+    for (const file of testFiles) {
+        try {
+            const code = fs.readFileSync(file, "utf-8");
+            const ast = parse(code, {
+                sourceType: "module",
+                plugins: ["typescript", "jsx"],
+                errorRecovery: true,
+            });
+            // Handle both ES module and CommonJS exports for traverse
+            // @babel/traverse can be imported as: traverse.default.default in compiled code
+            // biome-ignore lint/suspicious/noExplicitAny: see earlier comment on babel/traverse CJS/ESM interop
+            let traverseFunc = traverse;
+            if (typeof traverseFunc !== "function") {
+                traverseFunc = traverseFunc.default;
+            }
+            if (typeof traverseFunc !== "function") {
+                traverseFunc = traverseFunc.default;
+            }
+            traverseFunc(ast, {
+                // biome-ignore lint/suspicious/noExplicitAny: babel-traverse visitor `path` is a deeply-generic NodePath whose precise type depends on what handler you're inside; `any` is the documented practice for plugin code.
+                CallExpression(path) {
+                    const callee = path.node.callee;
+                    // Check if this is a requirement() call
+                    if (t.isIdentifier(callee) && callee.name === "requirement") {
+                        const args = path.node.arguments;
+                        // Extract all string literal arguments (supports multi-requirement calls)
+                        for (const arg of args) {
+                            if (t.isStringLiteral(arg)) {
+                                allRequirementIds.push(arg.value);
+                            }
+                        }
+                    }
+                },
+            });
+        }
+        catch { }
+    }
+    // Extract root IDs by removing the path suffix (everything after the first dot)
+    const rootIds = allRequirementIds.map((id) => {
+        const dotIndex = id.indexOf(".");
+        return dotIndex > 0 ? id.substring(0, dotIndex) : id;
+    });
+    return new Set(rootIds);
+}
+//# sourceMappingURL=grep.js.map

package/dist/requirements/index.d.ts

@@ -0,0 +1,73 @@
+import { type Metadata, type RequirementNode } from "../schema/index.js";
+/**
+ * Flattened requirement for search results
+ */
+export interface FlattenedRequirement {
+    id: string;
+    rootId: string;
+    label: string;
+    content: string;
+    path: string[];
+    sourceFile: string;
+    documentTitle: string;
+}
+/**
+ * Parsed requirements file
+ */
+export interface ParsedRequirementsFile {
+    metadata: Metadata;
+    requirements: RequirementNode[];
+}
+/**
+ * Find all *.requirements.md files in the workspace.
+ * Supports both .requirements/ directories and colocated files.
+ * Excludes example files, test fixtures, and build artifacts.
+ */
+export declare function findRequirementsFiles(workspaceRoot: string): Promise<string[]>;
+/**
+ * Synchronous variant of {@link findRequirementsFiles}. Used by code paths
+ * that can't await (e.g. the test-harness lookup-cache builder).
+ */
+export declare function findRequirementsFilesSync(workspaceRoot: string): string[];
+/**
+ * Load all requirements from the workspace
+ */
+export declare function loadAllRequirements(workspaceRoot: string): Promise<{
+    files: ParsedRequirementsFile[];
+    flattened: FlattenedRequirement[];
+}>;
+/**
+ * Flatten a requirements file into searchable requirements
+ */
+export declare function flattenRequirementsFile(file: ParsedRequirementsFile, sourceFile: string): FlattenedRequirement[];
+/**
+ * Search requirements by text query
+ */
+export declare function searchRequirements(requirements: FlattenedRequirement[], query: string): FlattenedRequirement[];
+/**
+ * Get a specific requirement by ID (supports partial matching)
+ */
+export declare function getRequirementById(requirements: FlattenedRequirement[], id: string): FlattenedRequirement | undefined;
+/**
+ * Get a requirement and all its children
+ */
+export declare function getRequirementTree(requirements: FlattenedRequirement[], rootId: string): FlattenedRequirement[];
+/**
+ * Format a requirement for display
+ */
+export declare function formatRequirement(req: FlattenedRequirement): string;
+/**
+ * Filter a requirements file's content to only include specified requirement keys.
+ * Parses the file content, filters top-level requirements by key, and rebuilds as
+ * markdown requirement blocks (without frontmatter).
+ */
+export declare function filterRequirementsByKeys(fileContents: string, keys: string[]): {
+    filteredContent: string;
+    foundKeys: string[];
+    missingKeys: string[];
+};
+/**
+ * Format a requirement tree for display
+ */
+export declare function formatRequirementTree(requirements: FlattenedRequirement[]): string;
+//# sourceMappingURL=index.d.ts.map