@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/push/core.js

@@ -9,11 +9,11 @@
  * - Executing the push
  * - Updating local files with document IDs and timestamps
  */
-import * as fs from 'fs';
-import * as path from 'path';
-import { ConvexHttpClient } from 'convex/browser';
-import { parseRequirementsFromFile, getAllRequirements, parseRequirementKey, buildRequirementsFile, } from '../schema/index.js';
-import { api } from '../convex.js';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ConvexHttpClient } from "convex/browser";
+import { api } from "../convex.js";
+import { buildRequirementsFile, getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -36,7 +36,7 @@ export function parseFilesForPush(filePaths) {
     let totalRequirements = 0;
     for (const filePath of filePaths) {
         // Read raw file content
-        const rawContent = fs.readFileSync(filePath, 'utf-8');
+        const rawContent = fs.readFileSync(filePath, "utf-8");
         // Parse to get metadata and requirements
         const parsed = parseRequirementsFromFile(filePath);
         const flatRequirements = getAllRequirements(parsed.requirements);
@@ -82,9 +82,9 @@ export async function dryRunPush(parsedFiles, credentials) {
                 file,
                 result: {
                     dryRun: true,
-                    action: 'invalid',
+                    action: "invalid",
                     title: fileName,
-                    error: 'Missing document section in frontmatter',
+                    error: "Missing document section in frontmatter",
                 },
             });
             continue;
@@ -95,7 +95,7 @@ export async function dryRunPush(parsedFiles, credentials) {
                     projectSlug: credentials.projectId,
                     projectSecret: credentials.projectSecret,
                 },
-                target: { type: 'project', slug: credentials.projectId },
+                target: { type: "project", slug: credentials.projectId },
                 documentId: doc.id,
                 title: doc.title,
                 markdownContent: file.markdownContent,
@@ -109,7 +109,7 @@ export async function dryRunPush(parsedFiles, credentials) {
                 file,
                 result: {
                     dryRun: true,
-                    action: 'invalid',
+                    action: "invalid",
                     title: doc.title,
                     error: err.message,
                 },
@@ -117,10 +117,10 @@ export async function dryRunPush(parsedFiles, credentials) {
         }
     }
     // Categorize results
-    const updates = dryRunResults.filter((r) => r.result.action === 'update');
-    const creates = dryRunResults.filter((r) => r.result.action === 'create');
-    const notFound = dryRunResults.filter((r) => r.result.action === 'not_found');
-    const invalid = dryRunResults.filter((r) => r.result.action === 'invalid');
+    const updates = dryRunResults.filter((r) => r.result.action === "update");
+    const creates = dryRunResults.filter((r) => r.result.action === "create");
+    const notFound = dryRunResults.filter((r) => r.result.action === "not_found");
+    const invalid = dryRunResults.filter((r) => r.result.action === "invalid");
     // Check for conflicts on updates (cloud changed since last pull)
     const conflicts = [];
     if (updates.length > 0) {
@@ -130,7 +130,7 @@ export async function dryRunPush(parsedFiles, credentials) {
                 projectSlug: credentials.projectId,
                 projectSecret: credentials.projectSecret,
             },
-            target: { type: 'project', slug: credentials.projectId },
+            target: { type: "project", slug: credentials.projectId },
             documentIds: docIds,
         });
         const cloudMetaByDocId = new Map(cloudMetadata.map((m) => [m.documentId, m]));
@@ -174,28 +174,28 @@ export async function executePush(dryRunResult, credentials) {
         const doc = file.metadata.document;
         const fileName = path.basename(file.filePath);
         // For not_found, clear the ID so we create a new document
-        const effectiveDocId = result.action === 'not_found' ? undefined : doc.id;
+        const effectiveDocId = result.action === "not_found" ? undefined : doc.id;
         try {
             const pushResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
                 projectAuth: {
                     projectSlug: credentials.projectId,
                     projectSecret: credentials.projectSecret,
                 },
-                target: { type: 'project', slug: credentials.projectId },
+                target: { type: "project", slug: credentials.projectId },
                 documentId: effectiveDocId,
                 title: doc.title,
                 markdownContent: file.markdownContent,
                 defaultPrefix: doc.defaultPrefix,
                 dryRun: false,
             }));
