@popoverai/dotrequirements 0.20.3 → 0.21.0

package/dist/cli.js

@@ -6,6 +6,9 @@ import { pullCommand } from './commands/pull.js';
 import { pushCommand } from './commands/push.js';
 import { testCommand } from './commands/test.js';
 import { browserTestCommand } from './commands/browsertest.js';
+import { prepareCommand } from './commands/prepare.js';
+import { finalizeCommand } from './commands/finalize.js';
+import { reportCommand } from './commands/report.js';
 import { mcpCommand } from './commands/mcp.js';
 import { mcpSetupCommand } from './commands/mcp-setup.js';
 import { loadEnvFile } from './utils/env.js';
@@ -75,7 +78,25 @@ program
     .command('browsertest <requirement-key> [url]')
     .description('Run browser-based acceptance test for a requirement')
     .option('--json', 'Output results as JSON')
+    .option('--useAgent', 'Encourage Claude to use the Agent tool for multi-step tasks')
     .action(wrapCommand(browserTestCommand));
+program
+    .command('prepare')
+    .description('Parse requirements and build lookup cache for multi-language test tracking')
+    .option('-q, --quiet', 'Suppress output (for scripting)')
+    .action(wrapCommand(prepareCommand));
+program
+    .command('finalize')
+    .description('Aggregate test tracking data and generate coverage report')
+    .option('--push', 'Push coverage to DotRequirements Cloud')
+    .option('-q, --quiet', 'Output only coverage percentage (for scripting)')
+    .action(wrapCommand(finalizeCommand));
+program
+    .command('report')
+    .description('Display coverage report from most recent test run')
+    .option('-f, --format <format>', 'Output format: console, json, markdown', 'console')
+    .option('-r, --requirement <id>', 'Filter to specific requirement and its children')
+    .action(wrapCommand(reportCommand));
 program
     .command('mcp')
     .description('Start the MCP (Model Context Protocol) server for AI assistant integration')

package/dist/commands/browsertest.d.ts

@@ -1,5 +1,6 @@
 interface BrowserTestOptions {
     json?: boolean;
+    useAgent?: boolean;
 }
 export declare function browserTestCommand(requirementKey: string, url: string | undefined, options: BrowserTestOptions): Promise<void>;
 export {};

package/dist/commands/browsertest.js

