@quantakrypto/core 0.2.1 → 0.3.0

package/src/index.ts

@@ -25,8 +25,9 @@ export { AbortError, BudgetExceededError } from "./errors.js";
 export { scanParallel, mergeChunkResults, chunkByBytes } from "./parallel.js";
 export type { ScanChunk, ChunkResult, SizedFile } from "./parallel.js";
 
-// Detector registry (plugin point) + helpers.
+// Detector registry (plugin point) + helpers + the rule catalog.
 export { DetectorRegistry, defaultRegistry, detectorScope } from "./registry.js";
+export type { RuleCatalogEntry } from "./registry.js";
 
 // Canonical baseline (shared by qScan + the Action).
 export {

package/src/inventory.ts

@@ -33,10 +33,16 @@ function penaltyFor(weight: number, occurrence: number): number {
   return weight / Math.sqrt(occurrence);
 }
 
+/** Decay constant for the readiness score (larger = more forgiving). */
+const SCORE_SCALE = 100;
+
 /**
- * Compute a 0–100 readiness score. Starts at 100 and subtracts severity-weighted
- * penalties with diminishing returns per severity bucket. 100 means no classical
- * asymmetric crypto was found; the score is clamped to [0, 100].
+ * Compute a 0–100 readiness score. 100 means no classical asymmetric crypto was
+ * found. Findings accrue a severity-weighted penalty (with per-bucket diminishing
+ * returns), then the score is `100 * e^(-penalty/scale)`. Exponential decay keeps
+ * the score responsive across the whole range — fixing findings always raises it,
+ * and a large legacy repo lands low without pinning flat at 0 (which made progress
+ * invisible under the old linear model). Tuned so one low ~97, one critical ~74.
  */
 export function readinessScore(findings: Finding[]): number {
   if (findings.length === 0) return 100;
@@ -49,13 +55,13 @@ export function readinessScore(findings: Finding[]): number {
     info: 0,
   };
 
-  let score = 100;
+  let penalty = 0;
   for (const f of findings) {
     seen[f.severity] += 1;
-    score -= penaltyFor(SEVERITY_WEIGHT[f.severity], seen[f.severity]);
+    penalty += penaltyFor(SEVERITY_WEIGHT[f.severity], seen[f.severity]);
   }
 
-  return Math.max(0, Math.min(100, Math.round(score)));
+  return Math.max(0, Math.min(100, Math.round(100 * Math.exp(-penalty / SCORE_SCALE))));
 }
 
 /** Build the full inventory (counts + HNDL + score) from a set of findings. */

package/src/parallel.ts

@@ -191,6 +191,8 @@ export async function scanParallel(options: ParallelScanOptions): Promise<ScanRe
     config: options.config !== false,
     deps: options.dependencies !== false,
     scanMinified: options.scanMinified === true,
+    // Plain string array — structured-cloneable, so it crosses the worker boundary.
+    disabledRules: options.disabledRules,
   };
 
   let results: ChunkResult[];
