agentic-qe 3.15.5 → 3.15.7

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

package/dist/shared/metrics/index.d.ts

@@ -3,7 +3,7 @@
  * Exports for code quality and system metrics analysis
  */
 export { CodeMetricsAnalyzer, getCodeMetricsAnalyzer } from './code-metrics';
-export type { FileMetrics, FunctionMetrics, HalsteadMetrics, DuplicationResult, DuplicateBlock, } from './code-metrics';
+export type { FileMetrics, FileAnalysisOutcome, FileAnalysisStatus, FunctionMetrics, HalsteadMetrics, DuplicationResult, DuplicateBlock, } from './code-metrics';
 export { SystemMetricsCollector, getSystemMetricsCollector } from './system-metrics';
 export type { SystemMetrics, CpuMetrics, MemoryMetrics, ProcessMetrics, MetricSample, HttpMetrics, } from './system-metrics';
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/security/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * Agentic QE v3 - Security Utilities
  */
-export { OSVClient } from './osv-client';
-export type { OSVClientConfig, OSVQueryRequest, OSVEcosystem, OSVVulnerability, OSVSeverity, OSVAffected, OSVRange, OSVReference, OSVQueryResponse, OSVBatchQueryRequest, OSVBatchQueryResponse, ParsedVulnerability, } from './osv-client';
+export { OSVClient, OSVLookupError, resolveOSVBaseUrl } from './osv-client';
+export type { OSVBatchLookup, OSVPackageQuery, OSVUncheckedPackage, OSVClientConfig, OSVQueryRequest, OSVEcosystem, OSVVulnerability, OSVSeverity, OSVAffected, OSVRange, OSVReference, OSVQueryResponse, OSVBatchQueryRequest, OSVBatchQueryResponse, ParsedVulnerability, } from './osv-client';
 export { CompliancePatternAnalyzer, getCompliancePatternAnalyzer } from './compliance-patterns';
 export type { PatternMatch, CompliancePatternResult, EncryptionAnalysis, AccessControlAnalysis, LoggingAnalysis, DataProtectionAnalysis, SecurityControlsAnalysis, } from './compliance-patterns';
 export type { RiskLevel, ValidationResult, PathValidationResult, RegexSafetyResult, CommandValidationResult, SanitizationOptions, PathValidationOptions, RegexValidationOptions, CommandValidationOptions, IValidationStrategy, IPathValidationStrategy, IRegexValidationStrategy, ICommandValidationStrategy, IInputSanitizationStrategy, ICryptoValidationStrategy, IValidationOrchestrator, } from './validators-interfaces';

package/dist/shared/security/index.js

@@ -1,7 +1,7 @@
 /**
  * Agentic QE v3 - Security Utilities
  */
-export { OSVClient } from './osv-client.js';
+export { OSVClient, OSVLookupError, resolveOSVBaseUrl } from './osv-client.js';
 export { CompliancePatternAnalyzer, getCompliancePatternAnalyzer } from './compliance-patterns.js';
 // ============================================================================
 // Validators (moved from mcp/security/validators/)

package/dist/shared/security/osv-client.d.ts

@@ -5,146 +5,85 @@
  * OSV provides vulnerability information for npm, PyPI, Go, Maven, and more.
  * API Documentation: https://google.github.io/osv.dev/api/
  */
