agentic-qe 3.15.5 → 3.15.7

package/dist/domains/quality-assessment/interfaces.d.ts

@@ -56,6 +56,10 @@ export interface GateResult {
     checks: GateCheck[];
     overallScore: number;
     failedChecks: string[];
+    /** Gate service evidence state; absent for other gate implementations. */
+    evidenceStatus?: 'measured' | 'insufficient-evidence';
+    /** Configured checks whose input was missing, negative, or non-finite. */
+    unmeasured?: string[];
 }
 export interface GateCheck {
     name: string;
@@ -68,6 +72,11 @@ export interface QualityAnalysisRequest {
     sourceFiles: string[];
     includeMetrics: string[];
     compareBaseline?: string;
+    /**
+     * #1021: files the caller named explicitly. If one of them fails to read or
+     * parse, the affected metrics are unmeasured regardless of coverage of scope.
+     */
+    explicitFiles?: string[];
 }
 export interface QualityReport {
     score: QualityScore;
@@ -76,6 +85,43 @@ export interface QualityReport {
     recommendations: Recommendation[];
     /** ADR-051: Optional LLM-generated insights (when enableLLMInsights is true) */
     llmInsights?: LLMQualityInsights;
+    /**
+     * #1011: requested metrics that were NOT measured, with the reason. They are
+     * absent from `metrics` and -1 in `score`; never a fixed fallback value.
+     */
+    unmeasured?: UnmeasuredQualityMetric[];
+    /**
+     * #1021: files left out of the scope (binary, generated, minified, type
+     * declarations, refused by the reader's path policy). Metrics stay measured
+     * over the remaining files.
+     */
+    excluded?: ExcludedQualityFile[];
+    /**
+     * #1021: metrics measured over most, but not all, analysable files. Their
+     * value covers `analysedFiles` of `totalFiles`; `failed` lists the gaps.
+     */
+    partial?: PartialQualityMetric[];
+}
+/** #1021: a file excluded from static analysis, with the reason. */
+export interface ExcludedQualityFile {
+    file: string;
+    reason: string;
+}
+/** #1021: a metric measured over part of its scope. */
+export interface PartialQualityMetric {
+    metric: string;
+    analysedFiles: number;
+    totalFiles: number;
+    /** analysedFiles / totalFiles, three decimals, rounded down (never 1 while a file failed). */
+    coverageOfScope: number;
+    failed: ExcludedQualityFile[];
+}
+/** #1011: a requested metric the static analysis could not measure. */
+export interface UnmeasuredQualityMetric {
+    metric: string;
+    reason: string;
+    /** Files that could not be analysed, when the cause is file-specific. */
+    files?: string[];
 }
 /**
  * ADR-051: LLM-generated quality insights
@@ -140,13 +186,17 @@ export interface ComplexityReport {
     summary: ComplexitySummary;
     hotspots: ComplexityHotspot[];
 }
+/** Values are -1 when not measured (not requested, or the file could not be analysed). */
 export interface FileComplexity {
     path: string;
     cyclomatic: number;
     cognitive: number;
     maintainability: number;
     linesOfCode: number;
+    /** #1011: why this file's metrics are unmeasured (unreadable, binary, unparseable). */
+    unmeasuredReason?: string;
 }
+/** Averages over measured files only; -1 when no file was measured for that metric. */
 export interface ComplexitySummary {
     averageCyclomatic: number;
     averageCognitive: number;

package/dist/domains/quality-assessment/quality-evidence.d.ts

@@ -10,6 +10,20 @@ export interface QualityEvidenceRecord {
     value: number;
     measuredAt: string;
     source: string;
+    /**
+     * The test run this figure came from, when it came from one (#1027 NB1).
+     * Coverage and testsPassing written from one run share the runId.
+     */
+    runId?: string;
+    /** Whether that run's tests passed (#1027 NB1). */
+    runStatus?: 'passed' | 'failed';
+}
+/** Metadata of an evidence write; `runId`/`runStatus` scope it to one test run. */
+export interface QualityEvidenceMetadata {
+    measuredAt: string;
+    source: string;
+    runId?: string;
+    runStatus?: 'passed' | 'failed';
 }
 export interface QualityThreshold {
     direction: 'min' | 'max';
@@ -25,9 +39,31 @@ export interface EvaluatedQualityCheck {
     direction: 'min' | 'max';
     severity: QualityThreshold['severity'];
 }
-export declare function writeQualityEvidence(memory: MemoryBackend, values: Partial<QualityEvidenceValues>, metadata: {
-    measuredAt: string;
+export declare function writeQualityEvidence(memory: MemoryBackend, values: Partial<QualityEvidenceValues>, metadata: QualityEvidenceMetadata): Promise<void>;
+/** Test counts of one run. */
+export interface TestRunCounts {
+    passed: number;
+    failed: number;
+    skipped?: number;
+}
+/**
+ * testsPassing as `aqe test execute` has always computed it: passed over all
+ * tests, skipped included; a run with no tests is 0 (#1027 NB1: one formula).
+ */
+export declare function testsPassingPercent(run: TestRunCounts): number;
+/**
+ * Record the evidence of ONE test run (#1027 NB1): its testsPassing and, when
+ * it measured coverage, its coverage — both stamped with the same runId and
+ * runStatus. The single writer for `aqe test execute`, test_execute_parallel
+ * (TestExecutorService) and the coverage auto-run, so coverage from a failing
+ * run can never sit next to a stale testsPassing from an earlier run.
+ */
+export declare function writeTestRunEvidence(memory: MemoryBackend, run: TestRunCounts & {
+    runId: string;
+}, options: {
     source: string;
+    coverage?: number;
+    measuredAt?: string;
 }): Promise<void>;
 /** #996: the single status word for "a verdict cannot be reached on this evidence". */
 export declare const INSUFFICIENT_EVIDENCE: "insufficient-evidence";
@@ -62,13 +98,23 @@ export declare class InsufficientQualityEvidenceError extends Error {
  * Inspect every canonical metric with the same validation, collecting each
  * absent, stale, future-dated or malformed record instead of stopping at the first.
  */
-export declare function inspectQualityEvidence(memory: MemoryBackend, options?: {
+export declare function inspectQualityEvidence(memory: Pick<MemoryBackend, 'get'>, options?: {
     now?: number;
     maxAgeMs?: number;
 }): Promise<{
     values: Partial<QualityEvidenceValues>;
     problems: UnusableQualityEvidence[];
 }>;
+/**
+ * #1028: the latest record of ONE metric when it is usable evidence — the same
+ * validation (schema, metric, finite value, source, fresh measuredAt) the gate
+ * applies — or `null`. Unlike {@link inspectQualityEvidence} it returns the
+ * record, so a reader can follow its `runId` to the run it came from.
+ */
+export declare function readQualityEvidenceRecord(memory: Pick<MemoryBackend, 'get'>, metric: QualityMetricName, options?: {
+    now?: number;
+    maxAgeMs?: number;
+}): Promise<QualityEvidenceRecord | null>;
 export declare function loadQualityEvidence(memory: MemoryBackend, options?: {
     now?: number;
     maxAgeMs?: number;

package/dist/domains/quality-assessment/quality-evidence.js

@@ -71,6 +71,8 @@ export async function writeQualityEvidence(memory, values, metadata) {
             value,
             measuredAt: metadata.measuredAt,
             source: metadata.source,
+            ...(metadata.runId ? { runId: metadata.runId } : {}),
+            ...(metadata.runStatus ? { runStatus: metadata.runStatus } : {}),
         };
         await memory.set(evidenceKey(metric), record, {
             namespace: QUALITY_EVIDENCE_NAMESPACE,
@@ -78,6 +80,34 @@ export async function writeQualityEvidence(memory, values, metadata) {
         });
     }
 }
+/**
+ * testsPassing as `aqe test execute` has always computed it: passed over all
+ * tests, skipped included; a run with no tests is 0 (#1027 NB1: one formula).
+ */
+export function testsPassingPercent(run) {
+    const total = run.passed + run.failed + (run.skipped ?? 0);
+    return total > 0 ? (run.passed / total) * 100 : 0;
+}
+/**
+ * Record the evidence of ONE test run (#1027 NB1): its testsPassing and, when
+ * it measured coverage, its coverage — both stamped with the same runId and
+ * runStatus. The single writer for `aqe test execute`, test_execute_parallel
+ * (TestExecutorService) and the coverage auto-run, so coverage from a failing
+ * run can never sit next to a stale testsPassing from an earlier run.
+ */
+export async function writeTestRunEvidence(memory, run, options) {
+    const runStatus = run.failed > 0 ? 'failed' : 'passed';
+    const metadata = {
+        measuredAt: options.measuredAt ?? new Date().toISOString(),
+        source: options.source,
+        runId: run.runId,
+        runStatus,
+    };
+    await writeQualityEvidence(memory, {
+        testsPassing: testsPassingPercent(run),
+        ...(typeof options.coverage === 'number' && Number.isFinite(options.coverage) ? { coverage: options.coverage } : {}),
+    }, metadata);
+}
 /** #996: the single status word for "a verdict cannot be reached on this evidence". */
 export const INSUFFICIENT_EVIDENCE = 'insufficient-evidence';
 /** #996: what to run to measure a metric that has no usable evidence. */
@@ -141,6 +171,7 @@ export async function inspectQualityEvidence(memory, options = {}) {
     const maxAgeMs = options.maxAgeMs ?? DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS;
     const values = {};
     const problems = [];
+    const valid = {};
     for (const metric of QUALITY_METRICS) {
         const record = await memory.get(evidenceKey(metric), {
             namespace: QUALITY_EVIDENCE_NAMESPACE,
@@ -148,13 +179,44 @@ export async function inspectQualityEvidence(memory, options = {}) {
         try {
             validateRecord(record, metric, now, maxAgeMs);
             values[metric] = record.value;
+            valid[metric] = record;
         }
         catch (error) {
             problems.push({ metric, reason: error instanceof Error ? error.message : String(error) });
         }
     }
+    // #1027 NB1: coverage measured in a run whose tests FAILED is evidence only
+    // next to the testsPassing of that same run — never next to a stale figure
+    // from an earlier (passing) run, which would let the gate pass.
+    const coverage = valid.coverage;
+    if (coverage?.runStatus === 'failed' && (!coverage.runId || valid.testsPassing?.runId !== coverage.runId)) {
+        delete values.coverage;
+        problems.push({
+            metric: 'coverage',
+            reason: 'Measured coverage comes from a run with failing tests, but no testsPassing evidence '
+                + 'from that same run was recorded. Re-run the test suite.',
+        });
+    }
     return { values, problems };
 }
+/**
+ * #1028: the latest record of ONE metric when it is usable evidence — the same
+ * validation (schema, metric, finite value, source, fresh measuredAt) the gate
+ * applies — or `null`. Unlike {@link inspectQualityEvidence} it returns the
+ * record, so a reader can follow its `runId` to the run it came from.
+ */
+export async function readQualityEvidenceRecord(memory, metric, options = {}) {
+    const record = await memory.get(evidenceKey(metric), {
+        namespace: QUALITY_EVIDENCE_NAMESPACE,
+    });
+    try {
+        validateRecord(record, metric, options.now ?? Date.now(), options.maxAgeMs ?? DEFAULT_QUALITY_EVIDENCE_MAX_AGE_MS);
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
 export async function loadQualityEvidence(memory, options = {}) {
     const { values, problems } = await inspectQualityEvidence(memory, options);
     if (problems.length > 0)

package/dist/domains/quality-assessment/services/quality-analyzer.d.ts

@@ -3,8 +3,9 @@
  * Comprehensive quality metrics analysis with trends and recommendations
  */
 import { Result, QualityScore } from '../../../shared/types';
+import { CodeMetricsAnalyzer } from '../../../shared/metrics';
 import { MemoryBackend } from '../../../kernel/interfaces';
-import { QualityAnalysisRequest, QualityReport, QualityMetricDetail, QualityTrend, ComplexityRequest, ComplexityReport, LLMQualityInsights } from '../interfaces';
+import { QualityAnalysisRequest, QualityReport, QualityMetricDetail, QualityTrend, ComplexityRequest, ComplexityReport, LLMQualityInsights, UnmeasuredQualityMetric } from '../interfaces';
 import type { HybridRouter } from '../../../shared/llm';
 /**
  * Interface for the quality analyzer service
@@ -49,7 +50,17 @@ export interface QualityAnalyzerDependencies {
     memory: MemoryBackend;
     /** ADR-051: Optional LLM router for AI-enhanced quality insights */
     llmRouter?: HybridRouter;
+    /** Code metrics analyzer (defaults to the shared instance). */
+    metricsAnalyzer?: CodeMetricsAnalyzer;
 }
+/**
+ * #1021: a parsed metric with read/parse failures is still evidence when at
+ * least this share of the analysable files (in-scope minus excluded) was
+ * analysed. Below it, the unseen files are too large a blind spot for an
+ * average to describe the target, so the metric is unmeasured. 95% keeps one
+ * failure in a 20-file scope acceptable but not one in 10.
+ */
+export declare const MIN_ANALYSED_SHARE = 0.95;
 export declare class QualityAnalyzerService implements IQualityAnalyzerService {
     private readonly config;
     private readonly metricsAnalyzer;
@@ -75,7 +86,7 @@ export declare class QualityAnalyzerService implements IQualityAnalyzerService {
      * Generate quality insights using LLM
      * Provides AI-powered explanation and prioritized recommendations
      */
-    generateQualityInsightsWithLLM(metrics: QualityMetricDetail[], score: QualityScore, codeContext?: string): Promise<LLMQualityInsights | null>;
+    generateQualityInsightsWithLLM(metrics: QualityMetricDetail[], score: QualityScore, codeContext?: string, unmeasured?: UnmeasuredQualityMetric[]): Promise<LLMQualityInsights | null>;
     /**
      * Build prompt for quality insights generation
      */
@@ -104,6 +115,16 @@ export declare class QualityAnalyzerService implements IQualityAnalyzerService {
      * Get quality trend for a specific metric
      */
     getQualityTrend(metric: string, days: number): Promise<Result<QualityTrend, Error>>;
+    /**
+     * Collect per-file metric values. #1011 / #1021:
+     * - excluded files (binary, generated, minified, declarations, refused by
+     *   reader policy) leave the scope with a reason;
+     * - failed files (unreadable, unparseable) make a parsed metric partial, or
+     *   unmeasured below MIN_ANALYSED_SHARE or when a failed file was named
+     *   explicitly;
+     * - failed duplication detection and missing coverage are unmeasured.
+     * Never a fixed fallback value.
+     */
     private collectFileMetrics;
     private getStoredCoverage;
     private aggregateMetrics;