@@ -82,7 +82,7 @@ export async function browserTestCommand(requirementKey, url, options) {
         console.log(`Testing ${requirementKey} against ${targetURL}...\n`);
     }
     try {
-        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
+        const { stdout } = await execFileAsync('npx', ['@popoverai/browser-automation', 'test', ...(options.useAgent ? ['--useAgent'] : []), targetURL, ...assertions], { env, maxBuffer: 10 * 1024 * 1024 });
         // 9. Parse results
         let results;
         try {

package/dist/commands/finalize.d.ts

@@ -0,0 +1,7 @@
+interface FinalizeOptions {
+    push?: boolean;
+    quiet?: boolean;
+}
+export declare function finalizeCommand(options: FinalizeOptions): Promise<void>;
+export {};
+//# sourceMappingURL=finalize.d.ts.map

package/dist/commands/finalize.js

@@ -0,0 +1,40 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { finalize } from '../harness/finalize.js';
+import { findRequirementsDir, isCacheStale } from '../harness/cache.js';
+import { findProjectRoot } from '../utils/project-settings.js';
+export async function finalizeCommand(options) {
+    // Warn if cache is stale before finalizing
+    if (!options.quiet) {
+        const projectRoot = findProjectRoot(process.cwd());
+        if (projectRoot) {
+            const requirementsDir = findRequirementsDir(projectRoot);
+            if (requirementsDir) {
+                const lookupPath = path.join(requirementsDir, '.cache', 'lookup.json');
+                try {
+                    const cacheStat = fs.statSync(lookupPath);
+                    if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+                        console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements prepare" to rebuild.\n');
+                    }
+                }
+                catch {
+                    // Ignore — finalize will handle missing cache
+                }
+            }
+        }
+    }
+    const result = await finalize({
+        cwd: process.cwd(),
+        reportToCloud: options.push ?? false,
+        cleanup: true,
+        showSummary: !options.quiet,
+        showTestedList: true,
+        showUntestedList: true,
+        showCloudStatus: !options.quiet,
+    });
+    if (options.quiet) {
+        // In quiet mode, just output the coverage percent for scripting
+        console.log(result.coveragePercent.toFixed(1));
+    }
+}
+//# sourceMappingURL=finalize.js.map

package/dist/commands/prepare.d.ts

@@ -0,0 +1,6 @@
+interface PrepareOptions {
+    quiet?: boolean;
+}
+export declare function prepareCommand(options: PrepareOptions): Promise<void>;
+export {};
+//# sourceMappingURL=prepare.d.ts.map

package/dist/commands/prepare.js

@@ -0,0 +1,20 @@
+import { prepare } from '../harness/prepare.js';
+export async function prepareCommand(options) {
+    const result = prepare({
+        cwd: process.cwd(),
+        logWarnings: !options.quiet,
+    });
+    if (!options.quiet) {
+        console.log(`Parsed ${result.filesProcessed} file(s), loaded ${result.requirementsLoaded} requirement(s) into cache.`);
+        if (result.parseErrors.length > 0) {
+            console.log(`\n⚠️  ${result.parseErrors.length} file(s) had parse errors (skipped):`);
+            for (const err of result.parseErrors) {
+                console.log(`  - ${err.file}: ${err.error}`);
+            }
+        }
+        console.log('\nCache written to .requirements/.cache/lookup.json');
+        console.log('Tracking initialized at .requirements/.cache/tracking.jsonl');
+        console.log('\nRun your tests, then run "dotrequirements finalize" to generate coverage report.');
+    }
+}
+//# sourceMappingURL=prepare.js.map

package/dist/commands/report.d.ts

@@ -0,0 +1,7 @@
+interface ReportOptions {
+    format?: 'console' | 'json' | 'markdown';
+    requirement?: string;
+}
+export declare function reportCommand(options: ReportOptions): Promise<void>;
+export {};
+//# sourceMappingURL=report.d.ts.map

package/dist/commands/report.js

@@ -0,0 +1,152 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { findProjectRoot } from '../utils/project-settings.js';
+import { findRequirementsDir, readTrackingEntries, isCacheStale, } from '../harness/cache.js';
+function buildCoverageEntries(lookup, entries, filterKey) {
+    // Aggregate tracking by key
+    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)) {
+        // Skip alias entries to avoid double-counting
+        if (req.isAlias)
+            continue;
+        // Filter if requested
+        if (filterKey && key !== filterKey && !key.startsWith(filterKey + '.')) {
+            continue;
+        }
+        // Collect locations from both the numeric key and any alias keys that map to the same id
+        const locations = new Set();
+        const keyLocations = locationsByKey.get(key);
+        if (keyLocations)
+            keyLocations.forEach(l => locations.add(l));
+        // Also check if tracking data was written using a label path
+        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;
+}
+function formatConsole(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    const pct = total > 0 ? ((tested / total) * 100).toFixed(1) : '0.0';
+    let out = `\n=== Requirements Coverage Report ===\n`;
+    out += `\nTotal: ${total} | Tested: ${tested} | Untested: ${total - tested} | Coverage: ${pct}%\n`;
+    const testedEntries = coverage.filter(c => c.tested);
+    if (testedEntries.length > 0) {
+        out += '\n✓ Tested:\n';
+        for (const c of testedEntries) {
+            const preview = c.content.length > 60 ? c.content.substring(0, 60) + '...' : c.content;
+            out += `  ${c.key}: ${preview}\n`;
+            for (const loc of c.locations) {
+                out += `    ← ${loc}\n`;
+            }
+        }
+    }
+    const untestedEntries = coverage.filter(c => !c.tested);
+    if (untestedEntries.length > 0) {
+        out += '\n✗ Untested:\n';
+        for (const c of untestedEntries) {
+            const preview = c.content.length > 60 ? c.content.substring(0, 60) + '...' : c.content;
+            out += `  ${c.key}: ${preview}\n`;
+        }
+    }
+    out += '\n====================================\n';
+    return out;
+}
+function formatJson(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    return JSON.stringify({
+        summary: {
+            total,
+            tested,
+            untested: total - tested,
+            coveragePercent: total > 0 ? parseFloat(((tested / total) * 100).toFixed(1)) : 0,
+        },
+        requirements: coverage,
+    }, null, 2);
+}
+function formatMarkdown(coverage) {
+    const tested = coverage.filter(c => c.tested).length;
+    const total = coverage.length;
+    const pct = total > 0 ? ((tested / total) * 100).toFixed(1) : '0.0';
+    let out = `# Requirements Coverage Report\n\n`;
+    out += `**Coverage:** ${tested}/${total} (${pct}%)\n\n`;
+    out += `| Requirement | Status | Locations |\n`;
+    out += `|---|---|---|\n`;
+    for (const c of coverage) {
+        const status = c.tested ? '✓' : '✗';
+        const locs = c.locations.join(', ') || '-';
+        const preview = c.content.length > 40 ? c.content.substring(0, 40) + '...' : c.content;
+        out += `| ${c.key}: ${preview} | ${status} | ${locs} |\n`;
+    }
+    return out;
+}
+export async function reportCommand(options) {
+    const projectRoot = findProjectRoot(process.cwd());
+    if (!projectRoot) {
+        throw new Error('Could not find .requirements directory. Run "dotrequirements init" to initialize your project.');
+    }
+    const requirementsDir = findRequirementsDir(projectRoot);
+    const cacheDir = path.join(requirementsDir, '.cache');
+    const lookupPath = path.join(cacheDir, 'lookup.json');
+    if (!fs.existsSync(lookupPath)) {
+        throw new Error('No lookup cache found. Run "dotrequirements prepare" first to build the cache.');
+    }
+    // Read lookup cache
+    const lookupContent = fs.readFileSync(lookupPath, 'utf-8');
+    const lookup = JSON.parse(lookupContent);
+    // Warn if cache is stale (requirements changed since last prepare)
+    try {
+        const cacheStat = fs.statSync(lookupPath);
+        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+            console.error('Warning: Cache may be stale — requirements have changed since last prepare. Run "dotrequirements prepare" to rebuild.\n');
+        }
+    }
+    catch {
+        // Ignore stat errors
+    }
+    // Read tracking entries
+    const trackingPath = path.join(cacheDir, 'tracking.jsonl');
+    const trackingExists = fs.existsSync(trackingPath);
+    const entries = readTrackingEntries(requirementsDir);
+    if (!trackingExists) {
+        console.error('Warning: No tracking data found. Run your tests first, or run "dotrequirements prepare" to start a new tracking session.\n');
+    }
+    else if (entries.length === 0) {
+        console.error('Warning: Tracking file is empty — no requirements were tracked during tests.\n');
+    }
+    const coverage = buildCoverageEntries(lookup, entries, options.requirement);
+    const format = options.format || 'console';
+    switch (format) {
+        case 'json':
+            console.log(formatJson(coverage));
+            break;
+        case 'markdown':
+            console.log(formatMarkdown(coverage));
+            break;
+        case 'console':
+        default:
+            console.log(formatConsole(coverage));
+            break;
+    }
+}
+//# sourceMappingURL=report.js.map