-/**
- * OSV query request
- */
-export interface OSVQueryRequest {
-    /** Package name */
-    package?: {
-        name: string;
-        ecosystem: OSVEcosystem;
-        version?: string;
-    };
-    /** Git commit hash */
-    commit?: string;
-    /** Package lock file version (for version ranges) */
-    version?: string;
-}
-/**
- * Supported ecosystems
- */
-export type OSVEcosystem = 'npm' | 'PyPI' | 'Go' | 'Maven' | 'crates.io' | 'NuGet' | 'Packagist' | 'RubyGems' | 'Hex' | 'Pub';
-/**
- * OSV vulnerability record
- */
-export interface OSVVulnerability {
-    id: string;
-    summary: string;
-    details?: string;
-    aliases?: string[];
-    modified: string;
-    published?: string;
-    withdrawn?: string;
-    severity?: OSVSeverity[];
-    affected: OSVAffected[];
-    references?: OSVReference[];
-    database_specific?: Record<string, unknown>;
-}
-/**
- * OSV severity rating
- */
-export interface OSVSeverity {
-    type: 'CVSS_V2' | 'CVSS_V3';
-    score: string;
-}
-/**
- * OSV affected package information
- */
-export interface OSVAffected {
-    package: {
-        name: string;
-        ecosystem: string;
-        purl?: string;
-    };
-    ranges?: OSVRange[];
-    versions?: string[];
-    ecosystem_specific?: Record<string, unknown>;
-    database_specific?: Record<string, unknown>;
-}
-/**
- * OSV version range
- */
-export interface OSVRange {
-    type: 'SEMVER' | 'ECOSYSTEM' | 'GIT';
-    repo?: string;
-    events: Array<{
-        introduced?: string;
-        fixed?: string;
-        last_affected?: string;
-        limit?: string;
-    }>;
-}
-/**
- * OSV reference link
- */
-export interface OSVReference {
-    type: 'ADVISORY' | 'ARTICLE' | 'DETECTION' | 'DISCUSSION' | 'REPORT' | 'FIX' | 'GIT' | 'PACKAGE' | 'EVIDENCE' | 'WEB';
-    url: string;
-}
-/**
- * OSV query response
- */
-export interface OSVQueryResponse {
-    vulns: OSVVulnerability[];
-}
-/**
- * OSV batch query request
- */
-export interface OSVBatchQueryRequest {
-    queries: OSVQueryRequest[];
-}
-/**
- * OSV batch query response
- */
-export interface OSVBatchQueryResponse {
-    results: Array<{
-        vulns?: OSVVulnerability[];
-    }>;
-}
-/**
- * Parsed vulnerability for easier consumption
- */
-export interface ParsedVulnerability {
-    id: string;
-    cveIds: string[];
-    summary: string;
-    details: string;
-    severity: 'critical' | 'high' | 'medium' | 'low' | 'unknown';
-    cvssScore: number | null;
-    affectedPackage: string;
-    affectedVersions: string[];
-    fixedVersions: string[];
-    publishedDate: Date | null;
-    references: string[];
-}
+import { type OSVBatchLookup, type OSVPackageQuery } from './osv-lookup';
+export { OSVLookupError } from './osv-lookup';
+export type { OSVBatchLookup, OSVPackageQuery, OSVUncheckedPackage } from './osv-lookup';
+import type { OSVEcosystem, ParsedVulnerability } from './osv-types';
+export type { OSVQueryRequest, OSVEcosystem, OSVVulnerability, OSVSeverity, OSVAffected, OSVRange, OSVReference, OSVQueryResponse, OSVBatchQueryRequest, OSVBatchQueryResponse, ParsedVulnerability, } from './osv-types';
 /**
  * OSV API Client Configuration
  */
 export interface OSVClientConfig {
-    /** API base URL (default: https://api.osv.dev) */
+    /**
+     * API base URL (default: $AQE_OSV_API_URL, else https://api.osv.dev). Must be
+     * https, or http on a loopback host. Validated lazily at the first lookup, so
+     * an invalid value fails dependency scans only, never construction (#1049).
+     */
     baseUrl?: string;
-    /** Request timeout in ms (default: 30000) */
+    /** Idle request timeout in ms (default: 30000) */
     timeout?: number;
-    /** Enable response caching (default: true) */
+    /** Retries per request after the first attempt (default: 2) */
+    retries?: number;
+    /** Packages per querybatch request (default: 500; OSV accepts up to 1000) */
+    batchSize?: number;
+    /** Concurrent advisory-detail requests (default: 8) */
+    detailConcurrency?: number;
+    /** Enable advisory-detail caching (default: true) */
     enableCache?: boolean;
     /** Cache TTL in ms (default: 1 hour) */
     cacheTtl?: number;
 }