-            const isCreate = result.action === 'create' || result.action === 'not_found';
+            const isCreate = result.action === "create" || result.action === "not_found";
             if (isCreate) {
                 // New document - write ID back to file
                 doc.id = pushResult;
                 file.metadata.pulledAt = new Date().toISOString();
                 file.metadata.version = 1;
                 const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 created++;
             }
             else {
@@ -203,7 +203,7 @@ export async function executePush(dryRunResult, credentials) {
                 file.metadata.pulledAt = new Date().toISOString();
                 file.metadata.version = (file.metadata.version || 0) + 1;
                 const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 updated++;
             }
         }

package/dist/push/index.d.ts

@@ -4,5 +4,5 @@
  * Shared push logic for syncing local requirements files to the cloud.
  * Used by both CLI push command and MCP push_requirements tool.
  */
-export { type PushCredentials, type ParsedFile, type CloudDocumentMetadata, type DryRunResultItem, type FileWithDryRun, type ConflictInfo, type DryRunResult, type PushResult, extractMarkdownContent, parseFilesForPush, dryRunPush, executePush, } from './core.js';
+export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -4,7 +4,7 @@
  * Shared push logic for syncing local requirements files to the cloud.
  * Used by both CLI push command and MCP push_requirements tool.
  */
-export { 
+export { dryRunPush, executePush, 
 // Functions
-extractMarkdownContent, parseFilesForPush, dryRunPush, executePush, } from './core.js';
+extractMarkdownContent, parseFilesForPush, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/requirements/cloud-ai.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Cloud-AI library — hosted endpoints for style review, test review, and
+ * project context retrieval. Shared between the MCP handlers and the CLI
+ * verbs that wrap them.
+ *
+ * Each function does one cloud call and returns the unwrapped result (or
+ * throws on failure). Surface-specific concerns (error formatting, exit
+ * codes, MCP tool responses) live in the callers.
+ */
+/**
+ * Default base URL for the hosted AI endpoints (`/api/style-check`,
+ * `/api/review-test`). Overridable via the `apiBaseUrl` argument or
+ * the `DOTREQUIREMENTS_API_URL` environment variable in callers.
+ */
+export declare const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
+export interface StyleCheckParams {
+    apiBaseUrl: string;
+    projectId: string;
+    projectSecret: string;
+    fileContents: string;
+    fileType: "requirements" | "test";
+    model?: string;
+}
+/**
+ * POST to `/api/style-check`. Returns the feedback text on success;
+ * throws an Error with the underlying failure reason on a non-OK
+ * response or a network error.
+ */
+export declare function fetchStyleCheckFeedback(params: StyleCheckParams): Promise<string>;
+export interface ReviewTestParams {
+    apiBaseUrl: string;
+    projectId: string;
+    projectSecret: string;
+    testFileContents: string;
+    requirements: Array<{
+        id: string;
+        content: string;
+        testedIds: string[];
+    }>;
+}
+/**
+ * POST to `/api/review-test`. Returns the feedback text on success;
+ * throws an Error with the underlying failure reason on a non-OK
+ * response or a network error.
+ */
+export declare function fetchReviewTestFeedback(params: ReviewTestParams): Promise<string>;
+export interface ProjectContext {
+    projectContext: string | null;
+    requirementsStyleContext: string | null;
+}
+/**
+ * Query Convex for project-level AI context (project description and
+ * requirements style guidance). Returns null on any failure — the caller
+ * is expected to degrade gracefully if context is unavailable.
+ */
+export declare function getProjectContext(projectId: string, projectSecret: string, convexUrl: string): Promise<ProjectContext | null>;
+//# sourceMappingURL=cloud-ai.d.ts.map

package/dist/requirements/cloud-ai.js

@@ -0,0 +1,104 @@
+/**
+ * Cloud-AI library — hosted endpoints for style review, test review, and
+ * project context retrieval. Shared between the MCP handlers and the CLI
+ * verbs that wrap them.
+ *
+ * Each function does one cloud call and returns the unwrapped result (or
+ * throws on failure). Surface-specific concerns (error formatting, exit
+ * codes, MCP tool responses) live in the callers.
+ */
+/**
+ * Default base URL for the hosted AI endpoints (`/api/style-check`,
+ * `/api/review-test`). Overridable via the `apiBaseUrl` argument or
+ * the `DOTREQUIREMENTS_API_URL` environment variable in callers.
+ */
+export const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
+/**
+ * POST to `/api/style-check`. Returns the feedback text on success;
+ * throws an Error with the underlying failure reason on a non-OK
+ * response or a network error.
+ */
+export async function fetchStyleCheckFeedback(params) {
+    const response = await fetch(`${params.apiBaseUrl}/api/style-check`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            projectId: params.projectId,
+            projectSecret: params.projectSecret,
+            fileContents: params.fileContents,
+            fileType: params.fileType,
+            model: params.model,
+        }),
+    });
+    if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({})));
+        throw new Error(errorData.error || response.statusText);
+    }
+    const data = (await response.json());
+    return data.feedback;
+}
+/**
+ * POST to `/api/review-test`. Returns the feedback text on success;
+ * throws an Error with the underlying failure reason on a non-OK
+ * response or a network error.
+ */
+export async function fetchReviewTestFeedback(params) {
+    const response = await fetch(`${params.apiBaseUrl}/api/review-test`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            projectId: params.projectId,
+            projectSecret: params.projectSecret,
+            testFileContents: params.testFileContents,
+            requirements: params.requirements,
+        }),
+    });
+    if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({})));
+        throw new Error(errorData.error || response.statusText);
+    }
+    const data = (await response.json());
+    return data.feedback;
+}
+/**
+ * Query Convex for project-level AI context (project description and
+ * requirements style guidance). Returns null on any failure — the caller
+ * is expected to degrade gracefully if context is unavailable.
+ */
+export async function getProjectContext(projectId, projectSecret, convexUrl) {
+    try {
+        const response = await fetch(`${convexUrl}/api/query`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                path: "projects/queries:get",
+                args: {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: {
+                        type: "project",
+                        slug: projectId,
+                    },
+                },
+                format: "json",
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const json = (await response.json());
+        if (json.status === "error" || !json.value) {
+            return null;
+        }
+        return {
+            projectContext: json.value.projectContext ?? null,
+            requirementsStyleContext: json.value.requirementsStyleContext ?? null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=cloud-ai.js.map

package/dist/requirements/cloud-coverage.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export interface RequirementCoverageRecord {
+    requirementKey: string;
+    lastTestedAt: number | null;
+    branch: string | null;
+    testFile: string | null;
+    testLine: number | null;
+    allBranches: Array<{
+        branch: string;
+        lastTestedAt: number;
+        testFile?: string;
+        testLine?: number;
+    }>;
+}
+export interface ProjectCoverageRecord {
+    tested: Array<{
+        requirementKey: string;
+        lastTestedAt: number;
+        branch: string;
+        testFile?: string;
+        testLine?: number;
+    }>;
+    untested: string[];
+}
+/**
+ * Query cloud for coverage on a single requirement.
+ */
+export declare function getRequirementCoverage(requirementKey: string, projectId: string, projectSecret: string, convexUrl: string): Promise<RequirementCoverageRecord>;
+/**
+ * Query cloud for project-wide coverage summary, optionally filtered by
+ * branch or recorded-since timestamp.
+ */
+export declare function getProjectCoverage(projectId: string, projectSecret: string, convexUrl: string, options?: {
+    branch?: string;
+    sinceTimestamp?: number;
+}): Promise<ProjectCoverageRecord>;
+//# sourceMappingURL=cloud-coverage.d.ts.map

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/{mcp → requirements}/grep.d.ts

@@ -1,4 +1,13 @@
-import type { TestReference } from './types.js';
+/**
+ * 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
  *