package/dist/harness/cache.d.ts

@@ -32,6 +32,8 @@ export interface LookupCache {
         id: string;
         label: string;
         content: string;
+        /** True if this key is a label-path alias for another entry (e.g. "REQ.given" → "REQ.0") */
+        isAlias?: boolean;
     }>;
 }
 /**
@@ -69,6 +71,11 @@ export declare function findRequirementsFiles(projectRoot: string): string[];
  * Write the lookup cache with all pre-parsed requirements
  */
 export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
+/**
+ * Check if any source file is newer than the cache file.
+ * Returns true if cache is stale and should be invalidated.
+ */
+export declare function isCacheStale(requirementsDir: string, cacheMtime: number): boolean;
 /**
  * Read the lookup cache, returning null if not found, invalid, or stale.
  * Cache is considered stale if any .requirements.md file is newer than the cache.

package/dist/harness/cache.js

@@ -84,19 +84,37 @@ export function writeLookupCache(requirementsDir, requirements) {
         generatedAt: new Date().toISOString(),
         requirements: {},
     };
-    // Recursively flatten the requirement trees
-    function flatten(node) {
-        lookup.requirements[node.id] = {
+    // Recursively flatten the requirement trees, adding both numeric and label paths
+    function flatten(node, labelPath) {
+        const entry = {
             id: node.id,
             label: node.label,
             content: node.content,
         };
+        // Always add the numeric path (e.g. "AUTH-LOGIN.0")
+        lookup.requirements[node.id] = entry;
+        // Add label path as an alias if it differs from the numeric path
+        if (labelPath && labelPath !== node.id) {
+            lookup.requirements[labelPath] = { ...entry, isAlias: true };
+        }
+        // Track label occurrences for disambiguation (e.g. given#0, given#1)
+        const labelCounts = new Map();
         for (const child of node.children) {
-            flatten(child);
+            let childLabelPath = null;
+            if (child.label && child.label !== 'requirementHeader') {
+                const normalizedLabel = child.label.toLowerCase().replace(/\s+/g, '-');
+                const count = labelCounts.get(normalizedLabel) || 0;
+                labelCounts.set(normalizedLabel, count + 1);
+                const parentPath = labelPath || node.id;
+                childLabelPath = count === 0
+                    ? `${parentPath}.${normalizedLabel}`
+                    : `${parentPath}.${normalizedLabel}#${count}`;
+            }
+            flatten(child, childLabelPath);
         }
     }
     for (const req of requirements) {
-        flatten(req);
+        flatten(req, null);
     }
     fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
 }
@@ -104,7 +122,7 @@ export function writeLookupCache(requirementsDir, requirements) {
  * Check if any source file is newer than the cache file.
  * Returns true if cache is stale and should be invalidated.
  */
