agentic-qe 3.15.11 → 3.15.12

package/dist/coordination/handlers/coverage-evidence.js

@@ -0,0 +1,159 @@
+/**
+ * Coverage evidence: is a report complete and current for its target? (#1154)
+ *
+ * A report judged over only the files it happens to contain says nothing
+ * about the target's other files. `aqe fleet run analyze --target src` printed
+ * "100% over 1 files" and "Verdict: PASSED" from a report that listed
+ * `src/math.js` while `src/unsafe.js` had no measurement at all, and a report
+ * written before the sources last changed was judged as if it were current.
+ *
+ * This module answers two questions for every caller of the shared resolver
+ * (MCP `coverage_analyze_sublinear` / `task_orchestrate`, `aqe coverage`,
+ * `aqe ci`, `aqe fleet run analyze`):
+ *   1. Which production source files under the target are not in the report?
+ *      They are UNMEASURED: not 0%, and not left out silently.
+ *   2. Is the report older than source files it is judged against? (stale)
+ * Either one makes the evidence insufficient: no verdict may pass on it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { walkSourceFiles } from './coverage-collection.js';
+import { inCoverageScope, readCoverageScope } from './coverage-scope.js';
+/** Source files that share a coverage tool with each other (one report covers one family). */
+const LANGUAGE_FAMILIES = [
+    ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'],
+    ['.py'], ['.go'], ['.rs'], ['.java'], ['.rb'],
+];
+function familyOf(file) {
+    const ext = path.extname(file).toLowerCase();
+    return LANGUAGE_FAMILIES.find(family => family.includes(ext));
+}
+/**
+ * Files no coverage tool instruments by default: type declarations and tool
+ * configuration (`vitest.config.ts`, `eslint.config.js`, `.prettierrc.js`).
+ */
+function isNeverInstrumented(file) {
+    const base = path.basename(file);
+    return base.endsWith('.d.ts') || base.startsWith('.') || /\.config\.[cm]?[jt]sx?$/.test(base);
+}
+function canonical(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Absolute, canonical paths of the report's entries (relative entries resolve against `projectRoot`). */
+function reportPaths(files, projectRoot) {
+    const rootAbs = canonical(projectRoot);
+    return new Set(files.map(f => path.isAbsolute(f.path) ? canonical(f.path) : canonical(path.resolve(rootAbs, f.path))));
+}
+/**
+ * Production source files under a directory `target` that the report has no
+ * entry for. Only files in a language the report covers count: a JS report
+ * does not make a Python helper script unmeasured. Files the project's coverage
+ * config leaves out (include/exclude) were never meant to be measured and do
+ * not count either.
+ */
+export function findUnmeasuredSourceFiles(reportFiles, projectRoot, target) {
+    let isDir = false;
+    try {
+        isDir = fs.statSync(target).isDirectory();
+    }
+    catch { /* missing: nothing to compare */ }
+    if (!isDir)
+        return { targetFiles: [], unmeasured: [] };
+    const rootAbs = canonical(projectRoot);
+    const scope = readCoverageScope(rootAbs);
+    const families = new Set(reportFiles.map(f => familyOf(f.path)).filter(Boolean));
+    const inReport = reportPaths(reportFiles, projectRoot);
+    const targetFiles = walkSourceFiles(target)
+        .filter(file => families.has(familyOf(file)) && !isNeverInstrumented(file))
+        .map(canonical)
+        .filter(file => inCoverageScope(scope, file, rootAbs));
+    return {
+        targetFiles,
+        unmeasured: targetFiles.filter(file => !inReport.has(file)).sort(),
+        ...(scope ? { coverageScope: { source: scope.source, readable: scope.readable } } : {}),
+    };
+}
+/** Source files modified after the report was written; `undefined` when the report is current. */
+export function findStaleness(reportPath, sourceFiles) {
+    let reportMtime;
+    try {
+        reportMtime = fs.statSync(reportPath).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+    const newerFiles = sourceFiles.filter(file => {
+        try {
+            return fs.statSync(file).mtimeMs > reportMtime;
+        }
+        catch {
+            return false;
+        }
+    }).sort();
+    return newerFiles.length > 0
+        ? { reportPath, reportModified: new Date(reportMtime).toISOString(), newerFiles }
+        : undefined;
+}
+/**
+ * The evidence a report gives for `target`.
+ *
+ * `measuredFiles` are the report entries already scoped to the target.
+ * Completeness is checked only when `checkCompleteness` is set (a directory
+ * target, not a report file given as the target), staleness only when the
+ * report's path is known (not for a report the run just wrote).
+ */
+export function assessCoverageEvidence(report, measuredFiles, projectRoot, target, options = {}) {
+    const { targetFiles, unmeasured, coverageScope } = options.checkCompleteness === false
+        ? { targetFiles: [], unmeasured: [], coverageScope: undefined }
+        : findUnmeasuredSourceFiles(report.files, projectRoot, target);
+    const sources = new Set([...targetFiles, ...reportPaths(measuredFiles, projectRoot)]);
+    const stale = options.reportPath
+        ? findStaleness(options.reportPath, [...sources].filter(file => fs.existsSync(file)))
+        : undefined;
+    return {
+        status: unmeasured.length > 0 || stale ? 'insufficient-evidence' : 'complete',
+        unmeasuredFiles: unmeasured,
+        targetFiles: sources.size,
+        ...(stale ? { stale } : {}),
+        ...(coverageScope ? { coverageScope } : {}),
+    };
+}
+const MAX_LISTED = 5;
+function listFiles(files, root) {
+    const shown = files.slice(0, MAX_LISTED).map(f => path.relative(root, f) || f);
+    return shown.join(', ') + (files.length > MAX_LISTED ? `, … ${files.length - MAX_LISTED} more` : '');
+}
+/**
+ * Why the evidence is insufficient, one sentence per problem; empty when it is
+ * complete. Shared by MCP and CLI so the wording cannot drift.
+ */
+export function describeEvidence(evidence, projectRoot) {
+    if (!evidence)
+        return [];
+    const reasons = [];
+    const n = evidence.unmeasuredFiles.length;
+    if (n > 0) {
+        const scope = evidence.coverageScope;
+        const scopeNote = scope && !scope.readable
+            ? ` The coverage include/exclude in ${scope.source} could not be read statically, so files it leaves out ` +
+                'may be listed here; write them as literal string arrays to have them honoured.'
+            : '';
+        reasons.push(`${n} of ${evidence.targetFiles} source files under the target are not in the coverage report ` +
+            `(UNMEASURED, not counted as covered): ${listFiles(evidence.unmeasuredFiles, projectRoot)}. Regenerate ` +
+            'the report with coverage for the whole target, or exclude files that are not meant to be measured in the ' +
+            `coverage tool's include/exclude config.${scopeNote}`);
+    }
+    if (evidence.stale) {
+        const m = evidence.stale.newerFiles.length;
+        reasons.push(`the coverage report ${path.relative(projectRoot, evidence.stale.reportPath) || evidence.stale.reportPath} ` +
+            `is STALE: ${m} source file${m === 1 ? ' was' : 's were'} modified after it was written ` +
+            `(${evidence.stale.reportModified}): ${listFiles(evidence.stale.newerFiles, projectRoot)}`);
+    }
+    return reasons;
+}
+//# sourceMappingURL=coverage-evidence.js.map

package/dist/coordination/handlers/coverage-handlers.js

@@ -9,6 +9,7 @@ import { toError } from '../../shared/error-utils.js';
 import { requirePayloadPath } from '../../shared/io/payload-path-guard.js';
 import { buildEstimatedCoverage, collectRustCoverage, findCargoRoot, isCoverageExecDisabled, isRustProject, } from './coverage-collection.js';
 import { describeNoData, evaluateCoverageForTarget, isUnmeasured, packageFilterForTarget, resolveExistingCoverage, scopeCoverageToTarget, reconcileRecommendations, thresholdVerdict, } from './coverage-target.js';
+import { describeEvidence } from './coverage-evidence.js';
 import { randomUUID } from 'crypto';
 import * as path from 'path';
 import { describeRunFailure, runJsCoverage, testRunStatus } from './coverage-runner.js';
@@ -54,7 +55,7 @@ function instrumented(files) {
 }
 function fromEvaluation(evaluation, ranTests, projectRoot) {
     return evaluation.status === 'measured'
-        ? { collected: instrumented(evaluation.files), ranTests, projectRoot }
+        ? { collected: instrumented(evaluation.files), ranTests, projectRoot, evidence: evaluation.evidence }
         : { collected: null, ranTests, noData: evaluation.reason, projectRoot };
 }
 /**
@@ -212,7 +213,7 @@ export function registerCoverageHandlers(ctx) {
             }
             const analyzer = ctx.getCoverageAnalyzer();
             const threshold = payload.threshold || 80;
-            const { collected, ranTests, noData, projectRoot, notes, runStatus, testRun } = await collectCoverage(targetPath);
+            const { collected, ranTests, noData, projectRoot, notes, runStatus, testRun, evidence } = await collectCoverage(targetPath);
             // #995 review N5: say so plainly instead of "no coverage data found".
             if (noData === 'target-missing') {
                 return err(new Error(describeNoData('target-missing', targetPath, null)));
@@ -278,9 +279,16 @@ export function registerCoverageHandlers(ctx) {
             }
             const round = (n) => Math.round(n * 10) / 10;
             const pct = (covered, total) => total > 0 ? Math.round((covered / total) * 1000) / 10 : null;
+            // #1154: target files missing from the report, or a report older than the
+            // sources, leave the evidence insufficient: the figures stand for the
+            // measured files only, and the threshold is not met on them.
+            const evidenceReasons = describeEvidence(evidence, projectRoot ?? targetPath);
             const warnings = [...provenance.notes, ...(notes ?? [])];
             if (provenance.estimated)
                 warnings.push(estimationGuidance(targetPath));
+            if (evidenceReasons.length > 0) {
+                warnings.push(`INSUFFICIENT EVIDENCE — the threshold is not met on this report: ${evidenceReasons.join('; ').replace(/\.?$/, '.')}`);
+            }
             // #569: the analyzer generates recommendations from the summary numbers.
             // When branch or function data was never collected, those numbers are 0
             // by construction, and the resulting advice ("Branch coverage is
@@ -312,7 +320,12 @@ export function registerCoverageHandlers(ctx) {
                 })),
                 gaps,
                 // NB5: judged only on the metrics that were collected (shared with the CLI).
-                meetsThreshold: verdict.meetsThreshold,
+                meetsThreshold: verdict.meetsThreshold && evidenceReasons.length === 0,
+                ...(evidence ? {
+                    evidenceStatus: evidence.status,
+                    unmeasuredFiles: evidence.unmeasuredFiles,
+                    ...(evidence.stale ? { staleReport: evidence.stale } : {}),
+                } : {}),
                 delta: report.delta,
                 recommendations,
                 algorithm: 'sublinear-O(log n)',

package/dist/coordination/handlers/coverage-scope.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The project's own coverage scope (#1154 review).
+ *
+ * A file the coverage tool is configured to leave out (vitest
+ * `coverage.exclude: ['src/**\/index.ts']`, jest `'!src/**\/index.ts'` in
+ * `collectCoverageFrom`) is not "unmeasured": it was never meant to be
+ * measured. Counting it would fail every verdict on a normal project.
+ *
+ * The scope is read STATICALLY from literal string arrays. Config files are
+ * never executed (they are code from the analyzed repository). When a config
+ * declares a coverage scope that is not a literal, the scope is reported as
+ * unreadable rather than guessed.
+ *
+ * Sources, first match wins:
+ *   - vitest.config.* / vite.config.*  `coverage: { include, exclude }`
+ *   - jest.config.* / package.json "jest"  `collectCoverageFrom` (`!` = exclude),
+ *     `coveragePathIgnorePatterns` (regular expressions)
+ *   - .nycrc / .nycrc.json / package.json "nyc", .c8rc / .c8rc.json /
+ *     package.json "c8"  `include`, `exclude`
+ */
+export interface CoverageScope {
+    /** The config the scope was read from, relative to the project root. */
+    source: string;
+    /** False when the config declares a scope that is not a literal string array. */
+    readable: boolean;
+    include: string[];
+    exclude: string[];
+    /** jest `coveragePathIgnorePatterns`, matched against the absolute path. */
+    ignorePatterns: RegExp[];
+}
+/**
+ * A pattern matches a project-relative POSIX path, or any path under it when it
+ * names a directory (nyc/test-exclude treat `src` as `src/**`).
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+/** The coverage scope configured for the project at `projectRoot`; `null` when none is configured. */
+export declare function readCoverageScope(projectRoot: string): CoverageScope | null;
+/** Is `file` inside the configured coverage scope? Everything is, with no scope. */
+export declare function inCoverageScope(scope: CoverageScope | null, file: string, projectRoot: string): boolean;
+//# sourceMappingURL=coverage-scope.d.ts.map

package/dist/coordination/handlers/coverage-scope.js

@@ -0,0 +1,321 @@
+/**
+ * The project's own coverage scope (#1154 review).
+ *
+ * A file the coverage tool is configured to leave out (vitest
+ * `coverage.exclude: ['src/**\/index.ts']`, jest `'!src/**\/index.ts'` in
+ * `collectCoverageFrom`) is not "unmeasured": it was never meant to be
+ * measured. Counting it would fail every verdict on a normal project.
+ *
+ * The scope is read STATICALLY from literal string arrays. Config files are
+ * never executed (they are code from the analyzed repository). When a config
+ * declares a coverage scope that is not a literal, the scope is reported as
+ * unreadable rather than guessed.
+ *
+ * Sources, first match wins:
+ *   - vitest.config.* / vite.config.*  `coverage: { include, exclude }`
+ *   - jest.config.* / package.json "jest"  `collectCoverageFrom` (`!` = exclude),
+ *     `coveragePathIgnorePatterns` (regular expressions)
+ *   - .nycrc / .nycrc.json / package.json "nyc", .c8rc / .c8rc.json /
+ *     package.json "c8"  `include`, `exclude`
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { readConfinedTextSync } from '../../shared/io/confined-read.js';
+const JS_EXTS = ['ts', 'mts', 'cts', 'js', 'mjs', 'cjs'];
+const VITEST_CONFIGS = [...JS_EXTS.map(e => `vitest.config.${e}`), ...JS_EXTS.map(e => `vite.config.${e}`)];
+const JEST_CONFIGS = [...JS_EXTS.map(e => `jest.config.${e}`), 'jest.config.json'];
+const NYC_CONFIGS = ['.nycrc', '.nycrc.json'];
+const C8_CONFIGS = ['.c8rc', '.c8rc.json'];
+// ============================================================================
+// Glob matching (no glob library is a runtime dependency)
+// ============================================================================
+function escapeRe(s) {
+    return s.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+/** Glob body → regex source: `**`, `*`, `?` and non-nested `{a,b}`. */
+function globSource(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*' && glob[i + 1] === '*') {
+            if (glob[i + 2] === '/') {
+                re += '(?:.*/)?';
+                i += 2;
+            }
+            else {
+                re += '.*';
+                i += 1;
+            }
+        }
+        else if (c === '*') {
+            re += '[^/]*';
+        }
+        else if (c === '?') {
+            re += '[^/]';
+        }
+        else if (c === '{') {
+            const end = glob.indexOf('}', i);
+            if (end === -1) {
+                re += '\\{';
+                continue;
+            }
+            re += `(?:${glob.slice(i + 1, end).split(',').map(globSource).join('|')})`;
+            i = end;
+        }
+        else {
+            re += escapeRe(c);
+        }
+    }
+    return re;
+}
+/**
+ * A pattern matches a project-relative POSIX path, or any path under it when it
+ * names a directory (nyc/test-exclude treat `src` as `src/**`).
+ */
+export function globToRegExp(pattern) {
+    const body = pattern.replace(/^<rootDir>\//, '').replace(/^\.\//, '').replace(/\/+$/, '');
+    return new RegExp(`^${globSource(body)}(?:/.*)?$`);
+}
+// ============================================================================
+// Static extraction of literal arrays from config source
+// ============================================================================
+/** Remove comments, leaving string literals (which may contain `/*`) intact. */
+function stripComments(src) {
+    let out = '';
+    for (let i = 0; i < src.length; i++) {
+        const c = src[i];
+        if (c === '"' || c === "'" || c === '`') {
+            const start = i;
+            for (i++; i < src.length && src[i] !== c; i++)
+                if (src[i] === '\\')
+                    i++;
+            out += src.slice(start, i + 1);
+        }
+        else if (c === '/' && src[i + 1] === '/') {
+            while (i < src.length && src[i] !== '\n')
+                i++;
+            out += '\n';
+        }
+        else if (c === '/' && src[i + 1] === '*') {
+            const end = src.indexOf('*/', i + 2);
+            i = end === -1 ? src.length : end + 1;
+        }
+        else {
+            out += c;
+        }
+    }
+    return out;
+}
+/** Index just past the bracket matching the one at `open`, skipping strings. */
+function matchingClose(src, open) {
+    const pairs = { '[': ']', '{': '}', '(': ')' };
+    const stack = [];
+    for (let i = open; i < src.length; i++) {
+        const c = src[i];
+        if (c === '"' || c === "'" || c === '`') {
+            for (i++; i < src.length && src[i] !== c; i++)
+                if (src[i] === '\\')
+                    i++;
+        }
+        else if (pairs[c]) {
+            stack.push(pairs[c]);
+        }
+        else if (c === stack[stack.length - 1]) {
+            stack.pop();
+            if (stack.length === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+/** Split a bracket body on top-level commas. */
+function splitTopLevel(body) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '"' || c === "'" || c === '`') {
+            for (i++; i < body.length && body[i] !== c; i++)
+                if (body[i] === '\\')
+                    i++;
+        }
+        else if ('[{('.includes(c))
+            depth++;
+        else if (']})'.includes(c))
+            depth--;
+        else if (c === ',' && depth === 0) {
+            parts.push(body.slice(start, i));
+            start = i + 1;
+        }
+    }
+    parts.push(body.slice(start));
+    return parts.map(p => p.trim()).filter(p => p.length > 0);
+}
+const STRING_LITERAL = /^(['"])((?:\\.|(?!\1)[^\\])*)\1$|^`([^`$\\]*)`$/;
+/**
+ * The value of `key:` in `src` as a literal string array. `undefined` when the
+ * key is absent, `null` when it is present but not a literal. A spread of the
+ * tool's own defaults (`...coverageConfigDefaults.exclude`) is skipped: those
+ * are tests and config files, which are never counted anyway.
+ */
+function literalArray(src, key) {
+    const m = new RegExp(`(?:^|[\\s,{])['"]?${key}['"]?\\s*:\\s*`).exec(src);
+    if (!m)
+        return undefined;
+    const at = m.index + m[0].length;
+    if (src[at] === "'" || src[at] === '"') {
+        const single = STRING_LITERAL.exec(src.slice(at, matchingStringEnd(src, at)));
+        return single ? [single[2] ?? single[3]] : null;
+    }
+    if (src[at] !== '[')
+        return null;
+    const end = matchingClose(src, at);
+    if (end === -1)
+        return null;
+    const values = [];
+    for (const el of splitTopLevel(src.slice(at + 1, end - 1))) {
+        if (/^\.\.\.[\w$.]*defaults?\b/i.test(el))
+            continue;
+        const lit = STRING_LITERAL.exec(el);
+        if (!lit)
+            return null;
+        values.push(lit[2] ?? lit[3]);
+    }
+    return values;
+}
+function matchingStringEnd(src, at) {
+    let i = at + 1;
+    for (; i < src.length && src[i] !== src[at]; i++)
+        if (src[i] === '\\')
+            i++;
+    return i + 1;
+}
+// ============================================================================
+// Readers
+// ============================================================================
+function readText(file) {
+    try {
+        return readConfinedTextSync(file, { outsideRoot: 'allow' });
+    }
+    catch {
+        return null;
+    }
+}
+function readJson(file) {
+    const text = readText(file);
+    if (text === null)
+        return null;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const strings = (v) => v === undefined ? undefined
+    : typeof v === 'string' ? [v]
+        : Array.isArray(v) && v.every(e => typeof e === 'string') ? v : null;
+function scope(source, parts) {
+    const readable = [parts.include, parts.exclude, parts.collectFrom, parts.ignore].every(p => p !== null);
+    const collect = parts.collectFrom ?? [];
+    const ignorePatterns = [];
+    for (const p of parts.ignore ?? []) {
+        try {
+            ignorePatterns.push(new RegExp(p));
+        }
+        catch { /* jest would reject it too */ }
+    }
+    return {
+        source, readable, ignorePatterns,
+        include: [...(parts.include ?? []), ...collect.filter(g => !g.startsWith('!'))],
+        exclude: [...(parts.exclude ?? []), ...collect.filter(g => g.startsWith('!')).map(g => g.slice(1))],
+    };
+}
+function fromVitest(name, text) {
+    const src = stripComments(text);
+    const m = /(?:^|[\s,{])['"]?coverage['"]?\s*(?::\s*|(?=[,}]))/.exec(src);
+    if (!m)
+        return null;
+    const at = m.index + m[0].length;
+    // `coverage,` shorthand or `coverage: options`: declared, not readable.
+    if (!m[0].includes(':') || src[at] !== '{')
+        return scope(name, { include: null });
+    const end = matchingClose(src, at);
+    const block = end === -1 ? '' : src.slice(at, end);
+    return scope(name, { include: literalArray(block, 'include'), exclude: literalArray(block, 'exclude') });
+}
+function fromJestText(name, text) {
+    const src = stripComments(text);
+    const collectFrom = literalArray(src, 'collectCoverageFrom');
+    const ignore = literalArray(src, 'coveragePathIgnorePatterns');
+    if (collectFrom === undefined && ignore === undefined)
+        return null;
+    return scope(name, { collectFrom, ignore });
+}
+function fromJsonKeys(name, obj) {
+    if (!obj || typeof obj !== 'object')
+        return null;
+    if ('collectCoverageFrom' in obj || 'coveragePathIgnorePatterns' in obj) {
+        return scope(name, { collectFrom: strings(obj.collectCoverageFrom), ignore: strings(obj.coveragePathIgnorePatterns) });
+    }
+    if ('include' in obj || 'exclude' in obj) {
+        return scope(name, { include: strings(obj.include), exclude: strings(obj.exclude) });
+    }
+    return null;
+}
+/** The coverage scope configured for the project at `projectRoot`; `null` when none is configured. */
+export function readCoverageScope(projectRoot) {
+    for (const name of VITEST_CONFIGS) {
+        const text = readText(path.join(projectRoot, name));
+        if (text !== null) {
+            const found = fromVitest(name, text);
+            if (found)
+                return found;
+        }
+    }
+    for (const name of JEST_CONFIGS) {
+        const file = path.join(projectRoot, name);
+        if (!fs.existsSync(file))
+            continue;
+        const found = name.endsWith('.json')
+            ? fromJsonKeys(name, readJson(file) ?? undefined)
+            : fromJestText(name, readText(file) ?? '');
+        if (found)
+            return found;
+    }
+    const pkg = readJson(path.join(projectRoot, 'package.json'));
+    const fromPkg = fromJsonKeys('package.json "jest"', pkg?.jest);
+    if (fromPkg)
+        return fromPkg;
+    for (const [names, key] of [[NYC_CONFIGS, 'nyc'], [C8_CONFIGS, 'c8']]) {
+        for (const name of names) {
+            const obj = readJson(path.join(projectRoot, name));
+            const found = fromJsonKeys(name, obj ?? undefined);
+            if (found)
+                return found;
+            // A config that exists but is not JSON (e.g. YAML) cannot be read.
+            if (!obj && fs.existsSync(path.join(projectRoot, name)))
+                return scope(name, { include: null });
+        }
+        const found = fromJsonKeys(`package.json "${key}"`, pkg?.[key]);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Is `file` inside the configured coverage scope? Everything is, with no scope. */
+export function inCoverageScope(scope, file, projectRoot) {
+    if (!scope)
+        return true;
+    const rel = path.relative(projectRoot, file).split(path.sep).join('/');
+    if (scope.include.length > 0 && !scope.include.some(g => globToRegExp(g).test(rel)))
+        return false;
+    if (scope.exclude.some(g => globToRegExp(g).test(rel)))
+        return false;
+    const posixAbs = file.split(path.sep).join('/');
+    const rootPosix = projectRoot.split(path.sep).join('/');
+    return !scope.ignorePatterns.some(re => re.test(posixAbs) || re.test(posixAbs.replace(rootPosix, '<rootDir>')));
+}
+//# sourceMappingURL=coverage-scope.js.map

package/dist/coordination/handlers/coverage-target.d.ts

@@ -19,6 +19,7 @@
  * and the CLI `coverage` command can share it.
  */
 import type { CoverageData, FileCoverage } from '../../domains/coverage-analysis/interfaces';
+import { type CoverageEvidence } from './coverage-evidence';
 /**
  * Walk up from a target to the nearest directory that holds a project marker.
  *
@@ -75,6 +76,7 @@ export type NoDataReason =
 export type CoverageEvaluation = {
     status: 'measured';
     files: FileCoverage[];
+    evidence: CoverageEvidence;
 } | {
     status: 'no-data';
     reason: NoDataReason;
@@ -88,9 +90,16 @@ export type CoverageEvaluation = {
  *   - the report has no entry under the target.
  * Hit counts are never used: a file listed with 0 hits is a measured 0%,
  * whether the report came from our run or from the user (#995 review B3).
+ *
+ * A measured result carries its evidence (#1154): the target's source files
+ * the report has no entry for (UNMEASURED), and whether the report at
+ * `reportPath` is older than the sources. Insufficient evidence keeps the
+ * figures for the measured files, but no caller may pass a verdict on it.
  */
 export declare function evaluateCoverageForTarget(report: CoverageData, projectRoot: string, target: string, options?: {
     numTotalTests?: number | null;
+    reportPath?: string;
+    checkCompleteness?: boolean;
 }): CoverageEvaluation;
 export type ExistingCoverage = {
     status: 'target-missing';

package/dist/coordination/handlers/coverage-target.js

@@ -22,8 +22,9 @@ import * as fs from 'fs';
 import { readConfinedText, readConfinedTextSync } from '../../shared/io/confined-read.js';
 import * as os from 'os';
 import * as path from 'path';
-import { loadCoverageData, parseCoberturaXml, parseCoverageJson, parseCoverageSummaryJson, parseLcovInfo, } from './handler-utils.js';
+import { loadCoverageReport, parseCoberturaXml, parseCoverageJson, parseCoverageSummaryJson, parseLcovInfo, } from './handler-utils.js';
 import { isTestPath } from './coverage-collection.js';
+import { assessCoverageEvidence } from './coverage-evidence.js';
 import { findProjectRoot } from '../../kernel/project-root.js';
 // ============================================================================
 // Project root
@@ -418,6 +419,11 @@ export function scopeCoverageToTarget(data, root, target) {
  *   - the report has no entry under the target.
  * Hit counts are never used: a file listed with 0 hits is a measured 0%,
  * whether the report came from our run or from the user (#995 review B3).
+ *
+ * A measured result carries its evidence (#1154): the target's source files
+ * the report has no entry for (UNMEASURED), and whether the report at
+ * `reportPath` is older than the sources. Insufficient evidence keeps the
+ * figures for the measured files, but no caller may pass a verdict on it.
  */
 export function evaluateCoverageForTarget(report, projectRoot, target, options = {}) {
     if (options.numTotalTests === 0)
@@ -430,7 +436,10 @@ export function evaluateCoverageForTarget(report, projectRoot, target, options =
     const production = scoped.filter(f => !isTestPath(f.path, projectRoot));
     if (production.length === 0)
         return { status: 'no-data', reason: 'test-only-report' };
-    return { status: 'measured', files: production };
+    const evidence = assessCoverageEvidence(report, production, projectRoot, target, {
+        reportPath: options.reportPath, checkCompleteness: options.checkCompleteness,
+    });
+    return { status: 'measured', files: production, evidence };
 }
 /**
  * Resolve a target to coverage that already exists on disk, without running
@@ -454,18 +463,19 @@ export async function resolveExistingCoverage(targetPath) {
         const projectRoot = findCoverageProjectRoot(reportDir)
             ?? (path.basename(reportDir) === 'coverage' ? path.dirname(reportDir) : reportDir);
         const report = await loadCoverageReportFile(target);
+        // The report itself is the target: judged whole, but still checked for staleness.
         const evaluation = report
-            ? evaluateCoverageForTarget(report, projectRoot, projectRoot)
+            ? evaluateCoverageForTarget(report, projectRoot, projectRoot, { reportPath: target, checkCompleteness: false })
             : { status: 'no-data', reason: 'unreadable-report' };
         return { status: 'evaluated', target, projectRoot, source: 'report-file', evaluation };
     }
     const projectRoot = findCoverageProjectRoot(target) ?? (stat.isDirectory() ? target : path.dirname(target));
-    const existing = await loadCoverageData(projectRoot);
+    const existing = await loadCoverageReport(projectRoot);
     if (!existing)
         return { status: 'no-report', target, projectRoot };
     return {
         status: 'evaluated', target, projectRoot, source: 'project-report',
-        evaluation: evaluateCoverageForTarget(existing, projectRoot, target),
+        evaluation: evaluateCoverageForTarget(existing.data, projectRoot, target, { reportPath: existing.path }),
     };
 }
 /**