@quantakrypto/core 0.1.0

package/src/scan.ts

@@ -0,0 +1,187 @@
+/**
+ * Scan orchestrator. Walks the target (or an explicit file list), runs the
+ * applicable detectors over each file, parses dependency manifests, aggregates
+ * everything into an inventory, and returns a {@link ScanResult} with timing and
+ * the tool version.
+ *
+ * Detector scope (source vs config) is driven by each {@link Detector}'s
+ * declared `scope` (defaulting to "source"), not by ruleId prefixes. The
+ * detector set comes from {@link defaultRegistry} unless overridden via
+ * `options.detectors`.
+ */
+import { readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+
+import type { Detector, Finding, ScanOptions, ScanResult } from "./types.js";
+import { walkFiles, toPosix, isBinaryPath, looksMinified } from "./walk.js";
+import { sourceDetectors } from "./detectors/source.js";
+import { pemDetector } from "./detectors/pem.js";
+import { defaultRegistry, detectorScope } from "./registry.js";
+import { isManifestFile, scanManifest } from "./dependencies.js";
+import { buildInventory } from "./inventory.js";
+import { VERSION } from "./version.js";
+
+/**
+ * The full set of built-in detectors exposed on the public API. The PEM
+ * detector applies to every text file; the source detectors apply only to
+ * JS/TS. The manifest scanner is handled separately (it parses JSON rather than
+ * running a Detector).
+ */
+export const detectors: Detector[] = [...sourceDetectors, pemDetector];
+
+/** Stable comparator: by file, then line, then ruleId. Exported for reuse. */
+export function compareFindings(a: Finding, b: Finding): number {
+  if (a.location.file !== b.location.file) return a.location.file < b.location.file ? -1 : 1;
+  if (a.location.line !== b.location.line) return a.location.line - b.location.line;
+  return a.ruleId < b.ruleId ? -1 : a.ruleId > b.ruleId ? 1 : 0;
+}
+
+/** Resolve the active detector list for a scan (override or the default registry). */
+function resolveDetectors(options: ScanOptions): Detector[] {
+  return options.detectors ?? defaultRegistry.all();
+}
+
+/**
+ * Run all applicable detectors + the manifest scanner over a single file's
+ * contents, honouring the source / config / dependencies toggles. Pure: no I/O.
+ * Exported so the parallel worker and unit tests can drive it directly.
+ */
+export function detectFile(
+  file: string,
+  content: string,
+  dets: readonly Detector[],
+  toggles: { source: boolean; config: boolean; deps: boolean },
+): Finding[] {
+  const out: Finding[] = [];
+
+  for (const det of dets) {
+    if (!det.appliesTo(file)) continue;
+    const isConfig = detectorScope(det) === "config";
+    if (isConfig ? !toggles.config : !toggles.source) continue;
+    out.push(...det.detect({ file, content }));
+  }
+
+  if (toggles.deps && isManifestFile(file)) {
+    out.push(...scanManifest(file, content));
+  }
+
+  return out;
+}
+
+/**
+ * Recursively scan a directory (or single file, or explicit file list) for
+ * classical asymmetric crypto. Honours the source / dependencies / config
+ * toggles (all default true) and reports progress through `options.onFile`.
+ */
+export async function scan(options: ScanOptions): Promise<ScanResult> {
+  const startedAt = new Date();
+
+  const doSource = options.source !== false;
+  const doDeps = options.dependencies !== false;
+  const doConfig = options.config !== false;
+  const scanMinified = options.scanMinified === true;
+  const dets = resolveDetectors(options);
+
+  // Resolve whether the root is a file so we can rebuild absolute paths to read.
+  const rootStat = await stat(options.root);
+  const rootIsFile = rootStat.isFile();
+  const baseDir = rootIsFile ? path.dirname(options.root) : options.root;
+  const singleFileName = rootIsFile ? path.basename(options.root) : null;
+
+  const findings: Finding[] = [];
+  let filesScanned = 0;
+
+  // Source of relative paths: an explicit file list (incremental) or the walker.
+  const relPaths: AsyncIterable<string> = options.files
+    ? filterExplicitFiles(options.files, options)
+    : walkFiles(options.root, {
+        include: options.include,
+        exclude: options.exclude,
+        noDefaultIgnores: options.noDefaultIgnores,
+        maxFileSize: options.maxFileSize,
+      });
+
+  for await (const rel of relPaths) {
+    // 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;
+
+    options.onFile?.(reportedPath);
+
+    let content: string;
+    try {
+      content = await readFile(absPath, "utf8");
+    } catch {
+      continue; // unreadable / vanished file — skip.
+    }
+
+    // Skip machine-minified / generated content (unless explicitly enabled).
+    // Manifests are always scanned (their findings are dependency findings).
+    if (!scanMinified && !isManifestFile(reportedPath) && looksMinified(content)) {
+      continue;
+    }
+
+    filesScanned += 1;
+    findings.push(
+      ...detectFile(reportedPath, content, dets, {
+        source: doSource,
+        config: doConfig,
+        deps: doDeps,
+      }),
+    );
+  }
+
+  // Stable ordering: by file, then line, then ruleId.
+  findings.sort(compareFindings);
+
+  const inventory = buildInventory(findings);
+  const finishedAt = new Date();
+
+  return {
+    root: options.root,
+    findings,
+    filesScanned,
+    inventory,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString(),
+    toolVersion: VERSION,
+  };
+}
+
+/**
+ * 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
+ * deterministic output. Size limits are enforced later (we still read manifests
+ * over the cap). Non-existent files are simply skipped at read time.
+ */
+async function* filterExplicitFiles(files: string[], options: ScanOptions): AsyncGenerator<string> {
+  const include = options.include ?? [];
+  const exclude = options.exclude ?? [];
+  const seen = new Set<string>();
+  const list = [...files]
+    .map((f) => toPosix(f))
+    .filter((f) => {
+      if (seen.has(f)) return false;
+      seen.add(f);
+      return true;
+    })
+    .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;
+  }
+}
+
+/** Local substring/prefix matcher (mirrors the walker's pattern semantics). */
+function matchesAny(rel: string, patterns: readonly string[]): boolean {
+  for (const pattern of patterns) {
+    if (!pattern) continue;
+    const p = toPosix(pattern).replace(/\/+$/, "");
+    if (rel.includes(p)) return true;
+    if (rel === p || rel.startsWith(`${p}/`)) return true;
+  }
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,224 @@
+/**
+ * @quantakrypto/core — shared types (the locked public contract).
+ *
+ * These types are the stable interface between every tool in the monorepo
+ * (qScan, the MCP server, the GitHub Action). Treat additions as backwards
+ * compatible; treat renames/removals as breaking.
+ */
+
+/** How serious a finding is, ordered most → least severe. */
+export type Severity = "critical" | "high" | "medium" | "low" | "info";
+
+/** How sure the detector is that the finding is a real use of the algorithm. */
+export type Confidence = "high" | "medium" | "low";
+
+/** What kind of cryptographic concern a finding represents. */
+export type FindingCategory =
+  | "kem" // key encapsulation / public-key encryption (e.g. RSA-OAEP)
+  | "key-exchange" // (EC)DH
+  | "signature" // RSA/ECDSA/EdDSA signing
+  | "tls" // transport configuration
+  | "certificate" // X.509 / PKI material
+  | "dependency" // a quantum-vulnerable library in the dependency tree
+  | "hash" // weak / pre-quantum hash usage
+  | "rng"; // randomness concerns
+
+/** Classical asymmetric algorithm families that are not quantum-safe. */
+export type AlgorithmFamily =
+  | "RSA"
+  | "ECDH"
+  | "ECDSA"
+  | "EdDSA"
+  | "DH"
+  | "DSA"
+  | "X25519"
+  | "X448"
+  | "ECIES"
+  | "unknown";
+
+/** A precise location inside a scanned file. */
+export interface SourceLocation {
+  /** Path relative to the scan root, using POSIX separators. */
+  file: string;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column number, if known. */
+  column?: number;
+  /** 1-based end line, for multi-line matches. */
+  endLine?: number;
+  /** The matched source text (trimmed, single line). */
+  snippet?: string;
+}
+
+/** A single detected concern. */
+export interface Finding {
+  /** Stable rule identifier, e.g. "rsa-keygen", "ecdh-usage", "tls-legacy-version", "dep-vulnerable". */
+  ruleId: string;
+  title: string;
+  category: FindingCategory;
+  severity: Severity;
+  confidence: Confidence;
+  /** The classical algorithm involved, when applicable. */
+  algorithm?: AlgorithmFamily;
+  /** True when this is exposed to "harvest now, decrypt later". */
+  hndl: boolean;
+  /** One-line human explanation of the concern. */
+  message: string;
+  /** Suggested post-quantum remediation (e.g. ML-KEM, hybrid X25519MLKEM768). */
+  remediation?: string;
+  /** Associated CWE identifier, e.g. "CWE-327" (broken crypto), "CWE-326" (weak strength). */
+  cwe?: string;
+  location: SourceLocation;
+}
+
+/** A known quantum-vulnerable dependency entry. */
+export interface VulnerableDependency {
+  /** Package name. */
+  name: string;
+  ecosystem: "npm";
+  /** Why it's flagged (what classical crypto it provides). */
+  reason: string;
+  /** Algorithm families the package primarily exposes. */
+  algorithms: AlgorithmFamily[];
+  severity: Severity;
+}
+
+/**
+ * Which logical scope a detector belongs to. Drives the source/config scope
+ * toggles in {@link ScanOptions} (replacing the old ruleId-prefix inference).
+ */
+export type DetectorScope = "source" | "config";
+
+/**
+ * The programming language / surface a detector targets. `"any"` means the
+ * detector is language-agnostic (e.g. PEM material, config files).
+ */
+export type DetectorLanguage = "js" | "python" | "go" | "java" | "any";
+
+/** A pluggable source detector. Detectors are pure and stateless. */
+export interface Detector {
+  /** Unique id, used as the Finding.ruleId prefix space. */
+  id: string;
+  /** Human description of what the detector looks for. */
+  description: string;
+  /**
+   * Logical scope of this detector's findings. Used by `scan()` to honour the
+   * `config` / `source` toggles. Defaults to `"source"` when omitted (for
+   * backward compatibility with externally-defined detectors).
+   */
+  scope?: DetectorScope;
+  /**
+   * Language this detector targets, for documentation / registry filtering.
+   * Defaults to `"js"` when omitted.
+   */
+  language?: DetectorLanguage;
+  /** Whether this detector should run against the given file path. */
+  appliesTo(filePath: string): boolean;
+  /** Inspect a single file's contents and return zero or more findings. */
+  detect(input: DetectorInput): Finding[];
+}
+
+export interface DetectorInput {
+  /** Path relative to the scan root (POSIX). */
+  file: string;
+  /** Full file contents. */
+  content: string;
+}
+
+/** Options controlling a scan. */
+export interface ScanOptions {
+  /** Absolute or relative directory (or single file) to scan. */
+  root: string;
+  /**
+   * Restrict the walk to paths matching one of these include patterns
+   * (substring or relative-path-prefix match). When omitted, all non-excluded
+   * files are scanned. Wired into the walker.
+   */
+  include?: string[];
+  /** Extra exclude patterns (in addition to the built-in defaults). */
+  exclude?: string[];
+  /** Disable the built-in ignore list (node_modules, .git, dist, …). */
+  noDefaultIgnores?: boolean;
+  /** Scan source files for inline crypto usage. Default: true. */
+  source?: boolean;
+  /** Scan dependency manifests/lockfiles for vulnerable libraries. Default: true. */
+  dependencies?: boolean;
+  /** Scan config files (TLS, certificates). Default: true. */
+  config?: boolean;
+  /** Max file size to read, in bytes. Default: 2 MiB. */
+  maxFileSize?: number;
+  /**
+   * Scan minified / generated / bundled files (large single-line content)
+   * instead of skipping them. Default: false (skip them for speed).
+   */
+  scanMinified?: boolean;
+  /**
+   * Explicit relative file list (POSIX, relative to `root`) to scan instead of
+   * walking the tree. Used for incremental / changed-files scans. Each path is
+   * still subject to the binary / size filters. When set, the directory walk is
+   * bypassed entirely.
+   */
+  files?: string[];
+  /**
+   * Override / extend the built-in detector set. When omitted, the default
+   * registry's detectors are used.
+   */
+  detectors?: Detector[];
+  /** Optional progress callback. */
+  onFile?: (file: string) => void;
+}
+
+/** Extra options for {@link scanParallel}, layered onto {@link ScanOptions}. */
+export interface ParallelScanOptions extends ScanOptions {
+  /**
+   * Number of worker threads. Default: `os.availableParallelism()`. A value of
+   * 0 or 1 forces the in-process serial path.
+   */
+  concurrency?: number;
+  /**
+   * Combined-size floor (bytes) below which the scan always runs in-process.
+   * Default: 2 MiB. Also stays serial below `parallelFileThreshold` files.
+   */
+  parallelThresholdBytes?: number;
+  /** File-count floor below which the scan always runs in-process. Default: 200. */
+  parallelFileThreshold?: number;
+  /** Target bytes per worker chunk. Default: 4 MiB. */
+  chunkBytes?: number;
+}
+
+/** Aggregated counts produced from a scan's findings. */
+export interface CryptoInventory {
+  byAlgorithm: Partial<Record<AlgorithmFamily, number>>;
+  byCategory: Partial<Record<FindingCategory, number>>;
+  bySeverity: Record<Severity, number>;
+  /** Number of findings exposed to harvest-now-decrypt-later. */
+  hndlCount: number;
+  /** 0–100 readiness score (100 = no classical asymmetric crypto found). */
+  readinessScore: number;
+}
+
+/** The full result of a scan. */
+export interface ScanResult {
+  /** The scan root (as provided). */
+  root: string;
+  findings: Finding[];
+  filesScanned: number;
+  inventory: CryptoInventory;
+  /** ISO timestamps. */
+  startedAt: string;
+  finishedAt: string;
+  /** Tool version that produced the result. */
+  toolVersion: string;
+}
+
+/** Output formats qScan / reporters can emit. */
+export type ReportFormat = "human" | "json" | "sarif";
+
+/** A remediation recommendation for a classical algorithm. */
+export interface Remediation {
+  algorithm: AlgorithmFamily;
+  /** Short recommended replacement, e.g. "ML-KEM-768 (hybrid X25519MLKEM768)". */
+  recommendation: string;
+  /** Longer rationale. */
+  detail: string;
+}

package/src/version.ts

@@ -0,0 +1,6 @@
+/**
+ * The tool version surfaced in reports. Kept in its own module so reporters and
+ * 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";

package/src/walk.ts

@@ -0,0 +1,289 @@
+/**
+ * Filesystem walker. A zero-dependency recursive async generator that yields
+ * scannable text files as relative POSIX paths. It honours a default ignore
+ * list, user-supplied exclude patterns, a max file size, and a binary-extension
+ * filter. The root may be a directory or a single file.
+ */
+import { readdir, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import * as path from "node:path";
+
+/** Directories ignored by default (can be disabled with noDefaultIgnores). */
+export const DEFAULT_IGNORES: readonly string[] = [
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".next",
+  "out",
+  "coverage",
+  "vendor",
+  ".turbo",
+  ".cache",
+];
+
+/** Default maximum file size to read: 2 MiB. */
+export const DEFAULT_MAX_FILE_SIZE = 2 * 1024 * 1024;
+
+/**
+ * File extensions we treat as binary / non-text and therefore skip. Keeping this
+ * as an extension allow-list-by-exclusion is cheap and avoids reading bytes.
+ */
+const BINARY_EXTENSIONS = new Set<string>([
+  // images
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".bmp",
+  ".ico",
+  ".tiff",
+  ".avif",
+  // fonts
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  // archives / compressed
+  ".zip",
+  ".gz",
+  ".tgz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".tar",
+  // media
+  ".mp3",
+  ".mp4",
+  ".mov",
+  ".avi",
+  ".mkv",
+  ".wav",
+  ".flac",
+  ".ogg",
+  ".webm",
+  // documents / binaries
+  ".pdf",
+  ".doc",
+  ".docx",
+  ".xls",
+  ".xlsx",
+  ".ppt",
+  ".pptx",
+  ".exe",
+  ".dll",
+  ".so",
+  ".dylib",
+  ".bin",
+  ".o",
+  ".a",
+  ".class",
+  ".wasm",
+  // data blobs / db
+  ".db",
+  ".sqlite",
+  ".sqlite3",
+  ".dat",
+  ".pack",
+  ".idx",
+  // misc
+  ".lock",
+  ".map",
+  ".min.js",
+  ".node",
+]);
+
+/** Options accepted by {@link walkFiles}. */
+export interface WalkOptions {
+  /**
+   * Restrict to paths matching one of these include patterns (substring or
+   * relative-path-prefix match). When omitted/empty, all files pass.
+   */
+  include?: string[];
+  /** Extra exclude patterns (substring or relative-path-prefix match). */
+  exclude?: string[];
+  /** Disable the built-in directory ignore list. */
+  noDefaultIgnores?: boolean;
+  /** Max file size in bytes; larger files are skipped. */
+  maxFileSize?: number;
+}
+
+/** Normalise a path to forward-slash POSIX separators. */
+export function toPosix(p: string): string {
+  return p.split(path.sep).join("/");
+}
+
+/** True if `rel` (a POSIX relative path) matches any pattern (substring/prefix). */
+function matchesAny(rel: string, patterns: readonly string[]): boolean {
+  for (const pattern of patterns) {
+    if (!pattern) continue;
+    const p = toPosix(pattern).replace(/\/+$/, "");
+    // Substring match (handles "src/legacy" or "secrets")...
+    if (rel.includes(p)) return true;
+    // ...and explicit path-prefix match ("foo" should match "foo/bar.ts").
+    if (rel === p || rel.startsWith(`${p}/`)) return true;
+  }
+  return false;
+}
+
+/** True if `rel` (a POSIX relative path) matches any exclude pattern. */
+function isExcluded(rel: string, exclude: readonly string[]): boolean {
+  return matchesAny(rel, exclude);
+}
+
+/**
+ * True if `rel` passes the include filter. An empty include list means "include
+ * everything"; otherwise the file must match at least one include pattern.
+ */
+function isIncluded(rel: string, include: readonly string[]): boolean {
+  if (include.length === 0) return true;
+  return matchesAny(rel, include);
+}
+
+/** True if the file's extension marks it as binary / non-text. */
+export function isBinaryPath(rel: string): boolean {
+  const lower = rel.toLowerCase();
+  // Handle compound extensions like ".min.js" first.
+  if (lower.endsWith(".min.js")) return true;
+  const ext = path.posix.extname(lower);
+  return BINARY_EXTENSIONS.has(ext);
+}
+
+/**
+ * Compound / pattern extensions that mark generated or bundled output we skip
+ * by default (beyond `.min.js` / `.map`, which {@link isBinaryPath} handles).
+ */
+const GENERATED_PATH_RE =
+  /(?:\.min\.[mc]?js|[.-]min\.[mc]?js|\.bundle\.[mc]?js|\.chunk\.[mc]?js|\.generated\.[jt]sx?|_pb\.js|\.pb\.go)$/i;
+
+/** True if the path looks like generated / bundled output (by name). */
+export function isGeneratedPath(rel: string): boolean {
+  return GENERATED_PATH_RE.test(rel.toLowerCase());
+}
+
+/**
+ * Heuristic content check for machine-minified / generated files with no
+ * telltale extension: a very long average line length, or any single line over
+ * ~50 KB, in the first ~64 KB sampled. Used at read time, not in the walker.
+ */
+export function looksMinified(content: string): boolean {
+  const sample = content.length > 65_536 ? content.slice(0, 65_536) : content;
+  if (sample.length === 0) return false;
+  let maxLine = 0;
+  let cur = 0;
+  let lines = 1;
+  for (let i = 0; i < sample.length; i++) {
+    if (sample.charCodeAt(i) === 10 /* \n */) {
+      if (cur > maxLine) maxLine = cur;
+      cur = 0;
+      lines++;
+    } else {
+      cur++;
+    }
+  }
+  if (cur > maxLine) maxLine = cur;
+  if (maxLine > 50_000) return true;
+  const avgLine = sample.length / lines;
+  return avgLine > 1_000;
+}
+
+/**
+ * Recursively yield scannable file paths (relative to `root`, POSIX) under a
+ * directory. If `root` points at a single file, yields just that file's
+ * basename (subject to the size / binary filters).
+ */
+export async function* walkFiles(root: string, options: WalkOptions = {}): AsyncGenerator<string> {
+  const include = options.include ?? [];
+  const exclude = options.exclude ?? [];
+  const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+  const ignores = options.noDefaultIgnores ? [] : DEFAULT_IGNORES;
+
+  const rootStat = await stat(root);
+
+  // Single-file mode: yield the file itself (by basename) if it passes filters.
+  if (rootStat.isFile()) {
+    const name = toPosix(path.basename(root));
+    if (
+      !isBinaryPath(name) &&
+      isIncluded(name, include) &&
+      passesSizeLimit(name, rootStat.size, maxFileSize)
+    ) {
+      yield name;
+    }
+    return;
+  }
+
+  yield* walkDir(root, "", { include, exclude, maxFileSize, ignores });
+}
+
+interface WalkContext {
+  include: readonly string[];
+  exclude: readonly string[];
+  maxFileSize: number;
+  ignores: readonly string[];
+}
+
+/**
+ * True if a file passes the size limit. Dependency manifests (package.json /
+ * package-lock.json) are exempt from the cap so large lockfiles still get
+ * scanned for vulnerable dependencies instead of being silently dropped.
+ */
+function passesSizeLimit(rel: string, size: number, maxFileSize: number): boolean {
+  if (isManifestPath(rel)) return true;
+  return size <= maxFileSize;
+}
+
+/** True if the path's basename is a dependency manifest we always read. */
+function isManifestPath(rel: string): boolean {
+  const base = rel.split("/").pop() ?? rel;
+  return base === "package.json" || base === "package-lock.json";
+}
+
+/** Internal recursive directory walker. `relDir` is POSIX-relative to the root. */
+async function* walkDir(absDir: string, relDir: string, ctx: WalkContext): AsyncGenerator<string> {
+  let entries: Dirent[];
+  try {
+    entries = await readdir(absDir, { withFileTypes: true });
+  } catch {
+    // Unreadable directory (permissions, transient races) — skip silently.
+    return;
+  }
+
+  // Stable, deterministic ordering for reproducible scans.
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+  for (const entry of entries) {
+    const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+    const abs = path.join(absDir, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      // Don't follow symlinks: avoids cycles and escaping the root.
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      if (ctx.ignores.includes(entry.name)) continue;
+      if (isExcluded(rel, ctx.exclude)) continue;
+      yield* walkDir(abs, rel, ctx);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+    if (isExcluded(rel, ctx.exclude)) continue;
+    if (!isIncluded(rel, ctx.include)) continue;
+    if (isBinaryPath(rel)) continue;
+    if (isGeneratedPath(rel)) continue;
+
+    try {
+      const s = await stat(abs);
+      if (!passesSizeLimit(rel, s.size, ctx.maxFileSize)) continue;
+    } catch {
+      continue;
+    }
+
+    yield rel;
+  }
+}