+/**
+ * The OSV endpoint: `AQE_OSV_API_URL` or the public API. https is required,
+ * except plain http on a loopback host (local mirrors and test stubs).
+ * @throws Error naming AQE_OSV_API_URL when the value is not acceptable.
+ */
+export declare function resolveOSVBaseUrl(env?: NodeJS.ProcessEnv): string;
+/** Longest accepted AQE_OSV_API_URL; a longer value is invalid. */
+export declare const MAX_OSV_URL_LENGTH = 2048;
 /**
  * OSV API Client
- * Queries the Open Source Vulnerabilities database for dependency vulnerabilities
+ * Queries the Open Source Vulnerabilities database for dependency vulnerabilities.
+ *
+ * #1049: a failed or partial lookup is never reported as "no vulnerabilities".
+ * `lookupBatch` returns the packages it could not check; the list-returning
+ * methods throw `OSVLookupError` instead of returning `[]`.
  */
 export declare class OSVClient {
     private readonly config;
+    private readonly configuredBaseUrl;
+    private endpoint;
     private readonly http;
-    private readonly cache;
+    private readonly detailCache;
     constructor(config?: OSVClientConfig);
+    /** The endpoint this client queries, or null when the configured URL is invalid. */
+    get baseUrl(): string | null;
+    /** Resolve (once) the endpoint; an invalid value is a reason, never a throw. */
+    private resolveEndpoint;
+    private get base();
+    /**
+     * Look up advisories for packages, reporting every package that could not be
+     * checked. Only `status: 'complete'` may be read as a clean/measured result.
+     */
+    lookupBatch(packages: OSVPackageQuery[]): Promise<OSVBatchLookup>;
+    /**
+     * Look up npm `package.json` dependencies (`name -> version spec`).
+     *
+     * A dependency is checked at its lockfile-resolved version when one is given,
+     * else only when the spec is an exact version ("1.2.3", "=1.2.3", "v1.2.3").
+     * Ranges, tags and non-registry specs are reported unchecked, never guessed:
+     * checking a range's bound (e.g. "<4.17.12" as 4.17.12) can miss advisories
+     * that affect the versions the range allows (#1049).
+     */
+    lookupNpmDependencies(dependencies: Record<string, string>, lockedVersions?: Record<string, string>): Promise<OSVBatchLookup>;
     /**
-     * Query OSV for vulnerabilities affecting a package
+     * Query OSV for vulnerabilities affecting a package.
+     * @throws OSVLookupError when the advisory lookup did not complete.
      */
     queryPackage(packageName: string, ecosystem: OSVEcosystem, version?: string): Promise<ParsedVulnerability[]>;
     /**
-     * Batch query multiple packages
+     * Batch query multiple packages.
+     * @throws OSVLookupError when any package could not be checked.
      */
     queryBatch(packages: Array<{
         name: string;
@@ -152,40 +91,48 @@ export declare class OSVClient {
         version?: string;
     }>): Promise<Map<string, ParsedVulnerability[]>>;
     /**
-     * Query vulnerabilities by CVE ID
+     * Query vulnerabilities by advisory/CVE id. An id OSV does not know (404) is [].
+     * @throws OSVLookupError on any other failure.
      */
     queryByCVE(cveId: string): Promise<ParsedVulnerability[]>;
     /**
-     * Parse npm package.json dependencies for vulnerabilities
+     * Scan npm dependencies for vulnerabilities.
+     * @throws OSVLookupError when any dependency could not be checked; use
+     *   `lookupNpmDependencies` to get partial results with the unchecked list.
      */
     scanNpmDependencies(dependencies: Record<string, string>): Promise<ParsedVulnerability[]>;
     /**
-     * Scan a Python requirements.txt file content
+     * Scan a Python requirements.txt file content. Only `==` pins are concrete
+     * versions; other requirements are reported as unchecked.
+     * @throws OSVLookupError when any requirement could not be checked.
      */
     scanPythonRequirements(requirements: string): Promise<ParsedVulnerability[]>;
+    /** Clear the advisory-detail cache. */
+    clearCache(): void;
+    private requestOptions;
+    /** Read a JSON body; any transport failure, non-2xx status or parse failure is a reason. */
+    private readJson;
+    private postBatch;
+    /** Fetch full advisory records (querybatch returns only ids) with bounded concurrency. */
+    private fetchDetails;
+    private fetchDetail;
     /**
      * Parse vulnerabilities into a more usable format
      */
     private parseVulnerabilities;
     /**
-     * Extract CVSS score from severity array
+     * Extract a numeric CVSS score. OSV usually carries a CVSS vector string
+     * ("CVSS:3.1/AV:N/..."), which holds no base score: that yields null.
      */
     private extractCVSSScore;
     /**
-     * Convert CVSS score to severity level
+     * Severity from a numeric CVSS score, else the advisory's own severity label
+     * (GitHub advisories carry `database_specific.severity`), else unknown.
      */
     private scoreSeverity;
     /**
      * Extract fixed versions from affected ranges
      */
     private extractFixedVersions;
-    /**
-     * Clean version string (remove ^ ~ etc.)
-     */
-    private cleanVersion;
-    /**
-     * Clear the cache
-     */
-    clearCache(): void;
 }
 //# sourceMappingURL=osv-client.d.ts.map