@quantakrypto/core 0.1.0 → 0.2.0

package/src/parallel.ts

@@ -9,6 +9,7 @@
  * (small file counts / small total bytes) and whenever workers are unavailable.
  */
 import { stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,9 +17,9 @@ import { fileURLToPath } from "node:url";
 import type { Worker as NodeWorker } from "node:worker_threads";
 
 import type { Finding, ParallelScanOptions, ScanResult } from "./types.js";
-import { walkFiles, toPosix } from "./walk.js";
+import { walkFiles } from "./walk.js";
 import { buildInventory } from "./inventory.js";
-import { compareFindings, scan } from "./scan.js";
+import { compareFindings, filterExplicitFileList, scan } from "./scan.js";
 import { VERSION } from "./version.js";
 
 /** One unit of work dispatched to a worker. */
@@ -106,7 +107,9 @@ function shouldParallelize(options: ParallelScanOptions, files: SizedFile[]): bo
 async function enumerateFiles(options: ParallelScanOptions, baseDir: string): Promise<SizedFile[]> {
   const rels: string[] = [];
   if (options.files) {
-    for (const f of options.files) rels.push(toPosix(f));
+    // Apply the SAME include/exclude/binary filtering the serial path uses via
+    // `filterExplicitFiles`, so `--parallel` is byte-for-byte identical to serial.
+    for (const rel of filterExplicitFileList(options.files, options)) rels.push(rel);
   } else {
     for await (const rel of walkFiles(options.root, {
       include: options.include,
@@ -131,11 +134,21 @@ async function enumerateFiles(options: ParallelScanOptions, baseDir: string): Pr
   return sized;
 }
 
-/** Resolve the built worker entry (dist/scan-worker.js) next to this module. */
-function workerEntryPath(): string {
-  // After build this file is dist/parallel.js and the worker is dist/scan-worker.js.
+/**
+ * Resolve the worker entry next to this module. In a normal build it's
+ * `dist/scan-worker.js`. When running from source under a TypeScript loader
+ * (tsx) the built JS doesn't exist, so fall back to `scan-worker.ts` and tell
+ * the worker to load tsx as well — so the parallel scanner works in dev/source
+ * mode (and is exercisable by tests), not only after a build.
+ */
+function workerEntry(): { entry: string; execArgv?: string[] } {
   const here = fileURLToPath(import.meta.url);
-  return path.join(path.dirname(here), "scan-worker.js");
+  const dir = path.dirname(here);
+  const js = path.join(dir, "scan-worker.js");
+  if (existsSync(js)) return { entry: js };
+  const ts = path.join(dir, "scan-worker.ts");
+  if (existsSync(ts)) return { entry: ts, execArgv: ["--import", "tsx"] };
+  return { entry: js }; // neither present: let Worker surface a clear ENOENT
 }
 
 /**
@@ -171,7 +184,7 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
 
   const chunks = chunkByBytes(files, options.chunkBytes ?? DEFAULT_CHUNK_BYTES);
   const concurrency = Math.min(resolveConcurrency(options), chunks.length);
-  const entry = workerEntryPath();
+  const { entry, execArgv } = workerEntry();
 
   const toggles = {
     source: options.source !== false,
@@ -185,6 +198,7 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
     results = await runPool(
       WorkerCtor,
       entry,
+      execArgv,
       baseDir,
       toggles,
       chunks,
@@ -215,6 +229,7 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
 function runPool(
   WorkerCtor: typeof import("node:worker_threads").Worker,
   entry: string,
+  execArgv: string[] | undefined,
   baseDir: string,
   toggles: { source: boolean; config: boolean; deps: boolean; scanMinified: boolean },
   chunks: ScanChunk[],
@@ -243,7 +258,10 @@ function runPool(
     };
 
     const spawn = (): NodeWorker => {
-      const w = new WorkerCtor(entry, { workerData: { baseDir, toggles } });
+      const w = new WorkerCtor(entry, {
+        workerData: { baseDir, toggles },
+        ...(execArgv ? { execArgv } : {}),
+      });
       w.on(
         "message",
         (msg: { index: number; result?: ChunkResult; files?: string[]; error?: string }) => {

package/src/report.ts

@@ -3,8 +3,9 @@
  * or a human-readable text summary. No third-party dependencies — ANSI colour
  * is emitted with raw escape codes and is off by default.
  */
-import type { ScanResult, Severity } from "./types.js";
+import type { Finding, ScanResult, Severity } from "./types.js";
 import { VERSION } from "./version.js";
+import { SEVERITY_ORDER, sarifLevel } from "./severity.js";
 
 /** Minimal SARIF 2.1.0 log shape (kept permissive on purpose). */
 export interface SarifLog {
@@ -13,22 +14,30 @@ export interface SarifLog {
   runs: unknown[];
 }
 
+/** Options shared by the structured reporters ({@link toSarif} / {@link toJson}). */
+export interface ReportOptions {
+  /**
+   * Omit `location.snippet` from every finding in the output. Defaults to false
+   * (snippets are included). Snippets of `sensitive` findings (e.g. PEM key
+   * blocks, SSH public keys) are ALWAYS omitted regardless of this flag — the
+   * snippet there IS the sensitive value.
+   */
+  redactSnippets?: boolean;
+}
+
 const SARIF_SCHEMA =
   "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json";
 
-const INFORMATION_URI = "https://github.com/qproof-tools/qproof";
+const INFORMATION_URI = "https://github.com/quantakrypto/tools";
 
-/** Map our severity to a SARIF result level. */
-function sarifLevel(severity: Severity): "error" | "warning" | "note" {
-  switch (severity) {
-    case "critical":
-    case "high":
-      return "error";
-    case "medium":
-      return "warning";
-    default:
-      return "note";
-  }
+/**
+ * Resolve the snippet to emit for a finding, honouring redaction. Sensitive
+ * findings (key material) never expose their snippet; otherwise the snippet is
+ * dropped only when `redactSnippets` is set.
+ */
+function emittedSnippet(f: Finding, redactSnippets: boolean): string | undefined {
+  if (redactSnippets || f.sensitive) return undefined;
+  return f.location.snippet;
 }
 
 /** Map our severity to a SARIF rule-level default (used in rules[].defaultConfiguration). */
@@ -48,7 +57,8 @@ function sarifRank(severity: Severity): number {
 }
 
 /** Serialize a scan result as SARIF 2.1.0. */
-export function toSarif(result: ScanResult): SarifLog {
+export function toSarif(result: ScanResult, opts?: ReportOptions): SarifLog {
+  const redactSnippets = opts?.redactSnippets ?? false;
   // Build the unique rule set (one rule per ruleId encountered) and collect the
   // set of CWE taxa referenced by any rule.
   const ruleIndex = new Map<string, number>();
@@ -86,6 +96,7 @@ export function toSarif(result: ScanResult): SarifLog {
     const region: Record<string, number> = { startLine: f.location.line };
     if (typeof f.location.column === "number") region.startColumn = f.location.column;
     if (typeof f.location.endLine === "number") region.endLine = f.location.endLine;
+    const snippet = emittedSnippet(f, redactSnippets);
 
     return {
       ruleId: f.ruleId,
@@ -116,7 +127,7 @@ export function toSarif(result: ScanResult): SarifLog {
             artifactLocation: { uri: f.location.file },
             region: {
               ...region,
-              ...(f.location.snippet ? { snippet: { text: f.location.snippet } } : {}),
+              ...(snippet ? { snippet: { text: snippet } } : {}),
             },
           },
         },
@@ -178,7 +189,8 @@ function securitySeverity(severity: Severity): string {
 }
 
 /** Serialize a scan result as a plain JSON-friendly object. */
-export function toJson(result: ScanResult): Record<string, unknown> {
+export function toJson(result: ScanResult, opts?: ReportOptions): Record<string, unknown> {
+  const redactSnippets = opts?.redactSnippets ?? false;
   return {
     toolVersion: result.toolVersion,
     root: result.root,
@@ -208,7 +220,7 @@ export function toJson(result: ScanResult): Record<string, unknown> {
         line: f.location.line,
         column: f.location.column,
         endLine: f.location.endLine,
-        snippet: f.location.snippet,
+        snippet: emittedSnippet(f, redactSnippets),
       },
     })),
   };
@@ -231,9 +243,6 @@ const ANSI = {
   cyan: "\x1b[36m",
 } as const;
 
-/** Severity ordering for grouping / sorting, most → least severe. */
-const SEVERITY_ORDER: Severity[] = ["critical", "high", "medium", "low", "info"];
-
 function severityColor(sev: Severity): string {
   switch (sev) {
     case "critical":

package/src/scan.ts

@@ -19,6 +19,7 @@ import { pemDetector } from "./detectors/pem.js";
 import { defaultRegistry, detectorScope } from "./registry.js";
 import { isManifestFile, scanManifest } from "./dependencies.js";
 import { buildInventory } from "./inventory.js";
+import { AbortError, BudgetExceededError } from "./errors.js";
 import { VERSION } from "./version.js";
 
 /**
@@ -90,6 +91,12 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
 
   const findings: Finding[] = [];
   let filesScanned = 0;
+  let bytesScanned = 0;
+
+  // Work-budget / cancellation controls (all optional, unlimited when omitted).
+  const signal = options.signal;
+  const maxFiles = options.maxFiles;
+  const maxBytes = options.maxBytes;
 
   // Source of relative paths: an explicit file list (incremental) or the walker.
   const relPaths: AsyncIterable<string> = options.files
@@ -102,6 +109,14 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
       });
 
   for await (const rel of relPaths) {
+    // Cooperative cancellation: check the signal at the top of every iteration.
+    if (signal?.aborted) throw new AbortError();
+
+    // File-count budget: enforced before reading the next file.
+    if (typeof maxFiles === "number" && filesScanned >= maxFiles) {
+      throw new BudgetExceededError(`maxFiles budget exceeded (limit: ${maxFiles}).`);
+    }
+
     // In single-file mode, walkFiles yields the basename; map back to the file.
     const absPath = singleFileName ? options.root : path.join(baseDir, ...rel.split("/"));
     const reportedPath = singleFileName ? toPosix(rel) : rel;
@@ -121,6 +136,12 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
       continue;
     }
 
+    // Cumulative-byte budget: enforced once this file's bytes are accounted for.
+    bytesScanned += Buffer.byteLength(content, "utf8");
+    if (typeof maxBytes === "number" && bytesScanned > maxBytes) {
+      throw new BudgetExceededError(`maxBytes budget exceeded (limit: ${maxBytes}).`);
+    }
+
     filesScanned += 1;
     findings.push(
       ...detectFile(reportedPath, content, dets, {
@@ -150,11 +171,18 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
 
 /**
  * Filter an explicit relative file list down to the paths that pass the binary
- * filter and the include/exclude patterns, yielding them in sorted order for
+ * filter and the include/exclude patterns, returning them deduped and sorted for
  * deterministic output. Size limits are enforced later (we still read manifests
  * over the cap). Non-existent files are simply skipped at read time.
+ *
+ * Pure + synchronous, and exported so the parallel enumerator applies the EXACT
+ * same filtering for explicit file lists as the serial path (byte-for-byte
+ * identical results under `--parallel`).
  */
-async function* filterExplicitFiles(files: string[], options: ScanOptions): AsyncGenerator<string> {
+export function filterExplicitFileList(
+  files: readonly string[],
+  options: Pick<ScanOptions, "include" | "exclude">,
+): string[] {
   const include = options.include ?? [];
   const exclude = options.exclude ?? [];
   const seen = new Set<string>();
@@ -167,12 +195,17 @@ async function* filterExplicitFiles(files: string[], options: ScanOptions): Asyn
     })
     .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
 
-  for (const rel of list) {
-    if (isBinaryPath(rel)) continue;
-    if (include.length > 0 && !matchesAny(rel, include)) continue;
-    if (matchesAny(rel, exclude)) continue;
-    yield rel;
-  }
+  return list.filter((rel) => {
+    if (isBinaryPath(rel)) return false;
+    if (include.length > 0 && !matchesAny(rel, include)) return false;
+    if (matchesAny(rel, exclude)) return false;
+    return true;
+  });
+}
+
+/** Async-generator wrapper around {@link filterExplicitFileList} for `scan()`. */
+async function* filterExplicitFiles(files: string[], options: ScanOptions): AsyncGenerator<string> {
+  for (const rel of filterExplicitFileList(files, options)) yield rel;
 }
 
 /** Local substring/prefix matcher (mirrors the walker's pattern semantics). */

package/src/severity.ts

@@ -0,0 +1,40 @@
+/**
+ * Severity utilities shared across the monorepo (qScan, the MCP server, the
+ * GitHub Action). Lifts the previously-duplicated ordering / threshold / SARIF
+ * mapping logic into one place so every consumer agrees on what "at or above a
+ * threshold" means and how a severity maps to a SARIF level.
+ */
+import type { Severity } from "./types.js";
+
+/** Severity ordering, most → least severe. Index 0 is the most severe. */
+export const SEVERITY_ORDER: readonly Severity[] = ["critical", "high", "medium", "low", "info"];
+
+/**
+ * Rank of a severity within {@link SEVERITY_ORDER} (0 = most severe). Lower
+ * ranks are more severe; unknown values fall to the end.
+ */
+export function severityRank(s: Severity): number {
+  const i = SEVERITY_ORDER.indexOf(s);
+  return i < 0 ? SEVERITY_ORDER.length : i;
+}
+
+/**
+ * True when `severity` is at or above `threshold` (i.e. at least as severe).
+ * Because lower ranks are more severe, "at or above" is `rank <= threshold`.
+ */
+export function meetsThreshold(severity: Severity, threshold: Severity): boolean {
+  return severityRank(severity) <= severityRank(threshold);
+}
+
+/** Map our severity to a SARIF 2.1.0 result level. */
+export function sarifLevel(severity: Severity): "error" | "warning" | "note" {
+  switch (severity) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    default:
+      return "note";
+  }
+}

package/src/types.ts

@@ -68,6 +68,12 @@ export interface Finding {
   remediation?: string;
   /** Associated CWE identifier, e.g. "CWE-327" (broken crypto), "CWE-326" (weak strength). */
   cwe?: string;
+  /**
+   * True when the matched snippet IS the sensitive value (e.g. a PEM private/
+   * public key block, an `ssh-rsa AAAA…` public key). Reporters ALWAYS drop the
+   * snippet for such findings, regardless of any redaction flag.
+   */
+  sensitive?: boolean;
   location: SourceLocation;
 }
 
@@ -166,6 +172,23 @@ export interface ScanOptions {
   detectors?: Detector[];
   /** Optional progress callback. */
   onFile?: (file: string) => void;
+  /**
+   * Optional abort signal. When it fires mid-walk the scan stops cooperatively
+   * and rejects with an `AbortError` (a `DOMException`-like error with
+   * `name === "AbortError"`).
+   */
+  signal?: AbortSignal;
+  /**
+   * Work budget: maximum number of files to scan. When exceeded mid-walk the
+   * scan stops and throws a `BudgetExceededError`. Unlimited when omitted.
+   */
+  maxFiles?: number;
+  /**
+   * Work budget: maximum cumulative bytes of scanned file content. When
+   * exceeded mid-walk the scan stops and throws a `BudgetExceededError`.
+   * Unlimited when omitted.
+   */
+  maxBytes?: number;
 }
 
 /** Extra options for {@link scanParallel}, layered onto {@link ScanOptions}. */

package/src/version.ts

@@ -3,4 +3,4 @@
  * the scan orchestrator can import it without creating a cycle through index.ts.
  * Keep in sync with packages/core/package.json.
  */
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";