agentic-qe 3.15.5 → 3.15.6

package/dist/shared/aqe-managed-dirs.js

@@ -0,0 +1,56 @@
+/**
+ * AQE-managed directories that source walkers must not treat as project code
+ * (#999, review N4 / round 2b).
+ *
+ *  - `.agentic-qe/` is AQE runtime state (workers, results, DBs) at ANY depth;
+ *    it is never source.
+ *  - `.claude/` holds the assets `aqe init` writes (helpers, skills, agents).
+ *    It is AQE-managed at the walk root, and nested only when it sits next to
+ *    a `.agentic-qe/` (a nested `aqe init` in a monorepo package). A nested
+ *    `.claude/` with no AQE install beside it (e.g. a Claude Code plugin's own
+ *    `.claude/hooks/*.ts`) is the package's source and is walked.
+ */
+import { existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+export const AQE_STATE_DIR = '.agentic-qe';
+export const AQE_CLAUDE_DIR = '.claude';
+/** True when directory `name` inside `parentDir` is AQE-managed (never project source). */
+export function isAqeManagedDir(parentDir, name, isWalkRoot) {
+    if (name === AQE_STATE_DIR)
+        return true;
+    if (name === AQE_CLAUDE_DIR)
+        return isWalkRoot || existsSync(join(parentDir, AQE_STATE_DIR));
+    return false;
+}
+/**
+ * Root-relative ('/'-separated) paths of the AQE-managed `.claude` directories
+ * under `projectRoot`: the root one (if present) and every `.claude` that has a
+ * sibling `.agentic-qe`. Used to anchor cloc/tokei excludes. Bounded walk that
+ * skips `skipDirs` and dot-directories.
+ */
+export function findAqeClaudeDirs(projectRoot, skipDirs = [], maxDepth = 12) {
+    const skip = new Set(skipDirs);
+    const found = [];
+    const walk = (dir, rel, depth) => {
+        if (existsSync(join(dir, AQE_CLAUDE_DIR)) && (depth === 0 || existsSync(join(dir, AQE_STATE_DIR)))) {
+            found.push(rel ? `${rel}/${AQE_CLAUDE_DIR}` : AQE_CLAUDE_DIR);
+        }
+        if (depth >= maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || skip.has(entry.name))
+                continue;
+            walk(join(dir, entry.name), rel ? `${rel}/${entry.name}` : entry.name, depth + 1);
+        }
+    };
+    walk(projectRoot, '', 0);
+    return found;
+}
+//# sourceMappingURL=aqe-managed-dirs.js.map

package/dist/shared/events/domain-events.d.ts

