@popoverai/dotrequirements 0.21.1 → 0.22.0

package/README.md

@@ -276,6 +276,14 @@ await finalize({ showTestedList: true }); // Include tested requirements
 await finalize({ showSummary: false, showUntestedList: false }); // Quiet mode
 ```
 
+**Attribution:** tag cloud coverage rows with the name of the framework that produced them:
+
+```typescript
+await finalize({ context: 'Vitest' });
+```
+
+The Coverage tab uses this label to show which tool produced each result. Any string works — useful when you have multiple test suites (`"Vitest — unit"`, `"Vitest — integration"`).
+
 By default, only untested requirements are shown. See the [test harness docs](https://docs.dotrequirements.io/tools/test-harness) for all options.
 
 ### Setup with Jest

package/dist/cli.js

@@ -90,6 +90,7 @@ program
     .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)')
+    .option('--context <label>', 'Attribution label identifying the reporter (e.g. "Vitest", "pytest")')
     .action(wrapCommand(finalizeCommand));
 program
     .command('report')

package/dist/commands/finalize.d.ts

@@ -1,6 +1,7 @@
 interface FinalizeOptions {
     push?: boolean;
     quiet?: boolean;
+    context?: string;
 }
 export declare function finalizeCommand(options: FinalizeOptions): Promise<void>;
 export {};

package/dist/commands/finalize.js

@@ -31,6 +31,7 @@ export async function finalizeCommand(options) {
         showTestedList: true,
         showUntestedList: true,
         showCloudStatus: !options.quiet,
+        context: options.context,
     });
     if (options.quiet) {
         // In quiet mode, just output the coverage percent for scripting

package/dist/harness/cache.d.ts

@@ -39,17 +39,22 @@ export interface LookupCache {
 /**
  * Structure of the coverage.json cache (for cloud deduplication)
  */
+/** Attribution tuple used for debounce keying (COVERAGE-DEBOUNCE-2). */
+export interface CoverageTuple {
+    requirementKey: string;
+    context?: string;
+    branch?: string;
+}
+export interface CoverageCacheEntry {
+    testRunId: string;
+    timestamp: number;
+    tuples: CoverageTuple[];
+    /** Legacy field retained for backward-compat reads of pre-attribution caches. */
+    requirementKeys?: string[];
+}
 export interface CoverageCache {
-    current: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
-    previous: {
-        testRunId: string;
-        timestamp: number;
-        requirementKeys: string[];
-    } | null;
+    current: CoverageCacheEntry | null;
+    previous: CoverageCacheEntry | null;
 }
 /**
  * Find the nearest .requirements directory by walking up from startDir
@@ -123,16 +128,16 @@ export declare function readTrackingEntries(requirementsDir: string): TrackingEn
  * Delete the tracking file after finalize
  */
 export declare function deleteTrackingFile(requirementsDir: string): void;
-/**
- * Read the coverage cache for cloud deduplication
- */
 export declare function readCoverageCache(requirementsDir: string): CoverageCache;
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export declare function updateCoverageCache(requirementsDir: string, testRunId: string, requirementKeys: string[]): void;
+export declare function updateCoverageCache(requirementsDir: string, testRunId: string, tuples: CoverageTuple[] | string[]): void;
+export declare const COVERAGE_DEBOUNCE_WINDOW_MS: number;
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export declare function needsReporting(requirementKey: string, cache: CoverageCache): boolean;
+export declare function needsReporting(tupleOrKey: CoverageTuple | string, cache: CoverageCache): boolean;
 //# sourceMappingURL=cache.d.ts.map

package/dist/harness/cache.js

@@ -288,6 +288,30 @@ export function deleteTrackingFile(requirementsDir) {
 /**
  * Read the coverage cache for cloud deduplication
  */
+/**
+ * Normalize a cache entry read from disk. Migrates legacy `requirementKeys`
+ * arrays into the tuple shape (context/branch undefined) so downstream code
+ * can treat both shapes uniformly.
+ */
+function normalizeEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    if (Array.isArray(raw.tuples)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.tuples,
+        };
+    }
+    if (Array.isArray(raw.requirementKeys)) {
+        return {
+            testRunId: raw.testRunId,
+            timestamp: raw.timestamp,
+            tuples: raw.requirementKeys.map((requirementKey) => ({ requirementKey })),
+        };
+    }
+    return null;
+}
 export function readCoverageCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
@@ -296,45 +320,58 @@ export function readCoverageCache(requirementsDir) {
     }
     try {
         const content = fs.readFileSync(coveragePath, 'utf-8');
-        return JSON.parse(content);
+        const raw = JSON.parse(content);
+        return {
+            current: normalizeEntry(raw?.current),
+            previous: normalizeEntry(raw?.previous),
+        };
     }
     catch {
         return { current: null, previous: null };
     }
 }
 /**
- * Update the coverage cache after reporting
+ * Update the coverage cache after reporting. Accepts either attribution tuples
+ * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
  */
-export function updateCoverageCache(requirementsDir, testRunId, requirementKeys) {
+export function updateCoverageCache(requirementsDir, testRunId, tuples) {
     const cacheDir = getCacheDir(requirementsDir, true);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    const normalized = tuples.map((t) => typeof t === 'string' ? { requirementKey: t } : t);
     const existing = readCoverageCache(requirementsDir);
     const newCache = {
         current: {
             testRunId,
             timestamp: Date.now(),
-            requirementKeys,
+            tuples: normalized,
         },
         previous: existing.current,
     };
     fs.writeFileSync(coveragePath, JSON.stringify(newCache, null, 2));
 }
+export const COVERAGE_DEBOUNCE_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours — must match server-side in testCoverage/mutations.ts
+function tuplesMatch(a, b) {
+    return (a.requirementKey === b.requirementKey &&
+        a.context === b.context &&
+        a.branch === b.branch);
+}
 /**
- * Check if a requirement needs reporting based on coverage cache
+ * Check if an attribution tuple needs reporting based on the coverage cache.
+ * Returns true if no matching tuple was reported within the debounce window.
  */
-export function needsReporting(requirementKey, cache) {
-    const STALENESS_THRESHOLD_MS = 4 * 60 * 60 * 1000; // 4 hours
+export function needsReporting(tupleOrKey, cache) {
+    const tuple = typeof tupleOrKey === 'string' ? { requirementKey: tupleOrKey } : tupleOrKey;
     // If no current run, everything needs reporting
     if (!cache.current) {
         return true;
     }
-    // If requirement wasn't in current run, it needs reporting
-    if (!cache.current.requirementKeys.includes(requirementKey)) {
+    // If the tuple wasn't in the current cached run, it needs reporting
+    if (!cache.current.tuples.some((t) => tuplesMatch(t, tuple))) {
         return true;
     }
     // If current run is stale (>4 hours old), needs reporting
     const age = Date.now() - cache.current.timestamp;
-    if (age > STALENESS_THRESHOLD_MS) {
+    if (age > COVERAGE_DEBOUNCE_WINDOW_MS) {
         return true;
     }
     // Otherwise, skip reporting (already reported recently)

package/dist/harness/finalize.d.ts

@@ -24,6 +24,11 @@ export interface FinalizeOptions {
     showUntestedList?: boolean;
     /** Whether to show cloud reporting status messages (defaults to true) */
     showCloudStatus?: boolean;
+    /**
+     * Attribution label identifying the reporter (e.g. "Vitest", "Jest", "pytest").
+     * When omitted, rows are recorded with context absent per COVERAGE-CONTEXT-1.2.
+     */
+    context?: string;
 }
 export interface FinalizeResult {
     /** Number of unique requirements exercised */

package/dist/harness/finalize.js

@@ -10,6 +10,7 @@
  * Implements: HARNESS-FINALIZE-1, HARNESS-FINALIZE-2, HARNESS-FINALIZE-3, HARNESS-FINALIZE-4
  */
 import { execSync } from 'child_process';
+import { randomUUID } from 'crypto';
 import { findRequirementsDir, findProjectRoot, getTestRunId, cleanupTestRunId, readTrackingEntries, deleteTrackingFile, readLookupCache, readCoverageCache, updateCoverageCache, needsReporting, } from './cache.js';
 import { getProjectInfo } from '../utils/project-settings.js';
 /**
@@ -40,6 +41,26 @@ function getCurrentBranch(cwd) {
         return 'unknown';
     }
 }
+/**
+ * Return the git-blame author email for a specific file:line, or undefined
+ * if unavailable (not a git repo, file untracked, git unavailable, etc.).
+ *
+ * COVERAGE-CONTEXT-2: "last reported by" attribution.
+ */
+function getLineAuthor(cwd, file, line) {
+    try {
+        const output = execSync(`git blame -L ${line},${line} --porcelain -- "${file}"`, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        const match = output.match(/^author-mail\s+<([^>]+)>/m);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Print local coverage report to console
  *
@@ -112,7 +133,7 @@ const CONVEX_URL = 'https://data.dotrequirements.io';
  * HARNESS-FINALIZE-2: Cloud reporting with error tolerance
  * HARNESS-FINALIZE-3: Coverage records include requirement, file, line, branch
  */
-async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus) {
+async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context) {
     try {
         // Get project info from .requirements/project-settings.json
         const projectInfo = getProjectInfo(projectRoot);
@@ -125,24 +146,34 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
         }
         const { projectId, projectSecret } = projectInfo.credentials;
         const requirementsDir = findRequirementsDir(projectRoot);
-        // Get all tracked requirement keys
+        const branch = getCurrentBranch(projectRoot);
+        // Build the full set of tuples for this run, one per tracked requirement
         const requirementKeys = Array.from(aggregated.keys());
-        // Use coverage cache for deduplication
+        const allTuples = requirementKeys.map((key) => ({
+            requirementKey: key,
+            context,
+            branch,
+        }));
+        // Local debounce (COVERAGE-DEBOUNCE-1): only report tuples not recently cached.
+        // Server-side debounce is a backstop (COVERAGE-DEBOUNCE-4) — this layer just
+        // prevents unnecessary HTTP calls.
         const coverageCache = readCoverageCache(requirementsDir);
-        const keysToReport = requirementKeys.filter(key => needsReporting(key, coverageCache));
-        if (keysToReport.length === 0) {
+        const tuplesToReport = allTuples.filter((tuple) => needsReporting(tuple, coverageCache));
+        if (tuplesToReport.length === 0) {
             if (showCloudStatus) {
                 console.log('\n✓ Coverage unchanged since last run (skipping cloud report)');
             }
-            // Still update the cache
-            updateCoverageCache(requirementsDir, testRunId, requirementKeys);
+            // Still update the cache so the window continues tracking
+            updateCoverageCache(requirementsDir, testRunId, allTuples);
             return { sent: false, count: 0 };
         }
-        const branch = getCurrentBranch(projectRoot);
+        // Deterministic runId for this finalize invocation (COVERAGE-CONTEXT-4)
+        const runId = randomUUID();
+        // Cache git-blame lookups per file:line to avoid redundant subprocess spawns
+        const userCache = new Map();
         // Build coverage payload
-        // HARNESS-FINALIZE-3: Include requirement path, test file, line, branch
-        const coverage = keysToReport.map(key => {
-            const entries = aggregated.get(key);
+        const coverage = tuplesToReport.map((tuple) => {
+            const entries = aggregated.get(tuple.requirementKey);
             // Use the first access location
             const firstEntry = entries[0];
             const location = firstEntry.callerLocation;
@@ -159,10 +190,23 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                     testFile = location;
                 }
             }
+            // COVERAGE-CONTEXT-2: git blame on the requirement() call line
+            let user;
+            if (testFile && testLine !== undefined) {
+                const cacheKey = `${testFile}:${testLine}`;
+                if (userCache.has(cacheKey)) {
+                    user = userCache.get(cacheKey);
+                }
+                else {
+                    user = getLineAuthor(projectRoot, testFile, testLine);
+                    userCache.set(cacheKey, user);
+                }
+            }
             return {
-                requirementKey: key,
+                requirementKey: tuple.requirementKey,
                 testFile,
                 testLine,
+                user,
             };
         });
         // Send to Convex
@@ -185,6 +229,8 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                         slug: projectId,
                     },
                     branch,
+                    context,
+                    runId,
                     coverage,
                 },
                 format: 'json',
@@ -218,11 +264,11 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
             }
         }
         if (showCloudStatus) {
-            console.log(`\n✓ Reported ${keysToReport.length} requirement(s) to cloud (branch: ${branch})`);
+            console.log(`\n✓ Reported ${tuplesToReport.length} requirement(s) to cloud (branch: ${branch})`);
         }
-        // Update coverage cache
-        updateCoverageCache(requirementsDir, testRunId, requirementKeys);
-        return { sent: true, count: keysToReport.length };
+        // Update coverage cache with the full tuple set (includes those not reported this run)
+        updateCoverageCache(requirementsDir, testRunId, allTuples);
+        return { sent: true, count: tuplesToReport.length };
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -244,7 +290,7 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
  * HARNESS-FINALIZE-4: Finalize cleans up after itself
  */
 export async function finalize(options = {}) {
-    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, } = options;
+    const { cwd = process.cwd(), reportToCloud: shouldReportToCloud = true, cleanup: shouldCleanup = true, showSummary = true, showTestedList = false, showUntestedList = true, showCloudStatus = true, context, } = options;
     // Priority 1: Use environment variable (cross-process persistence from globalSetup)
     let projectRoot = process.env.DOTREQUIREMENTS_PROJECT_ROOT || null;
     // Priority 2: Find from cwd
@@ -309,7 +355,7 @@ export async function finalize(options = {}) {
     // HARNESS-FINALIZE-2, HARNESS-FINALIZE-3: Report to cloud
     let cloudResult = { sent: false, count: 0 };
     if (shouldReportToCloud) {
-        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus);
+        cloudResult = await reportToConvex(projectRoot, testRunId, aggregated, showCloudStatus, context);
     }
     // HARNESS-FINALIZE-4: Clean up tracking data
     if (shouldCleanup && !cloudResult.error) {

package/package.json

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