@popoverai/dotrequirements 0.29.1 → 0.29.2

package/dist/codebase-to-spec/compose.js

@@ -82,10 +82,6 @@ export function assembleComposedDocument(outline, partialPathFor) {
         partialsMissing,
     };
 }
-/** Escape a string for safe YAML scalar use. */
-function escapeYamlString(s) {
-    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-}
 /**
  * Compose the spec and write it to disk. Renumbers requirement IDs into a
  * clean sequence (CTS-COMPOSE-3), then validates the result.

package/dist/codebase-to-spec/renumber.d.ts

@@ -34,11 +34,13 @@ export interface Rename {
  * a contiguous 1..N sequence. Returns the rename list (including identity
  * renames for already-clean IDs, so callers can treat the result uniformly).
  *
- * Only the first line of each ```dotrequirements block is treated as a header
- * (one requirement per block, matching the parser's contract). Exact-duplicate
- * keys are a distinct validation error and out of scope here: a repeated key
- * does not consume a sequence slot (so it introduces no phantom gap) and keeps
- * its first mapping, leaving the downstream validator to flag the duplicate.
+ * A fence may hold several adjacent requirements (SYNC-FORMAT-4), so every
+ * header line in a block counts, not just the first. HEADER_RE is anchored at
+ * column zero and criteria are indented, so criterion text never reads as a
+ * header. Exact-duplicate keys are a distinct validation error and out of scope
+ * here: a repeated key does not consume a sequence slot (so it introduces no
+ * phantom gap) and keeps its first mapping, leaving the downstream validator to
+ * flag the duplicate.
  */
 export declare function computeRenames(content: string): Rename[];
 /**

package/dist/codebase-to-spec/renumber.js

@@ -41,11 +41,13 @@ function escapeRegExp(s) {
  * a contiguous 1..N sequence. Returns the rename list (including identity
  * renames for already-clean IDs, so callers can treat the result uniformly).
  *
- * Only the first line of each ```dotrequirements block is treated as a header
- * (one requirement per block, matching the parser's contract). Exact-duplicate
- * keys are a distinct validation error and out of scope here: a repeated key
- * does not consume a sequence slot (so it introduces no phantom gap) and keeps
- * its first mapping, leaving the downstream validator to flag the duplicate.
+ * A fence may hold several adjacent requirements (SYNC-FORMAT-4), so every
+ * header line in a block counts, not just the first. HEADER_RE is anchored at
+ * column zero and criteria are indented, so criterion text never reads as a
+ * header. Exact-duplicate keys are a distinct validation error and out of scope
+ * here: a repeated key does not consume a sequence slot (so it introduces no
+ * phantom gap) and keeps its first mapping, leaving the downstream validator to
+ * flag the duplicate.
  */
 export function computeRenames(content) {
     const counters = new Map();
@@ -54,18 +56,18 @@ export function computeRenames(content) {
     BLOCK_RE.lastIndex = 0;
     let block = BLOCK_RE.exec(content);
     while (block !== null) {
-        const body = block[1];
-        const firstLine = body.split("\n").find((l) => l.trim().length > 0) ?? "";
-        const m = firstLine.match(HEADER_RE);
-        if (m) {
+        for (const line of block[1].split("\n")) {
+            const m = line.match(HEADER_RE);
+            if (!m)
+                continue;
             const [, prefix, num, suffix] = m;
             const from = `${prefix}-${num}${suffix}`;
-            if (!seen.has(from)) {
-                seen.add(from);
-                const next = (counters.get(prefix) ?? 0) + 1;
-                counters.set(prefix, next);
-                renames.push({ from, to: `${prefix}-${next}` });
-            }
+            if (seen.has(from))
+                continue;
+            seen.add(from);
+            const next = (counters.get(prefix) ?? 0) + 1;
+            counters.set(prefix, next);
+            renames.push({ from, to: `${prefix}-${next}` });
         }
         block = BLOCK_RE.exec(content);
     }

package/dist/commands/report.js

@@ -1,3 +1,5 @@
+import { findRequirementsDir, readCoverageCache } from "../harness/cache.js";
+import { formatUnrecordedNotice } from "../harness/reportingStatus.js";
 import { getProjectCoverage, getRequirementCoverage, } from "../requirements/cloud-coverage.js";
 import { buildLocalReport, } from "../requirements/coverage.js";
 import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
@@ -5,11 +7,23 @@ const CONVEX_URL = "https://data.dotrequirements.io";
 export async function reportCommand(options) {
     const source = options.source ?? "local";
     const format = options.format ?? "console";
+    const projectRoot = findProjectRoot(process.cwd());
+    // COVERAGE-REPORT-3.1: someone asking about coverage learns first that
+    // coverage stopped recording. On stderr so machine-readable formats stay
+    // parseable.
+    if (projectRoot) {
+        const requirementsDir = findRequirementsDir(projectRoot);
+        const notice = requirementsDir
+            ? formatUnrecordedNotice(readCoverageCache(requirementsDir))
+            : null;
+        if (notice) {
+            console.error(notice);
+        }
+    }
     if (source === "local" && (options.branch || options.since !== undefined)) {
         throw new Error("--branch and --since require --source cloud. Local reports cover only the most recent test run on this machine.");
     }
     if (source === "local") {
-        const projectRoot = findProjectRoot(process.cwd());
         if (!projectRoot) {
             throw new Error('Could not find .requirements/ directory. Run "dotrequirements init" to initialize your project.');
         }

package/dist/commands/sync.js

@@ -93,7 +93,7 @@ export async function syncCommand(scope, options) {
         return "clean";
     }
     console.log(`\nSyncing with ${brand} cloud...`);
-    const outcome = await executePlan(plan, cloud, auth, workspaceRoot);
+    const outcome = await executePlan(plan, cloud, auth, workspaceRoot, mode);
     // Report.
     if (outcome.cloudCreated)
         console.log(`  Created in cloud: ${outcome.cloudCreated}`);
@@ -119,6 +119,12 @@ export async function syncCommand(scope, options) {
     for (const r of outcome.renames) {
         console.log(`  renamed "${r.from}" → "${r.to}"`);
     }
+    // DOC-HEADER-11.4: a prefix nobody wrote down was read off the first
+    // requirement key — name it rather than letting it appear in the frontmatter
+    // unannounced.
+    for (const { name, prefix } of outcome.inferredPrefixes) {
+        console.log(`  ${name}: no prefix in frontmatter — using "${prefix}"`);
+    }
     // IMPORT-3: marker failures are loud but never fatal.
     for (const { name, status } of outcome.importWarnings) {
         if (status === "already_used") {

package/dist/harness/cache.d.ts

@@ -64,9 +64,55 @@ export interface CoverageCacheEntry {
     /** Legacy field retained for backward-compat reads of pre-attribution caches. */
     requirementKeys?: string[];
 }
+/**
+ * The most recent reporting attempt that did not reach the cloud.
+ *
+ * Written on every failed attempt and cleared the moment one succeeds, so its
+ * presence alone answers "is coverage recording right now?" (COVERAGE-REPORT-3).
+ */
+/** One requirement's coverage as it is sent to the cloud. */
+export interface CoverageRow {
+    requirementKey: string;
+    testFile?: string;
+    testLine?: number;
+    user?: string;
+}
+/**
+ * A report that did not land, kept verbatim so a later run can replay it.
+ *
+ * Stored whole rather than as bare tuples for two reasons. A later run only
+ * knows the requirements *it* exercised, so anything narrower can never retry
+ * what a partial run (`vitest run one.test.ts`, a CI shard) doesn't touch. And
+ * branch and attribution belong to the original run — replaying them under a
+ * later run's branch would file the coverage against the wrong one.
+ */
+export interface PendingCoverageReport {
+    branch?: string;
+    context?: string;
+    runId?: string;
+    coverage: CoverageRow[];
+}
+export interface CoverageReportFailure {
+    timestamp: number;
+    /** The reason as it will be shown to the developer. */
+    reason: string;
+    /** The report to replay. Absent on caches written before replay existed. */
+    pending?: PendingCoverageReport;
+}
 export interface CoverageCache {
     current: CoverageCacheEntry | null;
     previous: CoverageCacheEntry | null;
+    /**
+     * When a report last actually reached the cloud.
+     *
+     * Deliberately separate from `current.timestamp`, which the debounce path
+     * also refreshes without contacting anything — anchoring "coverage last
+     * recorded …" on that would let a daily-driver suite roll the claim forward
+     * indefinitely while the cloud went stale (COVERAGE-REPORT-3.0).
+     */
+    lastRecordedAt?: number;
+    /** Absent while reporting is healthy. */
+    lastFailure?: CoverageReportFailure;
 }
 /**
  * Find the nearest .requirements directory by walking up from startDir
@@ -128,10 +174,45 @@ export declare function readTrackingEntries(requirementsDir: string): TrackingEn
 export declare function deleteTrackingFile(requirementsDir: string): void;
 export declare function readCoverageCache(requirementsDir: string): CoverageCache;
 /**
- * Update the coverage cache after reporting. Accepts either attribution tuples
- * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
+ * Update the debounce window after a reporting attempt. Accepts either
+ * attribution tuples (new) or bare requirement keys (legacy; converted to
+ * tuples with no context/branch).
+ *
+ * Says nothing about whether anything reached the cloud — the debounce path
+ * calls this having contacted nothing. Whether coverage is recording is
+ * `lastRecordedAt` / `lastFailure`, and both are carried through untouched.
  */
 export declare function updateCoverageCache(requirementsDir: string, testRunId: string, tuples: CoverageTuple[] | string[]): void;
+/**
+ * Record that coverage actually reached the cloud: refresh the debounce window,
+ * stamp when it landed, and drop any standing failure (COVERAGE-REPORT-3.3).
+ *
+ * This is the only path that may clear `lastFailure` on the strength of a
+ * successful report.
+ */
+export declare function recordCoverageReported(requirementsDir: string, testRunId: string, tuples: CoverageTuple[] | string[], timestamp?: number): void;
+/**
+ * Record that a reporting attempt did not reach the cloud, preserving when
+ * coverage last actually recorded — that is what "coverage last recorded …" is
+ * measured from (COVERAGE-REPORT-3.0).
+ */
+export declare function recordCoverageReportFailure(requirementsDir: string, reason: string, timestamp?: number, pending?: PendingCoverageReport): void;
+/**
+ * Drop a standing failure without claiming a report landed.
+ *
+ * For when reporting has stopped being applicable at all — an unlinked project
+ * is not failing to record, so the notice must not outlive the link
+ * (COVERAGE-REPORT-3.3).
+ */
+/**
+ * Record that a previously failed report has now landed on replay.
+ *
+ * Stamps when coverage recorded and drops the failure, leaving the debounce
+ * window alone — the replay carries an earlier run's tuples, which say nothing
+ * about what this run should send (COVERAGE-REPORT-3.4).
+ */
+export declare function recordCoverageReplayed(requirementsDir: string, timestamp?: number): void;
+export declare function clearCoverageReportFailure(requirementsDir: string): void;
 export declare const COVERAGE_DEBOUNCE_WINDOW_MS: number;
 /**
  * Check if an attribution tuple needs reporting based on the coverage cache.

package/dist/harness/cache.js

@@ -286,6 +286,26 @@ function normalizeEntry(raw) {
     }
     return null;
 }
+/**
+ * Normalize the last-failure record read from disk. Caches written before
+ * COVERAGE-REPORT-3 have no such field, which reads as "reporting is healthy".
+ */
+function normalizeFailure(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const failure = raw;
+    if (typeof failure.timestamp !== "number")
+        return undefined;
+    if (typeof failure.reason !== "string")
+        return undefined;
+    const pending = failure.pending;
+    const replayable = pending && typeof pending === "object" && Array.isArray(pending.coverage);
+    return {
+        timestamp: failure.timestamp,
+        reason: failure.reason,
+        ...(replayable ? { pending } : {}),
+    };
+}
 export function readCoverageCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
     const coveragePath = path.join(cacheDir, COVERAGE_FILE);
@@ -295,9 +315,13 @@ export function readCoverageCache(requirementsDir) {
     try {
         const content = fs.readFileSync(coveragePath, "utf-8");
         const raw = JSON.parse(content);
+        const lastFailure = normalizeFailure(raw?.lastFailure);
+        const lastRecordedAt = typeof raw?.lastRecordedAt === "number" ? raw.lastRecordedAt : undefined;
         return {
             current: normalizeEntry(raw?.current),
             previous: normalizeEntry(raw?.previous),
+            ...(lastRecordedAt !== undefined ? { lastRecordedAt } : {}),
+            ...(lastFailure ? { lastFailure } : {}),
         };
     }
     catch {
@@ -305,25 +329,87 @@ export function readCoverageCache(requirementsDir) {
     }
 }
 /**
- * Update the coverage cache after reporting. Accepts either attribution tuples
- * (new) or bare requirement keys (legacy; converted to tuples with no context/branch).
+ * Update the debounce window after a reporting attempt. Accepts either
+ * attribution tuples (new) or bare requirement keys (legacy; converted to
+ * tuples with no context/branch).
+ *
+ * Says nothing about whether anything reached the cloud — the debounce path
+ * calls this having contacted nothing. Whether coverage is recording is
+ * `lastRecordedAt` / `lastFailure`, and both are carried through untouched.
  */
 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 = {
+    writeCoverageCache(requirementsDir, {
+        ...existing,
         current: {
             testRunId,
             timestamp: Date.now(),
             tuples: normalized,
         },
         previous: existing.current,
-    };
-    fs.writeFileSync(coveragePath, JSON.stringify(newCache, null, 2));
+    });
+}
+/**
+ * Record that coverage actually reached the cloud: refresh the debounce window,
+ * stamp when it landed, and drop any standing failure (COVERAGE-REPORT-3.3).
+ *
+ * This is the only path that may clear `lastFailure` on the strength of a
+ * successful report.
+ */
+export function recordCoverageReported(requirementsDir, testRunId, tuples, timestamp = Date.now()) {
+    updateCoverageCache(requirementsDir, testRunId, tuples);
+    const existing = readCoverageCache(requirementsDir);
+    writeCoverageCache(requirementsDir, {
+        current: existing.current,
+        previous: existing.previous,
+        lastRecordedAt: timestamp,
+    });
+}
+/**
+ * Record that a reporting attempt did not reach the cloud, preserving when
+ * coverage last actually recorded — that is what "coverage last recorded …" is
+ * measured from (COVERAGE-REPORT-3.0).
+ */
+export function recordCoverageReportFailure(requirementsDir, reason, timestamp = Date.now(), pending) {
+    const existing = readCoverageCache(requirementsDir);
+    writeCoverageCache(requirementsDir, {
+        ...existing,
+        lastFailure: { timestamp, reason, ...(pending ? { pending } : {}) },
+    });
+}
+/**
+ * Drop a standing failure without claiming a report landed.
+ *
+ * For when reporting has stopped being applicable at all — an unlinked project
+ * is not failing to record, so the notice must not outlive the link
+ * (COVERAGE-REPORT-3.3).
+ */
+/**
+ * Record that a previously failed report has now landed on replay.
+ *
+ * Stamps when coverage recorded and drops the failure, leaving the debounce
+ * window alone — the replay carries an earlier run's tuples, which say nothing
+ * about what this run should send (COVERAGE-REPORT-3.4).
+ */
+export function recordCoverageReplayed(requirementsDir, timestamp = Date.now()) {
+    const existing = readCoverageCache(requirementsDir);
+    const { lastFailure: _cleared, ...rest } = existing;
+    writeCoverageCache(requirementsDir, { ...rest, lastRecordedAt: timestamp });
+}
+export function clearCoverageReportFailure(requirementsDir) {
+    const existing = readCoverageCache(requirementsDir);
+    if (!existing.lastFailure)
+        return;
+    const { lastFailure: _dropped, ...rest } = existing;
+    writeCoverageCache(requirementsDir, rest);
+}
+function writeCoverageCache(requirementsDir, cache) {
+    const cacheDir = getCacheDir(requirementsDir, true);
+    const coveragePath = path.join(cacheDir, COVERAGE_FILE);
+    fs.writeFileSync(coveragePath, JSON.stringify(cache, null, 2));
 }
-export const COVERAGE_DEBOUNCE_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours — must match server-side in testCoverage/mutations.ts
+export const COVERAGE_DEBOUNCE_WINDOW_MS = 4 * 60 * 60 * 1000; // 4 hours — must match DEBOUNCE_WINDOW_MS in testCoverage/helpers.ts
 function tuplesMatch(a, b) {
     return (a.requirementKey === b.requirementKey &&
         a.context === b.context &&