@@ -54,10 +54,15 @@ export declare const TestExecutionEvents: {
 export interface CoverageReportPayload {
     reportId: string;
     line: number;
-    branch: number;
-    function: number;
-    statement: number;
+    /** `null` = the report collected no branch data (not 0%, #1027). */
+    branch: number | null;
+    /** `null` = the report collected no function data (not 0%, #1027). */
+    function: number | null;
+    /** `null` = the report collected no statement data (lcov, Cobertura). */
+    statement: number | null;
     files: number;
+    /** Outcome of the test run behind the report, when known (#1027 N4). */
+    runStatus?: 'passed' | 'failed';
     /** False for a static estimate; consumers must not store it as coverage (#1008). */
     measured?: boolean;
 }
@@ -67,7 +72,17 @@ export interface CoverageGapPayload {
     uncoveredLines: number[];
     uncoveredBranches: number[];
     riskScore: number;
+    /**
+     * Provenance (#1014): true only for a gap found in MEASURED coverage. Gaps
+     * from a static estimate are never published; consumers must ignore any
+     * event without `measured: true` (legacy or foreign publishers).
+     */
+    measured: boolean;
+    /** How the underlying coverage was obtained, e.g. 'instrumented-report'. */
+    coverageMethod?: string;
 }
+/** Is this CoverageGapDetected payload a gap in measured coverage? (#1014, fail-closed) */
+export declare function isMeasuredGapPayload(payload: unknown): boolean;
 export declare const CoverageAnalysisEvents: {
     readonly CoverageReportCreated: "coverage-analysis.CoverageReportCreated";
     readonly CoverageGapDetected: "coverage-analysis.CoverageGapDetected";

package/dist/shared/events/domain-events.js

@@ -28,6 +28,10 @@ export const TestExecutionEvents = {
     FlakyTestDetected: 'test-execution.FlakyTestDetected',
     RetryTriggered: 'test-execution.RetryTriggered',
 };
+/** Is this CoverageGapDetected payload a gap in measured coverage? (#1014, fail-closed) */
+export function isMeasuredGapPayload(payload) {
+    return !!payload && typeof payload === 'object' && payload.measured === true;
+}
 export const CoverageAnalysisEvents = {
     CoverageReportCreated: 'coverage-analysis.CoverageReportCreated',
     CoverageGapDetected: 'coverage-analysis.CoverageGapDetected',

package/dist/shared/http/http-client.d.ts

@@ -5,6 +5,12 @@
 import { Result } from '../types';
 export interface RequestOptions {
     timeout?: number;
+    /**
+     * Absolute cap on the whole request including the body read (#980 review N6).
+     * `timeout` is an idle deadline for the body, so this bounds a peer that trickles
+     * bytes just often enough to reset it. Default: MAX_DURATION_TIMEOUT_MULTIPLE × timeout.
+     */
+    maxDurationMs?: number;
     retries?: number;
     retryDelay?: number;
     headers?: Record<string, string>;

package/dist/shared/http/http-client.js

@@ -4,10 +4,13 @@
  */
 import { ok, err } from '../types/index.js';
 import { toError } from '../error-utils.js';
+import { fetchWithResponseDeadline } from '../llm/providers/response-deadline.js';
 // ============================================================================
 // Constants
 // ============================================================================
 const DEFAULT_TIMEOUT = 30000;
+/** Default absolute request cap as a multiple of the idle timeout (#980 review N6). */
+const MAX_DURATION_TIMEOUT_MULTIPLE = 4;
 const DEFAULT_RETRIES = 3;
 const DEFAULT_RETRY_DELAY = 1000;
 const CIRCUIT_BREAKER_THRESHOLD = 5;
@@ -170,6 +173,7 @@ export class HttpClient {
      */
     async request(url, fetchOptions, options) {
         const timeout = options?.timeout ?? DEFAULT_TIMEOUT;
+        const maxDurationMs = options?.maxDurationMs ?? timeout * MAX_DURATION_TIMEOUT_MULTIPLE;
         const maxRetries = options?.retries ?? DEFAULT_RETRIES;
         const baseRetryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
         const useCircuitBreaker = options?.circuitBreaker ?? true;
@@ -198,7 +202,7 @@ export class HttpClient {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             timing.retryCount = attempt;
             try {
-                const response = await this.fetchWithTimeout(url, { ...fetchOptions, headers }, timeout);
+                const response = await this.fetchWithTimeout(url, { ...fetchOptions, headers }, timeout, maxDurationMs);
                 timing.endTime = Date.now();
                 timing.duration = timing.endTime - timing.startTime;
                 // Record success for circuit breaker
@@ -233,19 +237,13 @@ export class HttpClient {
     /**
      * Fetch with timeout using AbortController
      */
-    async fetchWithTimeout(url, options, timeout) {
-        const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), timeout);
-        try {
-            const response = await fetch(url, {
-                ...options,
-                signal: controller.signal,
-            });
-            return response;
-        }
-        finally {
-            clearTimeout(timeoutId);
-        }
+    async fetchWithTimeout(url, options, timeout, maxDurationMs) {
+        // #980 bug class: the timer used to be cleared as soon as headers arrived,
+        // so callers reading the body of a peer that stalls mid-body hung forever.
+        // The deadline now also covers the body, as an idle deadline (reset on
+        // every chunk) so slow but progressing downloads keep working, plus an
+        // absolute cap (maxDurationMs) so a trickling peer cannot hold it forever.
+        return fetchWithResponseDeadline(url, options, timeout, () => Object.assign(new Error(`Request timeout (idle ${timeout}ms, cap ${maxDurationMs}ms): ${url}`), { name: 'TimeoutError' }), 'idle', maxDurationMs);
     }
     /**
      * Determine error code from error type
@@ -261,7 +259,7 @@ export class HttpClient {
         while (typeof current === 'object' && current !== null && !visited.has(current)) {
             visited.add(current);
             const detail = current;
-            if (detail.name === 'AbortError')
+            if (detail.name === 'AbortError' || detail.name === 'TimeoutError')
                 return 'TIMEOUT';
             const message = typeof detail.message === 'string' ? detail.message : '';
             if (detail.code === 'ECONNREFUSED' || message.includes('ECONNREFUSED'))

package/dist/shared/io/file-reader.d.ts

@@ -12,6 +12,15 @@ export interface FileReaderOptions {
     cacheTtlMs?: number;
     /** Whether to enable caching (default: true) */
     enableCache?: boolean;
+    /**
+     * Opt-in in-root containment for `readFile` (#1021). A path that resolves
+     * inside this directory is accepted when its realpath stays inside the
+     * root's realpath (a symlink escaping the root is rejected); the legacy
+     * name-pattern validator is not applied to it, so names such as
+     * `[...slug].tsx`, in-root dot-dirs and deep paths are readable. Paths
+     * outside the root keep every legacy check. Omit to keep legacy behaviour.
+     */
+    projectRoot?: string;
 }
 export interface CacheEntry<T> {
     value: T;
@@ -49,6 +58,8 @@ export declare class FileReader {
     private readonly basePath;
     private readonly cache;
     private readonly enableCache;
+    private readonly projectRoot?;
+    private projectRootReal?;
     private stats;
     constructor(options?: FileReaderOptions);
     /**
@@ -56,6 +67,21 @@ export declare class FileReader {
      * SEC-004 FIX: Validates path to prevent directory traversal attacks
      */
     private resolvePath;
+    /**
+     * #1021: decide whether a path is handled by in-root containment. Returns
+     * undefined when the path is not lexically inside the root (or no root is
+     * configured), so the caller applies the legacy checks.
+     */
+    private inProjectRoot;
+    /**
+     * #1021 round 2b: read an in-root path without a check-then-use race.
+     * The file is OPENED first and the open descriptor is verified — its real
+     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
+     * which must be the same inode) must lie inside the root — and the content
+     * is read from that same descriptor. Swapping a symlink (file or directory
+     * component) between the check and the read can no longer redirect it.
+     */
+    private readContained;
     /**
      * Read file contents as a string
      * SEC-004: Now handles PathTraversalError from path validation

package/dist/shared/io/file-reader.js

@@ -7,6 +7,8 @@ import * as path from 'node:path';
 import { ok, err } from '../types/index.js';
 import { validatePath } from '../security/path-traversal-validator.js';
 import { safeJsonParse } from '../safe-json.js';
+/** Extensions never read, inside or outside the project root. */
+const DENIED_EXTENSIONS = ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'];
 export class FileReadError extends Error {
     filePath;
     code;
@@ -44,6 +46,49 @@ export class PathTraversalError extends Error {
         this.name = 'PathTraversalError';
     }
 }
+/** Map a filesystem error to the reader's FileReadError. */
+function readError(error, absolutePath) {
+    const nodeError = error;
+    let message;
+    switch (nodeError.code) {
+        case 'ENOENT':
+            message = 'File not found: ' + absolutePath;
+            break;
+        case 'EACCES':
+            message = 'Permission denied: ' + absolutePath;
+            break;
+        case 'EISDIR':
+            message = 'Path is a directory: ' + absolutePath;
+            break;
+        default:
+            message = 'Failed to read file: ' + absolutePath;
+    }
+    return new FileReadError(message, absolutePath, nodeError.code, nodeError);
+}
+/**
+ * #1021 round 2b: where an OPEN descriptor really points. On Linux,
+ * /proc/self/fd/N resolves to the opened file itself. Elsewhere, re-resolve
+ * the path and accept it only if it is the same inode as the descriptor, so
+ * a swap after the open is detected. Returns null when it cannot be proven.
+ */
+async function openedLocation(fd, lexical, opened) {
+    const sameFile = async (candidate) => {
+        const st = await fs.stat(candidate).catch(() => null);
+        return st !== null && st.dev === opened.dev && st.ino === opened.ino;
+    };
+    const viaProc = await fs.realpath(`/proc/self/fd/${fd}`).catch(() => null);
+    if (viaProc && path.isAbsolute(viaProc) && await sameFile(viaProc))
+        return viaProc;
+    const real = await fs.realpath(lexical).catch(() => null);
+    if (real && await sameFile(real))
+        return real;
+    return null;
+}
+/** True when `candidate` is `root` or lies beneath it (both absolute). */
+function isWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
 // ============================================================================
 // LRU Cache Implementation
 // ============================================================================
@@ -215,6 +260,8 @@ export class FileReader {
     basePath;
     cache;
     enableCache;
+    projectRoot;
+    projectRootReal;
     stats = {
         cacheHits: 0,
         cacheMisses: 0,
@@ -225,6 +272,7 @@ export class FileReader {
     constructor(options = {}) {
         this.basePath = options.basePath ?? process.cwd();
         this.enableCache = options.enableCache ?? true;
+        this.projectRoot = options.projectRoot ? path.resolve(options.projectRoot) : undefined;
         this.cache = new LRUCache(options.maxCacheSize ?? 100, options.cacheTtlMs ?? 5 * 60 * 1000 // 5 minutes default
         );
     }
@@ -252,7 +300,7 @@ export class FileReader {
             allowAbsolute: true,
             maxDepth: 10 + (isAbsolutePath ? baseDepth : 0),
             // Allow common development file extensions
-            deniedExtensions: ['.exe', '.bat', '.cmd', '.ps1', '.dll', '.so'],
+            deniedExtensions: DENIED_EXTENSIONS,
         });
         if (!validation.valid) {
             throw new PathTraversalError(filePath, [validation.error || 'Path validation failed'], validation.riskLevel);
@@ -269,6 +317,64 @@ export class FileReader {
         }
         return path.resolve(this.basePath, filePath);
     }
+    /**
+     * #1021: decide whether a path is handled by in-root containment. Returns
+     * undefined when the path is not lexically inside the root (or no root is
+     * configured), so the caller applies the legacy checks.
+     */
+    async inProjectRoot(filePath) {
+        if (!this.projectRoot)
+            return undefined;
+        if (filePath.includes('\0')) {
+            throw new PathTraversalError(filePath, ['Null byte in path'], 'critical');
+        }
+        const lexical = path.resolve(this.basePath, filePath);
+        if (!isWithin(this.projectRoot, lexical))
+            return undefined;
+        if (DENIED_EXTENSIONS.includes(path.extname(lexical).toLowerCase())) {
+            throw new PathTraversalError(filePath, [`File extension '${path.extname(lexical)}' is not allowed`], 'high');
+        }
+        this.projectRootReal ??= fs.realpath(this.projectRoot).catch(() => null);
+        const rootReal = await this.projectRootReal;
+        if (!rootReal)
+            return undefined;
+        return { lexical, rootReal };
+    }
+    /**
+     * #1021 round 2b: read an in-root path without a check-then-use race.
+     * The file is OPENED first and the open descriptor is verified — its real
+     * location (/proc/self/fd/N on Linux; otherwise the re-resolved realpath,
+     * which must be the same inode) must lie inside the root — and the content
+     * is read from that same descriptor. Swapping a symlink (file or directory
+     * component) between the check and the read can no longer redirect it.
+     */
+    async readContained(filePath, lexical, rootReal) {
+        this.stats.totalReads++;
+        let handle;
+        try {
+            handle = await fs.open(lexical, 'r');
+        }
+        catch (error) {
+            return err(readError(error, lexical));
+        }
+        try {
+            const opened = await handle.stat();
+            const location = await openedLocation(handle.fd, lexical, opened);
+            if (!location || !isWithin(rootReal, location)) {
+                return err(new PathTraversalError(filePath, ['Path resolves outside the project root'], 'critical'));
+            }
+            if (!opened.isFile()) {
+                return err(new FileReadError('Path is a directory: ' + lexical, lexical, 'EISDIR'));
+            }
+            return ok(await handle.readFile('utf-8'));
+        }
+        catch (error) {
+            return err(readError(error, lexical));
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
     /**
      * Read file contents as a string
      * SEC-004: Now handles PathTraversalError from path validation
@@ -277,6 +383,9 @@ export class FileReader {
         let absolutePath;
         // SEC-004: Handle path traversal errors from resolvePath
         try {
+            const contained = await this.inProjectRoot(filePath);
+            if (contained)
+                return this.readContained(filePath, contained.lexical, contained.rootReal);
             absolutePath = this.resolvePath(filePath);
         }
         catch (error) {
@@ -306,22 +415,7 @@ export class FileReader {
             return ok(content);
         }
         catch (error) {
-            const nodeError = error;
-            let message;
-            switch (nodeError.code) {
-                case 'ENOENT':
-                    message = 'File not found: ' + absolutePath;
-                    break;
-                case 'EACCES':
-                    message = 'Permission denied: ' + absolutePath;
-                    break;
-                case 'EISDIR':
-                    message = 'Path is a directory: ' + absolutePath;
-                    break;
-                default:
-                    message = 'Failed to read file: ' + absolutePath;
-            }
-            return err(new FileReadError(message, absolutePath, nodeError.code, nodeError));
+            return err(readError(error, absolutePath));
         }
     }
     /**

package/dist/shared/llm/providers/response-deadline.d.ts

@@ -1,3 +1,8 @@
-/** Bound headers and bodies; streaming callers may use an idle body deadline. */
-export declare function fetchWithResponseDeadline(url: string, options: RequestInit, timeoutMs: number, timeoutError: () => Error, bodyDeadline?: 'absolute' | 'idle'): Promise<Response>;
+/**
+ * Bound headers and bodies; streaming callers may use an idle body deadline.
+ * `maxDurationMs` adds an absolute cap from the start of the request, so an
+ * idle deadline cannot be held open forever by a peer that trickles bytes
+ * just often enough to reset it (#980 review N6).
+ */
+export declare function fetchWithResponseDeadline(url: string, options: RequestInit, timeoutMs: number, timeoutError: () => Error, bodyDeadline?: 'absolute' | 'idle', maxDurationMs?: number): Promise<Response>;
 //# sourceMappingURL=response-deadline.d.ts.map

package/dist/shared/llm/providers/response-deadline.js

@@ -1,5 +1,10 @@
-/** Bound headers and bodies; streaming callers may use an idle body deadline. */
-export async function fetchWithResponseDeadline(url, options, timeoutMs, timeoutError, bodyDeadline = 'absolute') {
+/**
+ * Bound headers and bodies; streaming callers may use an idle body deadline.
+ * `maxDurationMs` adds an absolute cap from the start of the request, so an
+ * idle deadline cannot be held open forever by a peer that trickles bytes
+ * just often enough to reset it (#980 review N6).
+ */
+export async function fetchWithResponseDeadline(url, options, timeoutMs, timeoutError, bodyDeadline = 'absolute', maxDurationMs) {
     const abort = new AbortController();
     let expired = false;
     let expireBody;
@@ -10,6 +15,13 @@ export async function fetchWithResponseDeadline(url, options, timeoutMs, timeout
         abort.abort(error);
     };
     let timer = setTimeout(expire, timeoutMs);
+    const capTimer = maxDurationMs !== undefined && maxDurationMs > 0 ? setTimeout(expire, maxDurationMs) : undefined;
+    capTimer?.unref?.();
+    const clearTimers = () => {
+        clearTimeout(timer);
+        if (capTimer)
+            clearTimeout(capTimer);
+    };
     const resetIdleDeadline = () => {
         if (bodyDeadline !== 'idle')
             return;
@@ -22,7 +34,7 @@ export async function fetchWithResponseDeadline(url, options, timeoutMs, timeout
     try {
         const response = await fetch(url, { ...options, signal: abort.signal });
         if (!response.body) {
-            clearTimeout(timer);
+            clearTimers();
             return response;
         }
         resetIdleDeadline();
@@ -30,7 +42,7 @@ export async function fetchWithResponseDeadline(url, options, timeoutMs, timeout
         let finished = false;
         const finish = () => {
             finished = true;
-            clearTimeout(timer);
+            clearTimers();
         };
         const body = new ReadableStream({
             start(controller) {
@@ -90,7 +102,7 @@ export async function fetchWithResponseDeadline(url, options, timeoutMs, timeout
         return bounded;
     }
     catch (error) {
-        clearTimeout(timer);
+        clearTimers();
         if (expired || (error instanceof Error && error.name === 'AbortError')) {
             throw timeoutError();
         }

package/dist/shared/metrics/code-metrics.d.ts

@@ -36,6 +36,21 @@ export interface DuplicationResult {
     percentage: number;
     duplicates: DuplicateBlock[];
 }
+/**
+ * #1011 / #1021: how one file's analysis counts as evidence.
+ * - `measured`: real metrics.
+ * - `excluded`: not source to judge (binary, generated, minified, type
+ *   declarations, or refused by the reader's path policy) — leave it out.
+ * - `failed`: source that could not be read or parsed — a gap in the scope.
+ */
+export type FileAnalysisStatus = 'measured' | 'excluded' | 'failed';
+export interface FileAnalysisOutcome {
+    status: FileAnalysisStatus;
+    /** Metrics computed from the file; null when excluded or unreadable. */
+    metrics: FileMetrics | null;
+    /** Why the file is excluded or failed. */
+    reason?: string;
+}
 export interface DuplicateBlock {
     lines: number;
     occurrences: number;
@@ -53,6 +68,15 @@ export declare class CodeMetricsAnalyzer {
      * Analyze a single file for all metrics
      */
     analyzeFile(filePath: string): Promise<FileMetrics | null>;
+    /**
+     * #1011 / #1021: analyse a file and say whether its metrics are evidence.
+     * Binary, generated, minified and declaration files — and files the reader
+     * refuses by policy — are `excluded`; unreadable or unparseable source is
+     * `failed`. Callers must not treat either as a measurement.
+     */
+    analyzeFileDetailed(filePath: string): Promise<FileAnalysisOutcome>;
+    /** Compute metrics, reporting read errors and parse failures separately. */
+    private analyzeWithDiagnostics;
     /**
      * Analyze function-level metrics
      */

package/dist/shared/metrics/code-metrics.js

@@ -3,10 +3,53 @@
  * Real code analysis for complexity, maintainability, and quality metrics
  */
 import { TypeScriptParser } from '../parsers/index.js';
-import { FileReader } from '../io/index.js';
+import { FileReader, PathTraversalError } from '../io/index.js';
 import { treeSitterRegistry } from '../parsers/multi-language-parser.js';
 import { getLanguageFromExtension } from '../types/test-frameworks.js';
 import { calculateCognitiveComplexity } from './cognitive-complexity.js';
+import { findProjectRoot } from '../../kernel/project-root.js';
+/** git-style binary sniff: a NUL within the first 8 KB. */
+const BINARY_SNIFF_CHARS = 8192;
+/** How far into a file the generated-file conventions are looked for. */
+const GENERATED_SNIFF_CHARS = 1024;
+/** Go's convention (golang.org/s/generatedcode), one full line. */
+const GO_GENERATED_LINE = /^\/\/ Code generated .* DO NOT EDIT\.$/m;
+/** `@generated` used as a tag (not part of a word, e.g. not `@generatedAt`). */
+const GENERATED_TAG = /(?:^|[\s*/])@generated(?![\w-])/;
+/** The file's first comment block: a leading block comment or run of line comments. */
+function firstCommentBlock(content) {
+    const text = content.replace(/^\uFEFF/, '').replace(/^#![^\n]*\n/, '').trimStart();
+    if (text.startsWith('/*')) {
+        const close = text.indexOf('*/');
+        return close >= 0 ? text.slice(0, close + 2) : text;
+    }
+    const lines = [];
+    for (const line of text.split('\n')) {
+        if (!line.trimStart().startsWith('//'))
+            break;
+        lines.push(line);
+    }
+    return lines.join('\n');
+}
+/**
+ * #1021 round 2b: generated only by convention — Go's
+ * "// Code generated … DO NOT EDIT." line near the top, or an `@generated`
+ * tag in the first comment block. Prose such as "DO NOT EDIT the retry
+ * constants", or `@generated` mentioned later in the file, is handwritten.
+ */
+function isGeneratedSource(content) {
+    const head = content.slice(0, GENERATED_SNIFF_CHARS).replace(/\r\n/g, '\n');
+    return GO_GENERATED_LINE.test(head) || GENERATED_TAG.test(firstCommentBlock(head));
+}
+/** Exclusion decided from the file name alone. */
+function excludedByName(filePath) {
+    const name = filePath.split(/[\\/]/).pop() ?? filePath;
+    if (/\.d\.(ts|mts|cts)$/i.test(name))
+        return 'type declaration file';
+    if (/\.min\.(js|mjs|cjs)$/i.test(name))
+        return 'minified bundle';
+    return undefined;
+}
 // ============================================================================
 // Code Metrics Analyzer
 // ============================================================================
@@ -15,17 +58,55 @@ export class CodeMetricsAnalyzer {
     fileReader;
     constructor() {
         this.parser = new TypeScriptParser();
-        this.fileReader = new FileReader();
+        // #1021: reads inside the AQE project root (AQE_PROJECT_ROOT, else the
+        // detected root — not merely the process cwd) are contained by realpath,
+        // so in-root names like `[...slug].tsx`, dot-dirs and deep paths are
+        // readable; anything outside keeps the legacy path validation.
+        this.fileReader = new FileReader({ projectRoot: findProjectRoot() });
     }
     /**
      * Analyze a single file for all metrics
      */
     async analyzeFile(filePath) {
+        return (await this.analyzeWithDiagnostics(filePath)).metrics;
+    }
+    /**
+     * #1011 / #1021: analyse a file and say whether its metrics are evidence.
+     * Binary, generated, minified and declaration files — and files the reader
+     * refuses by policy — are `excluded`; unreadable or unparseable source is
+     * `failed`. Callers must not treat either as a measurement.
+     */
+    async analyzeFileDetailed(filePath) {
+        const byName = excludedByName(filePath);
+        if (byName)
+            return { status: 'excluded', metrics: null, reason: `${filePath}: ${byName}` };
+        const { metrics, content, readError, parseFailure, parsedAsSource } = await this.analyzeWithDiagnostics(filePath);
+        if (readError) {
+            return readError instanceof PathTraversalError
+                ? { status: 'excluded', metrics: null, reason: `${filePath} was refused by the file reader (${readError.message})` }
+                : { status: 'failed', metrics: null, reason: `${filePath} could not be read (${readError.message})` };
+        }
+        // git-style sniff, except that TS/JS which parses cleanly is source even
+        // with a raw NUL inside a string literal (seen in real repos).
+        const sourceDespiteNul = parsedAsSource && !parseFailure;
+        if (content !== undefined && !sourceDespiteNul && content.slice(0, BINARY_SNIFF_CHARS).includes('\u0000')) {
+            return { status: 'excluded', metrics: null, reason: `${filePath} has binary content` };
+        }
+        if (content !== undefined && isGeneratedSource(content)) {
+            return { status: 'excluded', metrics: null, reason: `${filePath} is a generated file` };
+        }
+        if (parseFailure)
+            return { status: 'failed', metrics, reason: `${filePath} could not be parsed (${parseFailure})` };
+        return { status: 'measured', metrics };
+    }
+    /** Compute metrics, reporting read errors and parse failures separately. */
+    async analyzeWithDiagnostics(filePath) {
         const contentResult = await this.fileReader.readFile(filePath);
         if (!contentResult.success) {
-            return null;
+            return { metrics: null, readError: contentResult.error };
         }
         const content = contentResult.value;
+        let parseFailure;
         const lines = content.split('\n');
         // Count different types of lines
         const { codeLines, commentLines, blankLines } = this.countLines(lines);
@@ -41,6 +122,10 @@ export class CodeMetricsAnalyzer {
         if (['ts', 'tsx', 'js', 'jsx'].includes(ext)) {
             try {
                 const ast = this.parser.parseFile(fileName, content);
+                const syntaxErrors = ast.parseDiagnostics?.length ?? 0;
+                if (syntaxErrors > 0) {
+                    parseFailure = `${syntaxErrors} syntax error${syntaxErrors === 1 ? '' : 's'}`;
+                }
                 // Extract functions and calculate complexity
                 const functions = this.parser.extractFunctions(ast);
                 functionCount = functions.length;
@@ -62,8 +147,9 @@ export class CodeMetricsAnalyzer {
                     }
                 }
             }
-            catch {
-                // If parsing fails, use heuristic analysis
+            catch (error) {
+                // If parsing fails, use heuristic analysis — an estimate, not a measurement (#1011)
+                parseFailure ??= error instanceof Error ? error.message : String(error);
                 cyclomaticComplexity = this.estimateCyclomaticComplexity(content);
                 cognitiveComplexity = this.estimateCognitiveComplexity(content);
             }
@@ -98,7 +184,7 @@ export class CodeMetricsAnalyzer {
         const halsteadMetrics = this.calculateHalsteadMetrics(content);
         // Calculate maintainability index
         const maintainabilityIndex = this.calculateMaintainabilityIndex(halsteadMetrics.volume, cyclomaticComplexity, codeLines);
-        return {
+        const metrics = {
             path: filePath,
             linesOfCode: codeLines,
             linesOfComments: commentLines,
@@ -111,6 +197,7 @@ export class CodeMetricsAnalyzer {
             classCount,
             maxNestingDepth,
         };
+        return { metrics, content, parseFailure, parsedAsSource: ['ts', 'tsx', 'js', 'jsx'].includes(ext) };
     }
     /**
      * Analyze function-level metrics