@popoverai/dotrequirements 0.23.0 → 0.24.1

package/dist/{mcp → requirements}/grep.js

@@ -1,12 +1,12 @@
-import { execFile } from 'child_process';
-import { promisify } from 'util';
+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']);
+        await execFileAsync("rg", ["--version"]);
         return true;
     }
     catch {
@@ -21,7 +21,7 @@ async function hasRipgrep() {
 export async function findTestsForRequirement(workspaceRoot, requirementId) {
     const useRg = await hasRipgrep();
     // Escape special regex characters in the ID
-    const escapedId = requirementId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escapedId = requirementId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     // Pattern to match requirement('ID'), requirement("ID"), or requirement(`ID`)
     const pattern = `requirement\\s*\\(\\s*['"\`]${escapedId}`;
     try {
@@ -29,17 +29,39 @@ export async function findTestsForRequirement(workspaceRoot, requirementId) {
         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
+            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
+            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 (error) {
+    catch {
         // Grep returns exit code 1 when no matches found
         return [];
     }
@@ -48,11 +70,11 @@ export async function findTestsForRequirement(workspaceRoot, requirementId) {
  * 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('fs');
-    const pathModule = await import('path');
+    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)
@@ -60,32 +82,34 @@ export async function findRequirementsInFile(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 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 code = fs.readFileSync(resolvedPath, "utf-8");
         const ast = parse(code, {
-            sourceType: 'module',
-            plugins: ['typescript', 'jsx'],
+            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') {
+        if (typeof traverseFunc !== "function") {
             traverseFunc = traverseFunc.default;
         }
-        if (typeof traverseFunc !== 'function') {
+        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') {
+                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)
@@ -98,7 +122,7 @@ export async function findRequirementsInFile(filePath) {
                                     line: loc.start.line,
                                     column: loc.start.column + 1, // 1-indexed
                                     requirementId,
-                                    context: code.split('\n')[loc.start.line - 1] || '',
+                                    context: code.split("\n")[loc.start.line - 1] || "",
                                 });
                             }
                         }
@@ -108,7 +132,7 @@ export async function findRequirementsInFile(filePath) {
         });
         return results;
     }
-    catch (error) {
+    catch {
         return [];
     }
 }
@@ -125,14 +149,36 @@ export async function findAllTestReferences(workspaceRoot) {
         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
+            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
+            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);
+        return parseGrepOutput(output, "", useRg);
     }
     catch {
         return [];
@@ -143,7 +189,7 @@ export async function findAllTestReferences(workspaceRoot) {
  */
 function parseGrepOutput(output, expectedId, isRipgrep, singleFilePath) {
     const results = [];
-    const lines = output.trim().split('\n').filter(Boolean);
+    const lines = output.trim().split("\n").filter(Boolean);
     for (const line of lines) {
         let match;
         let file;
@@ -200,41 +246,43 @@ function parseGrepOutput(output, expectedId, isRipgrep, singleFilePath) {
  * 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('fs');
+    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}', {
+    const testFiles = await glob("**/*.{test,spec}.{js,jsx,ts,tsx}", {
         cwd: workspaceRoot,
         absolute: true,
-        ignore: ['**/node_modules/**', '**/dist/**', '**/build/**'],
+        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 code = fs.readFileSync(file, "utf-8");
             const ast = parse(code, {
-                sourceType: 'module',
-                plugins: ['typescript', 'jsx'],
+                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') {
+            if (typeof traverseFunc !== "function") {
                 traverseFunc = traverseFunc.default;
             }
-            if (typeof traverseFunc !== 'function') {
+            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') {
+                    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) {
@@ -246,14 +294,11 @@ export async function getReferencedRequirementIds(workspaceRoot) {
                 },
             });
         }
-        catch (error) {
-            // Skip unparseable files
-            continue;
-        }
+        catch { }
     }
     // Extract root IDs by removing the path suffix (everything after the first dot)
-    const rootIds = allRequirementIds.map(id => {
-        const dotIndex = id.indexOf('.');
+    const rootIds = allRequirementIds.map((id) => {
+        const dotIndex = id.indexOf(".");
         return dotIndex > 0 ? id.substring(0, dotIndex) : id;
     });
     return new Set(rootIds);

package/dist/{mcp/requirements.d.ts → requirements/index.d.ts}

@@ -1,5 +1,16 @@
-import { type RequirementNode, type Metadata } from '../schema/index.js';
-import type { FlattenedRequirement } from './types.js';
+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
  */
@@ -13,6 +24,11 @@ export interface ParsedRequirementsFile {
  * 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
  */
@@ -54,4 +70,4 @@ export declare function filterRequirementsByKeys(fileContents: string, keys: str
  * Format a requirement tree for display
  */
 export declare function formatRequirementTree(requirements: FlattenedRequirement[]): string;
-//# sourceMappingURL=requirements.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/{mcp/requirements.js → requirements/index.js}

@@ -1,30 +1,50 @@
-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, globSync } from "glob";
+import { buildRequirementMarkdown, getAllRequirements, parseRequirementsFile, parseRequirementsFromFile, } from "../schema/index.js";
+/**
+ * Glob pattern matching *.requirements.md files.
+ */
+const REQUIREMENTS_FILE_PATTERN = "**/*.requirements.md";
+/**
+ * Directories ignored when discovering requirements files.
+ * Shared between async and sync discovery so the two never drift.
+ */
+const REQUIREMENTS_IGNORE_PATTERNS = [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.git/**",
+    "**/build/**",
+    // Exclude example and test fixture directories
+    "**/example/**",
+    "**/examples/**",
+    "**/__tests__/**",
+    "**/fixtures/**",
+    "**/.fixtures/**",
+];
 /**
  * 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 matches = await glob(pattern, {
+    const matches = await glob(REQUIREMENTS_FILE_PATTERN, {
         cwd: workspaceRoot,
-        ignore: [
-            '**/node_modules/**',
-            '**/dist/**',
-            '**/.git/**',
-            '**/build/**',
-            // Exclude example and test fixture directories
-            '**/example/**',
-            '**/examples/**',
-            '**/__tests__/**',
-            '**/fixtures/**',
-            '**/.fixtures/**',
-        ],
+        ignore: REQUIREMENTS_IGNORE_PATTERNS,
         dot: true, // Include dotfiles/dotdirs like .requirements/
     });
-    return matches.map(m => path.join(workspaceRoot, m));
+    return matches.map((m) => path.join(workspaceRoot, m));
+}
+/**
+ * Synchronous variant of {@link findRequirementsFiles}. Used by code paths
+ * that can't await (e.g. the test-harness lookup-cache builder).
+ */
+export function findRequirementsFilesSync(workspaceRoot) {
+    const matches = globSync(REQUIREMENTS_FILE_PATTERN, {
+        cwd: workspaceRoot,
+        ignore: REQUIREMENTS_IGNORE_PATTERNS,
+        dot: true,
+    });
+    return matches.map((m) => path.join(workspaceRoot, m));
 }
 /**
  * Load all requirements from the workspace
@@ -56,9 +76,8 @@ 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('.');
         results.push({
             id: req.id,
             rootId: rootId,
@@ -76,7 +95,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 +113,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 +140,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 +156,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 +169,6 @@ export function formatRequirementTree(requirements) {
         }
         return 0;
     });
-    return sorted.map(formatRequirement).join('\n');
+    return sorted.map(formatRequirement).join("\n");
 }
-//# sourceMappingURL=requirements.js.map
+//# sourceMappingURL=index.js.map

package/dist/requirements/style-guide.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Style-guide template generator. Produces the markdown document that both
+ * the MCP `create_requirement_document` tool and the CLI
+ * `dotreq create-requirement-document` verb return.
+ *
+ * The output is a full ready-to-paste-into-a-PR markdown document that
+ * describes the requirements format, embeds a worked example, and includes
+ * style principles for writing requirements and tests. Discovered label /
+ * key patterns from the calling workspace and (optional) project-owner-
+ * supplied custom guidance are interpolated into the body.
+ *
+ * If the project has a `.requirements/STYLE.md`, callers can pass its
+ * contents via `localStyleGuide` to use that body in place of the bundled
+ * defaults. See {@link readLocalStyleGuide} for the lookup helper.
+ */
+import type { FlattenedRequirement } from "./index.js";
+/**
+ * Conventional location of a project's STYLE.md, relative to the workspace
+ * root. Exported so callers (init, push/pull, tests) can reference one place.
+ */
+export declare const STYLE_MD_PATH = ".requirements/STYLE.md";
+export interface GenerateStyleGuideParams {
+    /** Flattened view of the workspace's existing requirements, used to
+     * surface label patterns and key-prefix patterns in the output. Pass
+     * an empty array when no requirements exist yet. */
+    requirements: FlattenedRequirement[];
+    /** Project-owner-supplied custom guidance (currently sourced from the
+     * cloud project's `requirementsStyleContext` field). Pass null/undefined
+     * to omit. */
+    customStyleGuidance?: string | null;
+    /** Suggested target path for the new file. Used only in the preamble
+     * and "Next Steps" section. Defaults to a generic example path. */
+    filePath?: string;
+    /** Project-local STYLE.md contents. When provided and non-empty, this
+     * body replaces the bundled default; callers can fetch it via
+     * {@link readLocalStyleGuide}. */
+    localStyleGuide?: string | null;
+}
+/**
+ * Read `.requirements/STYLE.md` if the workspace has one. Returns the file
+ * contents on success, `null` if the file is absent. Empty / whitespace-only
+ * files are treated as absent so the bundled defaults still apply.
+ */
+export declare function readLocalStyleGuide(workspaceRoot: string): string | null;
+/**
+ * Build the body of the bundled default style guide. This is the content
+ * that lives inside the "# Requirements File Template" preamble — the
+ * format syntax, key/label conventions, style principles, and example
+ * requirements — with discovered patterns and custom guidance interpolated.
+ *
+ * Exposed separately from {@link generateStyleGuide} so callers can:
+ * - scaffold `.requirements/STYLE.md` with the bundled defaults at init time
+ * - swap the body wholesale (via `localStyleGuide`) without losing the
+ *   wrapping preamble + "Next Steps" footer
+ */
+export declare function generateStyleGuideBody(params: Omit<GenerateStyleGuideParams, "filePath" | "localStyleGuide">): string;
+/**
+ * Build a complete style-guide document for the calling workspace.
+ * Returns a single markdown string suitable for printing to stdout or
+ * wrapping in an MCP text response.
+ *
+ * When `localStyleGuide` is provided and non-empty, that content replaces
+ * the bundled default body. The preamble and "Next Steps" footer are
+ * always applied.
+ */
+export declare function generateStyleGuide(params: GenerateStyleGuideParams): string;
+//# sourceMappingURL=style-guide.d.ts.map