-function isCacheStale(requirementsDir, cacheMtime) {
+export function isCacheStale(requirementsDir, cacheMtime) {
     const projectRoot = path.dirname(requirementsDir);
     const sourceFiles = findRequirementsFiles(projectRoot);
     for (const file of sourceFiles) {

package/dist/harness/finalize.js

@@ -47,7 +47,7 @@ function getCurrentBranch(cwd) {
  */
 function printLocalReport(testedKeys, lookup, options) {
     const { showSummary, showTestedList, showUntestedList } = options;
-    const allKeys = lookup ? Object.keys(lookup.requirements) : [];
+    const allKeys = lookup ? Object.keys(lookup.requirements).filter(k => !lookup.requirements[k].isAlias) : [];
     const untestedKeys = allKeys.filter(key => !testedKeys.includes(key));
     const total = allKeys.length;
     const tested = testedKeys.length;
@@ -278,10 +278,26 @@ export async function finalize(options = {}) {
     const entries = readTrackingEntries(requirementsDir);
     // Aggregate by requirement key
     const aggregated = aggregateEntries(entries);
-    const testedKeys = Array.from(aggregated.keys());
     // Read lookup cache for report
     const lookup = readLookupCache(requirementsDir);
-    const totalRequirements = lookup ? Object.keys(lookup.requirements).length : 0;
+    // Normalize alias keys to canonical numeric keys.
+    // Non-JS consumers may write label paths (e.g. "AUTH-LOGIN.given") to tracking.jsonl.
+    // We resolve those to their canonical numeric key (e.g. "AUTH-LOGIN.0") so that
+    // coverage counting, display, and cloud reporting all use consistent keys.
+    if (lookup) {
+        for (const [key, trackingEntries] of Array.from(aggregated.entries())) {
+            const entry = lookup.requirements[key];
+            if (entry?.isAlias) {
+                const canonicalKey = entry.id;
+                // Merge into canonical key's entries
+                const existing = aggregated.get(canonicalKey) || [];
+                aggregated.set(canonicalKey, [...existing, ...trackingEntries]);
+                aggregated.delete(key);
+            }
+        }
+    }
+    const testedKeys = Array.from(aggregated.keys());
+    const totalRequirements = lookup ? Object.keys(lookup.requirements).filter(k => !lookup.requirements[k].isAlias).length : 0;
     const coveragePercent = totalRequirements > 0
         ? (testedKeys.length / totalRequirements) * 100
         : 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.20.3",
+  "version": "0.21.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {