@popoverai/dotrequirements 0.16.0 → 0.17.1

package/dist/mcp/handlers/search.js

@@ -0,0 +1,60 @@
+/**
+ * search_requirements handler
+ *
+ * Searches requirements by text or regex query across IDs, content, and labels.
+ * Returns matching requirements with their full tree context.
+ */
+import { textResponse, errorResponse } from './types.js';
+import { searchRequirements, getRequirementTree, formatRequirementTree, } from '../requirements.js';
+/**
+ * Handler for search_requirements tool
+ *
+ * Requirements covered:
+ * - MCP-SEARCH-1.0: Query matches requirement ID
+ * - MCP-SEARCH-1.1: Query matches requirement content
+ * - MCP-SEARCH-1.2: Query matches requirement label
+ * - MCP-SEARCH-1.3: useRegex interprets query as case-insensitive regex
+ * - MCP-SEARCH-1.4: Invalid regex returns error
+ * - MCP-SEARCH-1.5: No matches returns informative message
+ * - MCP-SEARCH-1.6: Nested match returns root requirement
+ * - MCP-SEARCH-1.7: Results include full tree as code block
+ */
+export async function handleSearchRequirements(args, context) {
+    const { query, useRegex = false, projectId } = args;
+    const requirements = await context.getRequirements(projectId);
+    let results;
+    if (useRegex) {
+        // MCP-SEARCH-1.3: Interpret query as case-insensitive regex
+        // MCP-SEARCH-1.4: Return error for invalid regex
+        try {
+            const regex = new RegExp(query, 'i');
+            results = requirements.filter((r) => regex.test(r.id) ||
+                regex.test(r.content) ||
+                regex.test(r.label));
+        }
+        catch (error) {
+            return errorResponse(`Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    else {
+        // MCP-SEARCH-1.0, MCP-SEARCH-1.1, MCP-SEARCH-1.2: Text search across ID, content, label
+        results = searchRequirements(requirements, query);
+    }
+    // MCP-SEARCH-1.6: Collect unique root IDs from all matches (nested matches bubble up to their root)
+    const matchedRootIds = new Set(results.map((r) => r.rootId));
+    const rootResults = requirements.filter((r) => r.path.length === 0 && matchedRootIds.has(r.rootId));
+    // MCP-SEARCH-1.5: No matches returns informative message
+    if (rootResults.length === 0) {
+        return textResponse(`No requirements found matching "${query}"${useRegex ? ' (regex)' : ''}`);
+    }
+    // MCP-SEARCH-1.7: Each result includes full tree as code block
+    const formatted = rootResults
+        .map((r) => {
+        const tree = getRequirementTree(requirements, r.id);
+        const treeFormatted = formatRequirementTree(tree);
+        return `**${r.id}** (${r.label})\n${r.content}\n_Source: ${r.documentTitle}_\n\n\`\`\`\n${treeFormatted}\n\`\`\``;
+    })
+        .join('\n\n---\n\n');
+    return textResponse(`Found ${rootResults.length} requirement(s) matching "${query}"${useRegex ? ' (regex)' : ''}:\n\n${formatted}`);
+}
+//# sourceMappingURL=search.js.map

package/dist/mcp/handlers/test-mapping.d.ts

@@ -0,0 +1,39 @@
+/**
+ * get_requirements_by_test and get_tests_by_requirement handlers
+ *
+ * Maps between test files and requirements in both directions.
+ */
+import type { HandlerContext, ToolResponse } from './types.js';
+/**
+ * Arguments for get_requirements_by_test tool
+ */
+export interface GetRequirementsByTestArgs {
+    testFile: string;
+    projectId?: string;
+}
+/**
+ * Handler for get_requirements_by_test tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-1.0: The response lists each requirement() call found in the test file
+ * - MCP-MAP-1.1: For each reference, the requirement content and line number are shown
+ * - MCP-MAP-1.2: When the test file does not exist, an error is returned
+ */
+export declare function handleGetRequirementsByTest(args: GetRequirementsByTestArgs, context: HandlerContext): Promise<ToolResponse>;
+/**
+ * Arguments for get_tests_by_requirement tool
+ */
+export interface GetTestsByRequirementArgs {
+    requirementsFile: string;
+    projectId?: string;
+}
+/**
+ * Handler for get_tests_by_requirement tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-2.0: The response lists which requirements have test references
+ * - MCP-MAP-2.1: For each covered requirement, the test file and line number are shown
+ * - MCP-MAP-2.2: Requirements without test references are listed separately
+ */
+export declare function handleGetTestsByRequirement(args: GetTestsByRequirementArgs, context: HandlerContext): Promise<ToolResponse>;
+//# sourceMappingURL=test-mapping.d.ts.map

package/dist/mcp/handlers/test-mapping.js

@@ -0,0 +1,133 @@
+/**
+ * get_requirements_by_test and get_tests_by_requirement handlers
+ *
+ * Maps between test files and requirements in both directions.
+ */
+import { existsSync } from 'fs';
+import { resolve, relative } from 'path';
+import { textResponse, errorResponse } from './types.js';
+import { getRequirementById } from '../requirements.js';
+import { findRequirementsInFile, findAllTestReferences, } from '../grep.js';
+/**
+ * Handler for get_requirements_by_test tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-1.0: The response lists each requirement() call found in the test file
+ * - MCP-MAP-1.1: For each reference, the requirement content and line number are shown
+ * - MCP-MAP-1.2: When the test file does not exist, an error is returned
+ */
+export async function handleGetRequirementsByTest(args, context) {
+    const { testFile, projectId } = args;
+    // MCP-MAP-1.2: Check if file exists before processing
+    const fullPath = resolve(context.workspaceRoot, testFile);
+    if (!existsSync(fullPath)) {
+        return errorResponse(`Test file not found: ${testFile}`);
+    }
+    const requirements = await context.getRequirements(projectId);
+    // MCP-MAP-1.0: Find all requirement references in the test file
+    const refs = await findRequirementsInFile(testFile);
+    if (refs.length === 0) {
+        return textResponse(`No requirement references found in "${testFile}"`);
+    }
+    // MCP-MAP-1.1: For each reference, get the requirement content and show line number
+    const entries = refs.map((ref) => {
+        const req = getRequirementById(requirements, ref.requirementId);
+        const reqContent = req
+            ? `**${req.label}:** ${req.content}`
+            : `(requirement not found)`;
+        return `**Line ${ref.line}:** \`${ref.requirementId}\` - ${reqContent}`;
+    });
+    return textResponse(`Requirements referenced in "${testFile}":\n\n${entries.join('\n\n')}`);
+}
+/**
+ * Handler for get_tests_by_requirement tool
+ *
+ * Requirements covered:
+ * - MCP-MAP-2.0: The response lists which requirements have test references
+ * - MCP-MAP-2.1: For each covered requirement, the test file and line number are shown
+ * - MCP-MAP-2.2: Requirements without test references are listed separately
+ */
+export async function handleGetTestsByRequirement(args, context) {
+    const { requirementsFile, projectId } = args;
+    const { workspaceRoot } = context;
+    const fullPath = resolve(workspaceRoot, requirementsFile);
+    // Verify file exists
+    if (!existsSync(fullPath)) {
+        return errorResponse(`Requirements file not found: ${requirementsFile}`);
+    }
+    // Verify it's a requirements file
+    if (!requirementsFile.endsWith('.requirements.md')) {
+        return errorResponse(`File must be a requirements file: *.requirements.md`);
+    }
+    // Load all requirements from this file
+    const requirements = await context.getRequirements(projectId);
+    const fileRequirements = requirements.filter(req => resolve(workspaceRoot, req.sourceFile) === fullPath);
+    if (fileRequirements.length === 0) {
+        return textResponse(`No requirements found in "${requirementsFile}"`);
+    }
+    // Get unique root requirement IDs from this file
+    const rootIds = new Set(fileRequirements.map(req => req.rootId));
+    // Find all test references in the workspace
+    const allTestRefs = await findAllTestReferences(workspaceRoot);
+    // Build coverage map: requirement ID -> list of test references
+    const coverageMap = new Map();
+    for (const ref of allTestRefs) {
+        if (!coverageMap.has(ref.requirementId)) {
+            coverageMap.set(ref.requirementId, []);
+        }
+        coverageMap.get(ref.requirementId).push(ref);
+    }
+    // MCP-MAP-2.0: Categorize requirements as covered or not covered
+    const covered = [];
+    const notCovered = [];
+    for (const rootId of rootIds) {
+        // Check if this requirement ID or any of its children are referenced
+        const reqAndChildren = fileRequirements.filter(r => r.rootId === rootId);
+        const allIds = reqAndChildren.map(r => r.id);
+        const testsForThisReq = [];
+        for (const id of allIds) {
+            const refs = coverageMap.get(id);
+            if (refs) {
+                testsForThisReq.push(...refs);
+            }
+        }
+        if (testsForThisReq.length > 0) {
+            covered.push({ id: rootId, tests: testsForThisReq });
+        }
+        else {
+            notCovered.push(rootId);
+        }
+    }
+    // Format output
+    let output = `# Test Coverage for \`${requirementsFile}\`\n\n`;
+    // MCP-MAP-2.1: For each covered requirement, show test file and line number
+    if (covered.length > 0) {
+        output += `## Covered (${covered.length})\n\n`;
+        for (const { id, tests } of covered) {
+            // Group tests by file
+            const testsByFile = new Map();
+            for (const test of tests) {
+                if (!testsByFile.has(test.file)) {
+                    testsByFile.set(test.file, []);
+                }
+                testsByFile.get(test.file).push(test.line);
+            }
+            output += `- **${id}**: ${tests.length} test${tests.length === 1 ? '' : 's'}\n`;
+            for (const [file, lines] of testsByFile.entries()) {
+                const relPath = relative(workspaceRoot, file);
+                const lineList = lines.sort((a, b) => a - b).join(', ');
+                output += `  - \`${relPath}\` (lines ${lineList})\n`;
+            }
+        }
+        output += '\n';
+    }
+    // MCP-MAP-2.2: Requirements without test references are listed separately
+    if (notCovered.length > 0) {
+        output += `## Not Covered (${notCovered.length})\n\n`;
+        for (const id of notCovered) {
+            output += `- **${id}**: No tests found\n`;
+        }
+    }
+    return textResponse(output);
+}
+//# sourceMappingURL=test-mapping.js.map

package/dist/mcp/handlers/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Handler types for MCP tool handlers
+ *
+ * Each handler is a pure function that takes arguments and context,
+ * and returns an MCP tool response. This enables unit testing without
+ * the full MCP server infrastructure.
+ */
+import type { FlattenedRequirement } from '../types.js';
+import type { DotreqProject } from '../../utils/project-discovery.js';
+/**
+ * MCP tool response content item
+ */
+export interface ToolContentItem {
+    type: 'text';
+    text: string;
+}
+/**
+ * MCP tool response
+ *
+ * Compatible with MCP SDK's CallToolResult type.
+ * The index signature allows for SDK extensibility (e.g., _meta, task).
+ */
+export interface ToolResponse {
+    [key: string]: unknown;
+    content: ToolContentItem[];
+    isError?: boolean;
+}
+/**
+ * Context provided to all handlers
+ *
+ * This abstraction enables:
+ * - Unit testing with mock context
+ * - Dependency injection
+ * - Isolation from global state
+ */
+export interface HandlerContext {
+    /**
+     * Get flattened requirements for a project
+     * @param projectId - Optional project ID for multi-project scenarios
+     */
+    getRequirements: (projectId?: string) => Promise<FlattenedRequirement[]>;
+    /**
+     * Get project from discovery (path, credentials)
+     * @param projectId - Optional project ID for multi-project scenarios
+     */
+    getProjectFromDiscovery: (projectId?: string) => Promise<DotreqProject>;
+    /**
+     * Workspace root directory
+     */
+    workspaceRoot: string;
+    /**
+     * Project paths from environment variables (PROJ_* pattern)
+     */
+    projectPaths: Map<string, string>;
+    /**
+     * Environment variables (for debug_mcp_environment)
+     */
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Handler function signature
+ *
+ * All MCP tool handlers implement this interface.
+ * The args parameter contains tool-specific arguments.
+ */
+export type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs, context: HandlerContext) => Promise<ToolResponse>;
+/**
+ * Helper to create a text response
+ */
+export declare function textResponse(text: string): ToolResponse;
+/**
+ * Helper to create an error response
+ */
+export declare function errorResponse(message: string): ToolResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/mcp/handlers/types.js

@@ -0,0 +1,25 @@
+/**
+ * Handler types for MCP tool handlers
+ *
+ * Each handler is a pure function that takes arguments and context,
+ * and returns an MCP tool response. This enables unit testing without
+ * the full MCP server infrastructure.
+ */
+/**
+ * Helper to create a text response
+ */
+export function textResponse(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Helper to create an error response
+ */
+export function errorResponse(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=types.js.map

package/dist/mcp/index.d.ts

@@ -1,3 +1,44 @@
 #!/usr/bin/env node
-export {};
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function invalidateCache(): void;
+export declare const server: Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        task?: {
+            [x: string]: unknown;
+            ttl?: number | null | undefined;
+            pollInterval?: number | undefined;
+        } | undefined;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            "io.modelcontextprotocol/related-task"?: {
+                [x: string]: unknown;
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        "io.modelcontextprotocol/related-task"?: {
+            [x: string]: unknown;
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
 //# sourceMappingURL=index.d.ts.map