@@ -231,7 +233,13 @@ function runPool(
   entry: string,
   execArgv: string[] | undefined,
   baseDir: string,
-  toggles: { source: boolean; config: boolean; deps: boolean; scanMinified: boolean },
+  toggles: {
+    source: boolean;
+    config: boolean;
+    deps: boolean;
+    scanMinified: boolean;
+    disabledRules?: string[];
+  },
   chunks: ScanChunk[],
   concurrency: number,
   onFile?: (file: string) => void,

package/src/registry.ts

@@ -10,7 +10,7 @@
  * To add a language or detector, see the "Adding a detector / language" section
  * of the package README.
  */
-import type { Detector, DetectorScope } from "./types.js";
+import type { Detector, DetectorScope, RuleMeta } from "./types.js";
 import { sourceDetectors } from "./detectors/source.js";
 import { pemDetector } from "./detectors/pem.js";
 
@@ -19,6 +19,12 @@ export function detectorScope(d: Detector): DetectorScope {
   return d.scope ?? "source";
 }
 
+/** A rule plus the detector that emits it — the result of {@link DetectorRegistry.forRule}. */
+export interface RuleCatalogEntry {
+  rule: RuleMeta;
+  detector: Detector;
+}
+
 /**
  * An ordered, id-indexed collection of detectors. Registration order is
  * preserved by {@link all} for deterministic scan output. Ids must be unique.
@@ -57,6 +63,38 @@ export class DetectorRegistry {
     return this.order.map((id) => this.byId.get(id)!);
   }
 
+  /**
+   * The flattened rule catalog: every {@link RuleMeta} declared by every
+   * registered detector, in detector-registration then in-detector order. This
+   * is the single source of truth for rule metadata consumed by SARIF
+   * `rules[]`, the MCP `explain_finding` resolver, and per-rule enable/disable.
+   * Duplicate rule ids across detectors throw (ids are globally unique).
+   */
+  ruleCatalog(): RuleMeta[] {
+    const out: RuleMeta[] = [];
+    const seen = new Set<string>();
+    for (const det of this.all()) {
+      for (const rule of det.rules ?? []) {
+        if (seen.has(rule.id)) {
+          throw new Error(`duplicate rule id in catalog: ${rule.id}`);
+        }
+        seen.add(rule.id);
+        out.push(rule);
+      }
+    }
+    return out;
+  }
+
+  /** Resolve a rule id to its {@link RuleMeta} and the detector that emits it. */
+  forRule(ruleId: string): RuleCatalogEntry | undefined {
+    for (const det of this.all()) {
+      for (const rule of det.rules ?? []) {
+        if (rule.id === ruleId) return { rule, detector: det };
+      }
+    }
+    return undefined;
+  }
+
   /** A shallow copy of this registry (useful to extend the defaults). */
   clone(): DetectorRegistry {
     return new DetectorRegistry(this.all());

package/src/report.ts

@@ -3,7 +3,7 @@
  * 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 { Finding, ScanResult, Severity } from "./types.js";
+import type { Finding, RuleMeta, ScanResult, Severity } from "./types.js";
 import { VERSION } from "./version.js";
 import { SEVERITY_ORDER, sarifLevel } from "./severity.js";
 
@@ -23,6 +23,14 @@ export interface ReportOptions {
    * snippet there IS the sensitive value.
    */
   redactSnippets?: boolean;
+  /**
+   * Full rule catalog to advertise in SARIF `tool.driver.rules[]`, even for
+   * rules that produced no finding in this run. Pass
+   * `defaultRegistry.ruleCatalog()`. When omitted, only the rules that actually
+   * fired are emitted (the historical behaviour). SARIF-only; ignored by
+   * {@link toJson}.
+   */
+  catalog?: RuleMeta[];
 }
 
 const SARIF_SCHEMA =
@@ -56,40 +64,88 @@ function sarifRank(severity: Severity): number {
   }
 }
 
+/** Build a SARIF `rules[]` entry from a rule's severity/title/message/etc. */
+function sarifRule(spec: {
+  id: string;
+  title: string;
+  message: string;
+  severity: Severity;
+  category: string;
+  algorithm?: string;
+  hndl: boolean;
+  cwe?: string;
+  remediation?: string;
+}): Record<string, unknown> {
+  return {
+    id: spec.id,
+    name: spec.id,
+    shortDescription: { text: spec.title },
+    fullDescription: { text: spec.message },
+    defaultConfiguration: { level: sarifLevel(spec.severity), rank: sarifRank(spec.severity) },
+    ...(spec.remediation ? { help: { text: `Remediation: ${spec.remediation}` } } : {}),
+    properties: {
+      category: spec.category,
+      ...(spec.algorithm ? { algorithm: spec.algorithm } : {}),
+      hndl: spec.hndl,
+      ...(spec.cwe ? { cwe: spec.cwe, "security-severity": securitySeverity(spec.severity) } : {}),
+      ...(spec.cwe ? { tags: ["security", spec.cwe] } : {}),
+    },
+    ...(spec.cwe
+      ? {
+          relationships: [
+            { target: { id: spec.cwe, toolComponent: { name: "CWE" } }, kinds: ["relevant"] },
+          ],
+        }
+      : {}),
+  };
+}
+
 /** Serialize a scan result as SARIF 2.1.0. */
 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.
+  // Build the rule set and collect the CWE taxa referenced by any rule. When a
+  // full catalog is supplied, advertise every rule (even ones that didn't fire);
+  // otherwise emit one rule per ruleId encountered (the historical behaviour).
   const ruleIndex = new Map<string, number>();
   const rules: Array<Record<string, unknown>> = [];
   const cweTaxa = new Set<string>();
+
+  for (const r of opts?.catalog ?? []) {
+    if (ruleIndex.has(r.id)) continue;
+    if (r.cwe) cweTaxa.add(r.cwe);
+    ruleIndex.set(r.id, rules.length);
+    rules.push(
+      sarifRule({
+        id: r.id,
+        title: r.title,
+        message: r.message,
+        severity: r.severity,
+        category: r.category,
+        algorithm: r.algorithm,
+        hndl: r.hndl,
+        cwe: r.cwe,
+        remediation: r.remediation,
+      }),
+    );
+  }
+
   for (const f of result.findings) {
     if (f.cwe) cweTaxa.add(f.cwe);
     if (ruleIndex.has(f.ruleId)) continue;
     ruleIndex.set(f.ruleId, rules.length);
-    rules.push({
-      id: f.ruleId,
-      name: f.ruleId,
-      shortDescription: { text: f.title },
-      fullDescription: { text: f.message },
-      defaultConfiguration: { level: sarifLevel(f.severity), rank: sarifRank(f.severity) },
-      ...(f.remediation ? { help: { text: `Remediation: ${f.remediation}` } } : {}),
-      properties: {
+    rules.push(
+      sarifRule({
+        id: f.ruleId,
+        title: f.title,
+        message: f.message,
+        severity: f.severity,
         category: f.category,
-        ...(f.algorithm ? { algorithm: f.algorithm } : {}),
+        algorithm: f.algorithm,
         hndl: f.hndl,
-        ...(f.cwe ? { cwe: f.cwe, "security-severity": securitySeverity(f.severity) } : {}),
-        ...(f.cwe ? { tags: ["security", f.cwe] } : {}),
-      },
-      ...(f.cwe
-        ? {
-            relationships: [
-              { target: { id: f.cwe, toolComponent: { name: "CWE" } }, kinds: ["relevant"] },
-            ],
-          }
-        : {}),
-    });
+        cwe: f.cwe,
+        remediation: f.remediation,
+      }),
+    );
   }
 
   const results = result.findings.map((f) => {

package/src/scan-worker.ts

@@ -23,6 +23,7 @@ interface WorkerToggles {
   config: boolean;
   deps: boolean;
   scanMinified: boolean;
+  disabledRules?: string[];
 }
 
 interface ChunkRequest {
@@ -57,11 +58,17 @@ if (parentPort) {
         filesScanned += 1;
         scannedNames.push(rel);
         findings.push(
-          ...detectFile(rel, content, dets, {
-            source: toggles.source,
-            config: toggles.config,
-            deps: toggles.deps,
-          }),
+          ...detectFile(
+            rel,
+            content,
+            dets,
+            {
+              source: toggles.source,
+              config: toggles.config,
+              deps: toggles.deps,
+            },
+            toggles.disabledRules,
+          ),
         );
       }
 

package/src/scan.ts

@@ -52,6 +52,7 @@ export function detectFile(
   content: string,
   dets: readonly Detector[],
   toggles: { source: boolean; config: boolean; deps: boolean },
+  disabledRules?: readonly string[],
 ): Finding[] {
   const out: Finding[] = [];
 
@@ -66,6 +67,13 @@ export function detectFile(
     out.push(...scanManifest(file, content));
   }
 
+  // Per-rule suppression: drop findings whose ruleId was disabled. Applied here
+  // so both the serial scan and the worker path honour it identically.
+  if (disabledRules && disabledRules.length > 0) {
+    const disabled = new Set(disabledRules);
+    return out.filter((f) => !disabled.has(f.ruleId));
+  }
+
   return out;
 }
 
@@ -144,11 +152,17 @@ export async function scan(options: ScanOptions): Promise<ScanResult> {
 
     filesScanned += 1;
     findings.push(
-      ...detectFile(reportedPath, content, dets, {
-        source: doSource,
-        config: doConfig,
-        deps: doDeps,
-      }),
+      ...detectFile(
+        reportedPath,
+        content,
+        dets,
+        {
+          source: doSource,
+          config: doConfig,
+          deps: doDeps,
+        },
+        options.disabledRules,
+      ),
     );
   }
 

package/src/types.ts

@@ -101,6 +101,46 @@ export type DetectorScope = "source" | "config";
  */
 export type DetectorLanguage = "js" | "python" | "go" | "java" | "any";
 
+/**
+ * Declarative metadata for a single rule a detector can emit. This is the
+ * catalog entry: the stable, queryable description of a rule keyed by the
+ * `ruleId` it stamps onto findings. It is the single source of truth for a
+ * rule's title / severity / category / remediation, consumed by the SARIF
+ * `rules[]` block, the MCP `explain_finding` resolver, and future per-rule
+ * enable/disable + language-pack work.
+ *
+ * For most rules the metadata is fixed and `detect()` builds findings straight
+ * from it (see `findingFromRule`). A few rules are inherently multi-variant
+ * (e.g. `node-crypto-keygen` spans RSA/EC/DSA/DH/Ed25519 at different
+ * severities); for those the metadata here is a REPRESENTATIVE umbrella and
+ * `detect()` refines the per-finding fields at match time. The catalog always
+ * enumerates every emittable ruleId regardless.
+ */
+export interface RuleMeta {
+  /** Stable rule id — matches {@link Finding.ruleId}. Unique across the catalog. */
+  id: string;
+  /** Canonical human title. */
+  title: string;
+  category: FindingCategory;
+  severity: Severity;
+  /** Default confidence for findings of this rule. */
+  confidence: Confidence;
+  /** Harvest-now-decrypt-later exposure. */
+  hndl: boolean;
+  /** Representative classical algorithm family; refined per-finding when it varies. */
+  algorithm?: AlgorithmFamily;
+  /** Associated CWE identifier (e.g. "CWE-327"). */
+  cwe?: string;
+  /** Suggested post-quantum remediation. When omitted, derived from {@link algorithm}. */
+  remediation?: string;
+  /** Canonical one-line human explanation; may be refined per-finding. */
+  message: string;
+  /** True when this rule's matched snippet IS sensitive key material. */
+  sensitive?: boolean;
+  /** Short description of what the rule detects (for catalog / MCP surfaces). */
+  description?: string;
+}
+
 /** A pluggable source detector. Detectors are pure and stateless. */
 export interface Detector {
   /** Unique id, used as the Finding.ruleId prefix space. */
@@ -118,6 +158,13 @@ export interface Detector {
    * Defaults to `"js"` when omitted.
    */
   language?: DetectorLanguage;
+  /**
+   * The rules this detector can emit, as declarative metadata. Together across
+   * all detectors these form the rule catalog ({@link DetectorRegistry.ruleCatalog}).
+   * Optional for backward compatibility with externally-defined detectors, but
+   * all built-in detectors declare it.
+   */
+  rules?: RuleMeta[];
   /** 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. */
@@ -170,6 +217,13 @@ export interface ScanOptions {
    * registry's detectors are used.
    */
   detectors?: Detector[];
+  /**
+   * Rule ids to suppress. Any finding whose `ruleId` is listed here is dropped
+   * after detection. Serializable (a plain string array), so it is honoured on
+   * both the serial and the worker-thread (`scanParallel`) paths. See the rule
+   * catalog ({@link DetectorRegistry.ruleCatalog}) for the valid ids.
+   */
+  disabledRules?: string[];
   /** Optional progress callback. */
   onFile?: (file: string) => void;
   /**

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.2.1";
+export const VERSION = "0.3.0";