@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/mcp/requirements.js

@@ -1,30 +1,30 @@
-import * as path from 'path';
-import { glob } from 'glob';
-import { parseRequirementsFromFile, parseRequirementsFile, buildRequirementMarkdown, getAllRequirements, } from '../schema/index.js';
+import * as path from "node:path";
+import { glob } from "glob";
+import { buildRequirementMarkdown, getAllRequirements, parseRequirementsFile, parseRequirementsFromFile, } from "../schema/index.js";
 /**
  * Find all *.requirements.md files in the workspace.
  * Supports both .requirements/ directories and colocated files.
  * Excludes example files, test fixtures, and build artifacts.
  */
 export async function findRequirementsFiles(workspaceRoot) {
-    const pattern = '**/*.requirements.md';
+    const pattern = "**/*.requirements.md";
     const matches = await glob(pattern, {
         cwd: workspaceRoot,
         ignore: [
-            '**/node_modules/**',
-            '**/dist/**',
-            '**/.git/**',
-            '**/build/**',
+            "**/node_modules/**",
+            "**/dist/**",
+            "**/.git/**",
+            "**/build/**",
             // Exclude example and test fixture directories
-            '**/example/**',
-            '**/examples/**',
-            '**/__tests__/**',
-            '**/fixtures/**',
-            '**/.fixtures/**',
+            "**/example/**",
+            "**/examples/**",
+            "**/__tests__/**",
+            "**/fixtures/**",
+            "**/.fixtures/**",
         ],
         dot: true, // Include dotfiles/dotdirs like .requirements/
     });
-    return matches.map(m => path.join(workspaceRoot, m));
+    return matches.map((m) => path.join(workspaceRoot, m));
 }
 /**
  * Load all requirements from the workspace
@@ -56,9 +56,9 @@ export function flattenRequirementsFile(file, sourceFile) {
     const allReqs = getAllRequirements(file.requirements);
     for (const req of allReqs) {
         // Extract position from ID (e.g., "REQ123.0.1" -> "0.1")
-        const idParts = req.id.split('.');
+        const idParts = req.id.split(".");
         const rootId = idParts[0];
-        const position = idParts.slice(1).join('.');
+        const position = idParts.slice(1).join(".");
         results.push({
             id: req.id,
             rootId: rootId,
@@ -76,7 +76,7 @@ export function flattenRequirementsFile(file, sourceFile) {
  */
 export function searchRequirements(requirements, query) {
     const lowerQuery = query.toLowerCase();
-    return requirements.filter(req => {
+    return requirements.filter((req) => {
         // Search in ID
         if (req.id.toLowerCase().includes(lowerQuery))
             return true;
@@ -94,24 +94,24 @@ export function searchRequirements(requirements, query) {
  */
 export function getRequirementById(requirements, id) {
     // Exact match first
-    const exact = requirements.find(r => r.id === id);
+    const exact = requirements.find((r) => r.id === id);
     if (exact)
         return exact;
     // Try partial match (just the root ID)
-    return requirements.find(r => r.rootId === id || r.id.startsWith(id + '.'));
+    return requirements.find((r) => r.rootId === id || r.id.startsWith(`${id}.`));
 }
 /**
  * Get a requirement and all its children
  */
 export function getRequirementTree(requirements, rootId) {
-    return requirements.filter(r => r.rootId === rootId || r.id === rootId);
+    return requirements.filter((r) => r.rootId === rootId || r.id === rootId);
 }
 /**
  * Format a requirement for display
  */
 export function formatRequirement(req) {
-    const indent = '  '.repeat(req.path.length);
-    const label = req.label ? ` (${req.label})` : '';
+    const indent = "  ".repeat(req.path.length);
+    const label = req.label ? ` (${req.label})` : "";
     return `${indent}${req.id}${label}: ${req.content}`;
 }
 /**
@@ -121,11 +121,11 @@ export function formatRequirement(req) {
  */
 export function filterRequirementsByKeys(fileContents, keys) {
     const { requirements } = parseRequirementsFile(fileContents);
-    const upperKeys = keys.map(k => k.toUpperCase());
-    const filtered = requirements.filter(r => upperKeys.includes(r.id.toUpperCase()));
-    const foundKeys = filtered.map(r => r.id);
-    const missingKeys = upperKeys.filter(k => !foundKeys.map(f => f.toUpperCase()).includes(k));
-    const filteredContent = filtered.map(buildRequirementMarkdown).join('\n');
+    const upperKeys = keys.map((k) => k.toUpperCase());
+    const filtered = requirements.filter((r) => upperKeys.includes(r.id.toUpperCase()));
+    const foundKeys = filtered.map((r) => r.id);
+    const missingKeys = upperKeys.filter((k) => !foundKeys.map((f) => f.toUpperCase()).includes(k));
+    const filteredContent = filtered.map(buildRequirementMarkdown).join("\n");
     return { filteredContent, foundKeys, missingKeys };
 }
 /**
@@ -137,8 +137,8 @@ export function formatRequirementTree(requirements) {
         // Compare paths element by element for proper tree order
         const maxLen = Math.max(a.path.length, b.path.length);
         for (let i = 0; i < maxLen; i++) {
-            const aVal = i < a.path.length ? parseInt(a.path[i]) : -1;
-            const bVal = i < b.path.length ? parseInt(b.path[i]) : -1;
+            const aVal = i < a.path.length ? parseInt(a.path[i], 10) : -1;
+            const bVal = i < b.path.length ? parseInt(b.path[i], 10) : -1;
             // If one path is a prefix of the other, the shorter one comes first
             if (aVal === -1)
                 return -1;
@@ -150,6 +150,6 @@ export function formatRequirementTree(requirements) {
         }
         return 0;
     });
-    return sorted.map(formatRequirement).join('\n');
+    return sorted.map(formatRequirement).join("\n");
 }
 //# sourceMappingURL=requirements.js.map

package/dist/mcp/testCodeExtractor.js

@@ -4,30 +4,32 @@
  * Finds requirement() call references and extracts the enclosing
  * meaningful code block (function, describe, test, etc.)
  */
-import { parse } from '@babel/parser';
-import traverse from '@babel/traverse';
-import * as t from '@babel/types';
-import * as fs from 'fs';
+import * as fs from "node:fs";
+import { parse } from "@babel/parser";
+import traverse from "@babel/traverse";
+import * as t from "@babel/types";
 /**
  * Find all test code blocks that reference a specific requirement
  */
 export function findTestCodeForRequirement(filePath, requirementId) {
     try {
-        const code = fs.readFileSync(filePath, 'utf-8');
+        const code = fs.readFileSync(filePath, "utf-8");
         const results = [];
         // Parse with TypeScript and JSX support
         const ast = parse(code, {
-            sourceType: 'module',
-            plugins: ['typescript', 'jsx'],
+            sourceType: "module",
+            plugins: ["typescript", "jsx"],
             errorRecovery: true,
         });
         // Handle both ES module and CommonJS exports
-        const traverseFunc = typeof traverse === 'function' ? traverse : traverse.default;
+        const traverseFunc = 
+        // biome-ignore lint/suspicious/noExplicitAny: @babel/traverse CJS default-export interop (callable function vs namespace import)
+        typeof traverse === "function" ? traverse : traverse.default;
         traverseFunc(ast, {
             CallExpression(path) {
                 // Check if this is a requirement('ID', ...) call
                 const callee = path.node.callee;
-                if (t.isIdentifier(callee) && callee.name === 'requirement') {
+                if (t.isIdentifier(callee) && callee.name === "requirement") {
                     const args = path.node.arguments;
                     // Extract all string literal arguments (supports multi-requirement calls)
                     const refIds = [];
@@ -39,12 +41,11 @@ export function findTestCodeForRequirement(filePath, requirementId) {
                     // Check if any argument matches the requirement we're looking for
                     // Match exact ID or if it's a child (e.g., searching for REQ-123 matches REQ-123.0)
                     for (const refId of refIds) {
-                        const isMatch = refId === requirementId ||
-                            refId.startsWith(`${requirementId}.`);
+                        const isMatch = refId === requirementId || refId.startsWith(`${requirementId}.`);
                         if (isMatch) {
                             // Find the meaningful enclosing block
                             const contextNode = findMeaningfulParent(path);
-                            if (contextNode && contextNode.node.loc) {
+                            if (contextNode?.node.loc) {
                                 const { start, end } = contextNode.node.loc;
                                 const nodeStart = contextNode.node.start ?? 0;
                                 const nodeEnd = contextNode.node.end ?? code.length;
@@ -91,15 +92,15 @@ function findMeaningfulParent(path) {
             const callee = node.callee;
             // Common test framework function names
             const testFunctionNames = [
-                'describe',
-                'it',
-                'test',
-                'suite',
-                'context',
-                'beforeEach',
-                'afterEach',
-                'beforeAll',
-                'afterAll',
+                "describe",
+                "it",
+                "test",
+                "suite",
+                "context",
+                "beforeEach",
+                "afterEach",
+                "beforeAll",
+                "afterAll",
             ];
             if (t.isIdentifier(callee) && testFunctionNames.includes(callee.name)) {
                 return current;
@@ -125,7 +126,7 @@ export function findFilesWithRequirement(files, requirementId) {
     const matchingFiles = [];
     for (const file of files) {
         try {
-            const code = fs.readFileSync(file, 'utf-8');
+            const code = fs.readFileSync(file, "utf-8");
             // Check for exact match or child references (e.g., AUTH-VALID-LOGIN or AUTH-VALID-LOGIN.0)
             // Simple string search first for performance
             // Patterns match both single and multi-arg calls:
@@ -142,10 +143,7 @@ export function findFilesWithRequirement(files, requirementId) {
                 matchingFiles.push(file);
             }
         }
-        catch (error) {
-            // Skip files that can't be read
-            continue;
-        }
+        catch (error) { }
     }
     return matchingFiles;
 }

package/dist/mcp/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Re-export shared types from CLI schema module
  */
-export type { Metadata, RequirementNode, RequirementsFile, } from '../schema/index.js';
+export type { Metadata, RequirementNode, RequirementsFile, } from "../schema/index.js";
 /**
  * Flattened requirement for search results
  */

package/dist/push/core.d.ts

@@ -9,7 +9,7 @@
  * - Executing the push
  * - Updating local files with document IDs and timestamps
  */
-import type { Metadata } from '../schema/index.js';
+import type { Metadata } from "../schema/index.js";
 export interface PushCredentials {
     projectId: string;
     projectSecret: string;
@@ -41,7 +41,7 @@ export interface CloudDocumentMetadata {
  */
 export interface DryRunResultItem {
     dryRun: true;
-    action: 'create' | 'update' | 'not_found' | 'invalid';
+    action: "create" | "update" | "not_found" | "invalid";
     documentId?: string;
     title?: string;
     warning?: string;

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