agentic-qe 3.15.4 → 3.15.6

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

@@ -4,10 +4,148 @@
  * Extracted from task-executor.ts registerHandlers().
  * Covers: assess-quality
  */
+import * as nodePath from 'node:path';
+import { existsSync, promises as fsp } from 'node:fs';
 import { ok, err } from '../../shared/types/index.js';
-import { toError } from '../../shared/error-utils.js';
+import { CallerInputError, toError } from '../../shared/error-utils.js';
 import { discoverSourceFiles } from './handler-utils.js';
-import { evaluateQualityEvidence, loadQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
+import { findProjectRoot } from '../../kernel/project-root.js';
+import { INSUFFICIENT_EVIDENCE, describeMissingMetrics, evaluateQualityEvidence, loadQualityEvidence, } from '../../domains/quality-assessment/quality-evidence.js';
+import { assessEvidenceSufficiency, describeMeasuredFailure, findMeasuredFailures, isMeasuredMetricValue, resolveCoverageOverride, validateRequestedMetrics, } from '../../domains/quality-assessment/evidence-sufficiency.js';
+const DEFAULT_STATIC_METRICS = ['coverage', 'complexity', 'maintainability', 'testability'];
+const UNMEASURED = -1;
+const STATIC_ONLY_NOTE = 'Static analysis only; no quality gate was evaluated. '
+    + 'Call quality_assess with runGate: true (or `aqe quality --gate`) for a pass/fail gate on measured evidence.';
+/** #996: report the -1 sentinel instead of a fabricated number for unmeasured values. */
+function sentinel(value) {
+    return isMeasuredMetricValue(value) ? value : UNMEASURED;
+}
+/**
+ * #1011: why each unmeasured metric has no value — the analyzer's reason
+ * (unreadable or unparseable file, failed detection, no stored coverage).
+ */
+function unmeasuredReasons(unmeasured, reported) {
+    const byMetric = new Map((reported ?? []).map((u) => [u.metric, u.reason]));
+    return Object.fromEntries(unmeasured.map((metric) => [
+        metric,
+        byMetric.get(metric) ?? (metric === 'security'
+            ? 'static analysis never measures security'
+            : 'the static analyzer produced no measured value'),
+    ]));
+}
+/** Cap on excluded files echoed back in the result (the count is always exact). */
+const MAX_EXCLUDED_LISTED = 50;
+/** True when `candidate` is `root` or lies beneath it. */
+function isWithin(root, candidate) {
+    const relative = nodePath.relative(root, candidate);
+    return relative === '' || (relative !== '..' && !relative.startsWith(`..${nodePath.sep}`) && !nodePath.isAbsolute(relative));
+}
+/**
+ * #1021 (B2): resolve a caller path against the project root and require it to
+ * stay inside — lexically, and by realpath when it exists (so a symlink cannot
+ * lead outside). A path that does not exist is returned as resolved; the
+ * analyzer reports it as unreadable.
+ */
+async function resolveContained(input, root, label) {
+    const resolved = nodePath.resolve(root, input);
+    if (input.includes('\0') || !isWithin(root, resolved)) {
+        throw new CallerInputError(`${label} ${JSON.stringify(input)} is outside the project root (${root}).`);
+    }
+    let real;
+    try {
+        real = await fsp.realpath(resolved);
+    }
+    catch {
+        return resolved;
+    }
+    const rootReal = await fsp.realpath(root).catch(() => root);
+    if (!isWithin(rootReal, real)) {
+        throw new CallerInputError(`${label} ${JSON.stringify(input)} resolves outside the project root (${root}).`);
+    }
+    return resolved;
+}
+/**
+ * #1021 (B2): the files to analyse and which of them the caller named. Explicit
+ * sourceFiles win over target; with neither, src/ (else the root) is analysed.
+ */
+async function resolveAnalysisScope(payload) {
+    // #1021 round 2b: the AQE project root (AQE_PROJECT_ROOT, else detected),
+    // not the process cwd — an MCP server may run from another directory.
+    const root = findProjectRoot();
+    if (Array.isArray(payload.sourceFiles) && payload.sourceFiles.length > 0) {
+        const files = [];
+        for (const file of payload.sourceFiles) {
+            if (typeof file !== 'string' || file.trim() === '') {
+                throw new CallerInputError('sourceFiles must be a non-empty array of file paths.');
+            }
+            files.push(await resolveContained(file, root, 'sourceFile'));
+        }
+        return { sourceFiles: files, explicitFiles: files, scope: 'sourceFiles' };
+    }
+    if (typeof payload.target === 'string' && payload.target.trim() !== '') {
+        const target = await resolveContained(payload.target, root, 'target');
+        const stat = await fsp.stat(target).catch(() => null);
+        if (!stat)
+            throw new CallerInputError(`target ${JSON.stringify(payload.target)} does not exist.`);
+        if (stat.isFile())
+            return { sourceFiles: [target], explicitFiles: [target], scope: target };
+        return { sourceFiles: await discoverSourceFiles(target, { includeTests: false }), explicitFiles: [], scope: target };
+    }
+    // Default to src/ — scanning the entire project root is too slow
+    // (node_modules, dist, .git, etc. make it hang on large projects)
+    const srcDir = nodePath.join(root, 'src');
+    const targetDir = existsSync(srcDir) ? srcDir : root;
+    return { sourceFiles: await discoverSourceFiles(targetDir, { includeTests: false }), explicitFiles: [], scope: targetDir };
+}
+/** #1021: one line per partially measured metric, naming the gap. */
+function describePartialMetrics(partial) {
+    return (partial ?? []).map((p) => `Partial evidence: ${p.metric} measured over ${p.analysedFiles} of ${p.totalFiles} `
+        // coverageOfScope is already rounded down to 3 decimals; round only float noise here.
+        + `file(s) (${Math.round(p.coverageOfScope * 1000) / 10}%); not analysed: `
+        + p.failed.slice(0, 3).map((f) => f.reason).join('; ')
+        + (p.failed.length > 3 ? `; and ${p.failed.length - 3} more` : '') + '.');
+}
+/** #996 (N3): reject a malformed `metrics` list instead of spreading a string into characters. */
+function requestedMetricsFrom(metrics) {
+    if (metrics === undefined)
+        return DEFAULT_STATIC_METRICS;
+    try {
+        return validateRequestedMetrics(metrics);
+    }
+    catch (error) {
+        throw new CallerInputError(toError(error).message);
+    }
+}
+/**
+ * #996: the user-configured gate coverage threshold (`quality_gate.thresholds.coverage`
+ * in .aqe-ci.yml), found the same way `aqe ci` finds its config. Undefined when
+ * there is no readable config.
+ */
+async function configuredCoverageThreshold(startDir) {
+    try {
+        const { findCIConfigFile, parseCIConfigFile } = await import('../../cli/utils/ci-config.js');
+        const configPath = findCIConfigFile(startDir);
+        if (!configPath)
+            return undefined;
+        const parsed = parseCIConfigFile(configPath);
+        return parsed.success ? parsed.config?.qualityGate.thresholds.coverage : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * #996: coverage limit for measured failures — the request's threshold, else
+ * the configured gate threshold, else the canonical default (undefined).
+ */
+async function coverageOverrideFor(payload) {
+    const requested = payload.thresholdSource === 'default' ? undefined : payload.threshold;
+    if (requested !== undefined && (typeof requested !== 'number' || !Number.isFinite(requested)
+        || requested < 0 || requested > 100)) {
+        throw new CallerInputError('threshold must be a finite number between 0 and 100.');
+    }
+    return resolveCoverageOverride(requested, requested === undefined ? await configuredCoverageThreshold(process.cwd()) : undefined);
+}
 export function registerQualityHandlers(ctx) {
     // Register quality assessment handler - REAL IMPLEMENTATION
     ctx.registerHandler('assess-quality', async (task) => {
@@ -15,74 +153,112 @@ export function registerQualityHandlers(ctx) {
         try {
             // An explicit gate evaluates the same measured, timestamped evidence as
             // `aqe quality --gate`. Static source scores cannot substitute for it.
+            // Missing/stale/malformed evidence throws InsufficientQualityEvidenceError,
+            // whose details (status, unmeasured) travel with the failure.
             if (payload.runGate === true) {
                 const measured = await loadQualityEvidence(ctx.memory);
                 return ok({
                     ...evaluateQualityEvidence(measured),
                     metrics: measured,
+                    evidenceStatus: 'measured',
+                    unmeasured: [],
+                    gateEvaluated: true,
                 });
             }
+            const requestedMetrics = requestedMetricsFrom(payload.metrics);
+            const coverageOverride = await coverageOverrideFor(payload);
             const analyzer = ctx.getQualityAnalyzer();
             const threshold = payload.threshold || 80;
-            // Determine source files to analyze
-            let sourceFiles = [];
-            if (payload.sourceFiles && payload.sourceFiles.length > 0) {
-                sourceFiles = payload.sourceFiles;
-            }
-            else if (payload.target) {
-                sourceFiles = await discoverSourceFiles(payload.target, { includeTests: false });
-            }
-            else {
-                // Default to src/ — scanning the entire project root is too slow
-                // (node_modules, dist, .git, etc. make it hang on large projects)
-                const path = await import('path');
-                const fs = await import('fs');
-                const srcDir = path.join(process.cwd(), 'src');
-                const targetDir = fs.existsSync(srcDir) ? srcDir : process.cwd();
-                sourceFiles = await discoverSourceFiles(targetDir, { includeTests: false });
-            }
+            // #1021 (B2): analyse what the caller scoped, contained in the project root.
+            const { sourceFiles, explicitFiles, scope } = await resolveAnalysisScope(payload);
             if (sourceFiles.length === 0) {
+                // Nothing was analyzed: every requested metric is unmeasured (#996).
                 return ok({
-                    qualityScore: 0,
+                    // #1011: nothing was analysed, so there is no score (-1), not a score of 0.
+                    qualityScore: UNMEASURED,
                     passed: false,
                     threshold,
                     metrics: {
-                        coverage: 0,
-                        complexity: 0,
-                        maintainability: 0,
-                        testability: 0,
+                        coverage: UNMEASURED,
+                        complexity: UNMEASURED,
+                        maintainability: UNMEASURED,
+                        testability: UNMEASURED,
                     },
-                    recommendations: ['No source files found for quality assessment'],
+                    recommendations: [
+                        ...describeMissingMetrics(requestedMetrics),
+                        'No source files found for quality assessment',
+                    ],
                     warning: 'No source files found',
+                    evidenceStatus: INSUFFICIENT_EVIDENCE,
+                    unmeasured: requestedMetrics,
+                    unmeasuredReasons: Object.fromEntries(requestedMetrics.map((m) => [m, 'no source files found to analyse'])),
+                    measuredFailures: [],
+                    gateEvaluated: false,
+                    confidence: 0,
+                    note: STATIC_ONLY_NOTE,
                 });
             }
             // Use the real QualityAnalyzerService
             const result = await analyzer.analyzeQuality({
                 sourceFiles,
-                includeMetrics: payload.metrics || ['coverage', 'complexity', 'maintainability', 'testability'],
+                includeMetrics: requestedMetrics,
+                explicitFiles,
             });
             if (!result.success) {
                 return result;
             }
             const report = result.value;
-            const passed = report.score.overall >= threshold;
-            // Convert metrics to the expected format
+            // Only metrics the analyzer actually computed count as measured; score
+            // fields carry the -1 sentinel for the rest.
             const metrics = {};
             for (const metric of report.metrics) {
                 metrics[metric.name] = metric.value;
             }
+            // #996: never pass on missing data. A static score computed without a
+            // requested metric (e.g. coverage = -1) is not evidence of quality, and
+            // a measured metric that fails its own limit blocks regardless (N2).
+            const sufficiency = assessEvidenceSufficiency(requestedMetrics, metrics);
+            const measuredFailures = findMeasuredFailures(sufficiency.measured, metrics, { coverage: coverageOverride });
+            const insufficient = sufficiency.evidenceStatus !== 'measured';
+            const passed = !insufficient && measuredFailures.length === 0 && report.score.overall >= threshold;
+            const recommendations = report.recommendations.map(r => `[${r.type}] ${r.title}: ${r.description}`);
             return ok({
                 qualityScore: report.score.overall,
                 passed,
                 threshold,
                 metrics: {
-                    coverage: report.score.coverage,
-                    complexity: report.score.complexity,
-                    maintainability: report.score.maintainability,
-                    security: report.score.security,
+                    coverage: sentinel(metrics.coverage),
+                    complexity: sentinel(metrics.complexity),
+                    maintainability: sentinel(metrics.maintainability),
+                    // The analyzer has no security measurement; never report a placeholder.
+                    security: sentinel(metrics.security),
+                    // #1011: every requested metric appears, -1 when unmeasured.
+                    ...Object.fromEntries(requestedMetrics.map((name) => [name, sentinel(metrics[name])])),
                     ...metrics,
                 },
-                recommendations: report.recommendations.map(r => `[${r.type}] ${r.title}: ${r.description}`),
+                unmeasuredReasons: unmeasuredReasons(sufficiency.unmeasured, report.unmeasured),
+                // #1021 round 2b: a score over a subset of the requested metrics (or over
+                // part of the files) names what it is based on — it is not a verdict.
+                ...(insufficient || (report.partial?.length ?? 0) > 0
+                    ? { scoreBasis: report.metrics.map((m) => m.name) }
+                    : {}),
+                recommendations: [
+                    ...measuredFailures.map(describeMeasuredFailure),
+                    ...describeMissingMetrics(sufficiency.unmeasured),
+                    ...describePartialMetrics(report.partial),
+                    ...recommendations,
+                ],
+                ...(report.partial && report.partial.length > 0 ? { partialMetrics: report.partial } : {}),
+                ...(report.excluded && report.excluded.length > 0
+                    ? { excludedFiles: report.excluded.slice(0, MAX_EXCLUDED_LISTED), excludedCount: report.excluded.length }
+                    : {}),
+                scope,
+                evidenceStatus: sufficiency.evidenceStatus,
+                unmeasured: sufficiency.unmeasured,
+                measuredFailures,
+                gateEvaluated: false,
+                confidence: sufficiency.confidence,
+                note: STATIC_ONLY_NOTE,
                 trends: report.trends.map(t => ({
                     metric: t.metric,
                     direction: t.direction,

package/dist/coordination/handlers/test-execution-handlers.js

@@ -222,7 +222,10 @@ export function registerTestExecutionHandlers(ctx) {
                         const executionError = getTestRunnerExecutionError(runner, testFiles.join(', '), execution.status, { passed, failed, skipped }, diagnostics, json);
                         if (executionError)
                             return err(executionError);
-                        return ok({ total, passed, failed, skipped, duration: 0, coverage: 0, failedTests: [] });
+                        // #1027 N5/NB5: this handler runs the tests without --coverage, so it has no
+                        // coverage figure to return (null, never 0%). For test_execute_parallel the
+                        // measured coverage + testsPassing are recorded by TestExecutorService.
+                        return ok({ total, passed, failed, skipped, duration: 0, coverage: null, failedTests: [] });
                     }
                 }
             }

package/dist/coordination/protocols/defect-investigation.d.ts

@@ -64,7 +64,8 @@ export interface RelatedFailure {
 export interface CoverageContext {
     file: string;
     lineCoverage: number;
-    branchCoverage: number;
+    /** `null` = no branch data was collected (#1027 NB4) — never a borrowed figure. */
+    branchCoverage: number | null;
     uncoveredLines: number[];
     riskScore: number;
 }

package/dist/coordination/protocols/defect-investigation.js

@@ -12,6 +12,7 @@ import { createEvent } from '../../shared/events/domain-events.js';
 import { toError } from '../../shared/error-utils.js';
 import { LoggerFactory } from '../../logging/index.js';
 import { addToCount } from '../../shared/utils/safe-record.js';
+import { measuredFileCoverage } from '../../domains/quality-assessment/coverage-report-event.js';
 const logger = LoggerFactory.create('defect-investigation');
 export const DefectInvestigationEvents = {
     DefectInvestigationStarted: 'coordination.DefectInvestigationStarted',
@@ -605,12 +606,14 @@ export class DefectInvestigationProtocol {
     async getCoverageContext(file) {
         try {
             // Try per-file coverage (written by coverage-analyzer and test-executor)
-            const coverage = await this.memory.get(`coverage:file:${file}`);
+            // #1014: only measured records; legacy unstamped estimates are ignored.
+            const coverage = measuredFileCoverage(await this.memory.get(`coverage:file:${file}`));
             if (!coverage) {
                 return null;
             }
-            // Calculate risk based on coverage
-            const avgCoverage = (coverage.line + coverage.branch) / 2;
+            // Calculate risk based on coverage (an uncollected branch metric is
+            // left out, not counted as 0%).
+            const avgCoverage = coverage.branch === null ? coverage.line : (coverage.line + coverage.branch) / 2;
             const riskScore = 1 - avgCoverage / 100;
             return {
                 file,

package/dist/coordination/protocols/quality-gate.js

@@ -10,6 +10,7 @@ import { v4 as uuidv4 } from 'uuid';
 import { ok, err, } from '../../shared/types/index.js';
 import { createEvent } from '../../shared/events/domain-events.js';
 import { toErrorMessage, toError } from '../../shared/error-utils.js';
+import { measuredCoverageSummary } from '../../domains/quality-assessment/coverage-report-event.js';
 // ============================================================================
 // Protocol Events
 // ============================================================================
@@ -402,12 +403,14 @@ export class QualityGateProtocol {
     async getCoverageMetrics(_releaseCandidate) {
         try {
             // Try to get latest coverage data from memory
-            const latestCoverage = await this.memory.get('coverage:latest');
+            // #1014: only a measured record is coverage evidence; a legacy
+            // unstamped or estimated record is "no data" (the gate fails closed).
+            const latestCoverage = measuredCoverageSummary(await this.memory.get('coverage:latest'));
             if (!latestCoverage) {
                 return null;
             }
-            // Get previous coverage for trend
-            const previousCoverage = await this.memory.get('coverage:previous');
+            // Get previous coverage for trend (measured baselines only, #1015)
+            const previousCoverage = measuredCoverageSummary(await this.memory.get('coverage:previous'));
             let trend = 'stable';
             if (previousCoverage) {
                 const delta = latestCoverage.line - previousCoverage.line;
@@ -418,9 +421,10 @@ export class QualityGateProtocol {
             }
             return {
                 line: latestCoverage.line,
-                branch: latestCoverage.branch,
-                function: latestCoverage.function,
-                statement: latestCoverage.statement,
+                // An uncollected metric has no evidence: 0 fails its check closed.
+                branch: latestCoverage.branch ?? 0,
+                function: latestCoverage.function ?? 0,
+                statement: latestCoverage.statement ?? 0,
                 trend,
             };
         }

package/dist/coordination/result-saver.d.ts

@@ -49,6 +49,11 @@ export interface TrendData {
 export declare class ResultSaver {
     private readonly baseDir;
     private readonly resultsDir;
+    /**
+     * @param baseDir Store directory. Defaults to the resolved project's
+     * `.agentic-qe` (review of #1026 N2: a cwd-relative default wrote
+     * `<tmp>/.agentic-qe/results` when run from a shared dir).
+     */
     constructor(baseDir?: string);
     /**
      * Save task result in appropriate format(s)
@@ -71,12 +76,29 @@ export declare class ResultSaver {
     private generateSecurityReport;
     private generateQualityReport;
     private ensureDirectories;
+    /** `YYYY-MM-DDTHH-MM-SS-mmm` (#1007: milliseconds, not seconds). */
     private formatTimestamp;
+    /** Short task-id fragment plus random hex, unique per save. */
+    private uniqueSuffix;
+    /** Write `filePath` via a temp file and rename, replacing any previous version. */
+    private replaceFile;
+    /**
+     * Create `filePath` exclusively and record it. If the name is taken (a
+     * reused custom prefix), write to
+     * `name-1.ext`, `name-2.ext`, … instead of replacing the earlier file (#1007).
+     */
+    private writeNewFile;
     private sanitizeFilename;
     private getTestExtension;
     private createFileEntry;
     private extractSummary;
+    /**
+     * Append to index.json. Concurrent saves read-modify-write the same file, so
+     * updates are serialized per index path in this process and the file is
+     * replaced atomically, otherwise one save's entry is lost (#1007).
+     */
     private updateIndex;
+    private writeIndexEntry;
 }
 export declare function createResultSaver(baseDir?: string): ResultSaver;
 //# sourceMappingURL=result-saver.d.ts.map