@quantakrypto/qscan 0.1.0

package/README.md

@@ -0,0 +1,251 @@
+# @quantakrypto/qscan
+
+**Find quantum-vulnerable cryptography in any codebase.**
+
+`qscan` walks a project and reports where it relies on classical asymmetric
+cryptography (RSA, (EC)DH, ECDSA, EdDSA, DSA, …) — the algorithms broken by a
+sufficiently large quantum computer, and the ones exposed to *harvest-now,
+decrypt-later* (HNDL) attacks today. It scans source files, dependency
+manifests, and configuration, then prints a readiness score and a concrete next
+step.
+
+- **Zero runtime dependencies.** Node built-ins only; the engine is
+  [`@quantakrypto/core`](../core).
+- **CI-friendly.** Severity thresholds drive the exit code; baselines suppress
+  known findings so the build only fails on *new* problems.
+- **Multiple formats.** `human` (default), `json`, SARIF 2.1.0 for code-scanning
+  dashboards, and a CycloneDX 1.6 **CBOM** for compliance tooling.
+- **Fast on big repos.** Optional worker-thread parallelism (`--parallel`) and
+  git-aware incremental scanning (`--changed`).
+
+## Install
+
+```bash
+npm install -g @quantakrypto/qscan
+# or run without installing
+npx @quantakrypto/qscan .
+```
+
+Requires Node ≥ 20.
+
+## Usage
+
+```bash
+qscan [path] [options]
+```
+
+`path` defaults to the current directory (`.`).
+
+### Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--format <human\|json\|sarif\|cbom>` | Output format. | `human` |
+| `--cbom` | Alias for `--format cbom` (CycloneDX 1.6 CBOM). | — |
+| `-o, --output <file>` | Write the report to a file instead of stdout. | stdout |
+| `--severity-threshold <level>` | Exit 1 if any finding is at/above this level. One of `critical`, `high`, `medium`, `low`, `info`. | `high` |
+| `--no-source` | Skip scanning source files for inline crypto. | scan on |
+| `--no-deps` | Skip scanning dependency manifests. | scan on |
+| `--no-config` | Skip scanning config files (TLS/certificates). Toggles config *detectors* — not the config file below. | scan on |
+| `--config <path>` | Use this `quantakrypto.config.json` instead of auto-discovering one at the scan root. | auto |
+| `--no-config-file` | Disable `quantakrypto.config.json` auto-discovery. | discovery on |
+| `--ignore <pattern>` | Exclude paths matching `<pattern>`. Repeatable. | — |
+| `--include <pattern>` | Restrict the scan to paths matching `<pattern>`. Repeatable. | all files |
+| `--max-file-size <bytes>` | Skip files larger than `<bytes>`. | 2 MiB |
+| `--no-default-ignores` | Don't skip `node_modules`/`.git`/`dist` by default. | ignores on |
+| `--scan-minified` | Scan minified/generated/bundled files too. | skipped |
+| `--changed` | Incremental: scan only files git reports as changed. | off |
+| `--since <git-ref>` | With `--changed`, diff against `<git-ref>` (implies `--changed`). | working tree |
+| `--parallel` | Scan using a worker-thread pool when the workload is large enough. | off |
+| `--concurrency <n>` | Worker count for `--parallel` (implies `--parallel`). `0`/`1` forces serial. | CPU count |
+| `--baseline <file>` | Suppress findings whose fingerprint is in the baseline file. | — |
+| `--write-baseline <file>` | Write current findings as a baseline, then exit 0. | — |
+| `--quiet` | Suppress the human summary banner. | off |
+| `-v, --version` | Print version and exit. | — |
+| `-h, --help` | Print help and exit. | — |
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | No findings at/above the threshold — or a baseline was written. |
+| `1` | One or more findings at/above the severity threshold. |
+| `2` | Usage error or I/O failure. |
+
+### Config file (`quantakrypto.config.json`)
+
+qScan auto-discovers a `quantakrypto.config.json` at the scan root and applies it
+under a strict precedence: **CLI flags > config file > built-in defaults**
+(per-key). It encodes `include` / `exclude` / `maxFileSize` / `noDefaultIgnores`
+/ `scanMinified`, the detector-family toggles, `severityThreshold`, and a
+`baseline` path so CI and local runs share one policy. Point at a file elsewhere
+with `--config <path>`, or disable discovery with `--no-config-file`. See
+[docs/CONFIG.md](../../docs/CONFIG.md) for the full schema.
+
+## Example output
+
+```
+qScan — quantum-vulnerable cryptography report
+root: ./examples/vulnerable-app  •  files scanned: 2  •  qscan v0.1.0
+
+3 findings  (2 high, 1 medium)
+2 exposed to harvest-now-decrypt-later (HNDL).
+Readiness score: 70/100
+
+Top findings
+  high     rsa-keygen      src/crypto.js:5
+           RSA is not quantum-safe.
+           → Use ML-KEM-768 (hybrid X25519MLKEM768).
+  high     dep-vulnerable  package.json:7
+           Dependency "node-forge" provides classical asymmetric crypto.
+  medium   ecdh-usage      src/crypto.js:13
+           ECDH is not quantum-safe.
+           → Use a hybrid KEM (X25519MLKEM768).
+
+Next step: migrate src/crypto.js — Use ML-KEM-768 (hybrid X25519MLKEM768).
+```
+
+Color is emitted only when writing the human format to an interactive terminal
+(and is suppressed by the `NO_COLOR` environment variable). Reports written to a
+file or piped are always plain text.
+
+## Baselines
+
+A baseline records the **fingerprints** of findings you have already triaged.
+qScan uses the **canonical baseline** shared across the whole monorepo
+(`@quantakrypto/core`, the GitHub Action, and this CLI): a single on-disk format and a
+single fingerprint algorithm, so a baseline written by one tool is understood by
+the others.
+
+A fingerprint is a full SHA-256 of `ruleId|file|normalizedSnippet`. It is
+deliberately **line-insensitive** — unrelated edits that shift line numbers no
+longer invalidate it — and the snippet's whitespace is normalized so
+reformatting doesn't either. It ignores volatile fields like severity wording or
+timestamps.
+
+```bash
+# 1. Accept the current state of the world.
+qscan . --write-baseline qscan-baseline.json
+
+# 2. From now on, fail only on findings that are NOT in the baseline.
+qscan . --baseline qscan-baseline.json
+```
+
+The baseline file is plain JSON:
+
+```json
+{
+  "version": 1,
+  "fingerprints": [
+    "0f1e2d3c4b5a...full-sha256...",
+    "a1b2c3d4e5f6...full-sha256..."
+  ]
+}
+```
+
+## Incremental scans
+
+In CI you usually only care about what a change introduced. `--changed` restricts
+the scan to the files git reports as modified, which is a large win on big repos:
+
+```bash
+# Files modified in the working tree (staged, unstaged, and untracked).
+qscan . --changed
+
+# Everything that changed since a base ref (e.g. a PR base).
+qscan . --changed --since origin/main
+```
+
+Outside a git work tree the changed-file list is empty (nothing is scanned),
+rather than an error.
+
+## Parallel scans
+
+For large trees, route the scan through a worker-thread pool. qScan automatically
+stays serial for small inputs, so `--parallel` is safe to leave on:
+
+```bash
+qscan . --parallel               # auto worker count (CPU cores)
+qscan . --concurrency 4          # pin the worker count (implies --parallel)
+```
+
+## CBOM (CycloneDX)
+
+Emit a CycloneDX 1.6 **cryptographic bill of materials** — one
+`cryptographic-asset` component per distinct (algorithm, primitive) pair, with
+file:line occurrence evidence — for compliance and supply-chain tooling:
+
+```bash
+qscan . --cbom -o qscan-cbom.json
+# equivalently:
+qscan . --format cbom -o qscan-cbom.json
+```
+
+The output is deterministic (sorted components and occurrences, stable serial
+number), so re-running on an unchanged tree produces byte-identical CBOMs.
+
+## CI
+
+Fail the build on any high-or-worse finding, while tolerating an accepted
+baseline:
+
+```yaml
+# .github/workflows/qscan.yml
+name: qscan
+on: [push, pull_request]
+
+jobs:
+  quantum-readiness:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Scan for quantum-vulnerable crypto
+        run: npx @quantakrypto/qscan . --severity-threshold high --baseline qscan-baseline.json
+
+      # Optional: upload SARIF to GitHub code scanning.
+      - name: Generate SARIF
+        if: always()
+        run: npx @quantakrypto/qscan . --format sarif -o qscan.sarif
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: qscan.sarif
+```
+
+## Programmatic API
+
+The CLI is a thin shell over `runQscan`, which `@quantakrypto/action` reuses:
+
+```ts
+import { runQscan, EXIT } from "@quantakrypto/qscan";
+
+const { result, exitCode, suppressed } = await runQscan({
+  path: "src",
+  format: "json",
+  severityThreshold: "high",
+  baseline: "qscan-baseline.json",
+});
+
+console.log(`${result.findings.length} findings, exit ${exitCode}`);
+if (exitCode === EXIT.FINDINGS) process.exitCode = 1;
+```
+
+`runQscan` never touches `process` or stdout — it returns the rendered `report`
+string and a suggested `exitCode`, leaving I/O to the caller. The package also
+re-exports the argument parser (`parseArgs`, `defaultOptions`), severity helpers
+(`severityRank`, `meetsThreshold`), and the **canonical** baseline utilities from
+`@quantakrypto/core` (`fingerprintFinding`, `baselineFromFindings`, `applyBaseline`,
+`loadBaseline`, `saveBaseline`) plus their legacy aliases (`fingerprint`,
+`buildBaseline`, `readBaseline`, `writeBaseline`) for source compatibility.
+
+## Examples
+
+See [`examples/`](./examples) for a sample vulnerable project and the commands
+to scan it.
+
+## License
+
+Apache-2.0

package/dist/args.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Zero-dependency command-line argument parsing for qScan.
+ *
+ * Hand-rolled rather than pulled from a library to keep the package free of
+ * runtime dependencies. The grammar is deliberately small: long flags
+ * (`--flag`, `--flag value`, `--flag=value`), a couple of short aliases
+ * (`-o`, `-v`, `-h`), repeatable `--ignore`, and a single optional positional
+ * path. Unknown flags are a usage error.
+ */
+import type { ReportFormat, Severity } from "@quantakrypto/core";
+/** Severities ordered most → least severe; index 0 is the most severe. */
+export declare const SEVERITY_ORDER: readonly Severity[];
+/**
+ * Output formats qScan accepts on the command line. Extends core's
+ * {@link ReportFormat} with `"cbom"` (a CycloneDX cryptographic bill of
+ * materials), which qScan renders locally via core's `toCbom`.
+ */
+export type QscanFormat = ReportFormat | "cbom";
+/** Fully-resolved options the CLI/programmatic runner operates on. */
+export interface QscanOptions {
+    /** Directory or file to scan. */
+    path: string;
+    /** Report format. */
+    format: QscanFormat;
+    /** Write the report to this file instead of stdout, when set. */
+    output?: string;
+    /** Findings at or above this severity cause a non-zero exit. */
+    severityThreshold: Severity;
+    /** Scan source files for inline crypto usage. */
+    source: boolean;
+    /** Scan dependency manifests for vulnerable libraries. */
+    dependencies: boolean;
+    /** Scan config files (TLS/certificates). */
+    config: boolean;
+    /** Extra exclude patterns (repeatable `--ignore`). */
+    ignore: string[];
+    /**
+     * Restrict the walk to paths matching one of these include patterns
+     * (repeatable `--include`). When empty, every non-excluded file is scanned.
+     */
+    include: string[];
+    /** Max file size to read, in bytes (`--max-file-size`). */
+    maxFileSize?: number;
+    /** Disable the built-in ignore list (`--no-default-ignores`). */
+    noDefaultIgnores: boolean;
+    /** Scan minified/generated/bundled files instead of skipping them. */
+    scanMinified: boolean;
+    /**
+     * Incremental mode: scan only the files git reports as changed
+     * (`--changed`), optionally relative to {@link since}.
+     */
+    changed: boolean;
+    /** Git ref/range the `--changed` diff is taken against (`--since`). */
+    since?: string;
+    /** Route the scan through core's worker-thread pool (`--parallel`). */
+    parallel: boolean;
+    /**
+     * Worker count for parallel scanning (`--concurrency`). Implies parallel.
+     * A value of 0 or 1 forces the in-process serial path.
+     */
+    concurrency?: number;
+    /** Suppress findings whose fingerprint is in this baseline file. */
+    baseline?: string;
+    /** Write current findings as a baseline to this file, then exit 0. */
+    writeBaseline?: string;
+    /** Suppress the human summary banner (still writes reports/output files). */
+    quiet: boolean;
+    /**
+     * Explicit path to a `quantakrypto.config.json` (`--config <path>`). Overrides
+     * auto-discovery at the scan root. Distinct from `--no-config`, which toggles
+     * config/TLS *detector* scanning — this names the config FILE.
+     */
+    configFile?: string;
+    /**
+     * Disable `quantakrypto.config.json` auto-discovery (`--no-config-file`). Distinct
+     * from `--no-config` (which skips config-file *detectors*).
+     */
+    noConfigFile: boolean;
+}
+/**
+ * Option keys that a `quantakrypto.config.json` may also set. When such a key was set
+ * by a CLI flag, the flag wins (precedence: flags > config > defaults); when it
+ * was left at its default, config may fill it. {@link parseArgs} records which
+ * of these keys came from an explicit flag in {@link ParsedRun.explicit}.
+ */
+export type ConfigurableKey = "severityThreshold" | "source" | "dependencies" | "config" | "include" | "ignore" | "maxFileSize" | "noDefaultIgnores" | "scanMinified" | "baseline";
+/** A successful parse: resolved options plus which configurable keys were explicit. */
+export interface ParsedRun {
+    kind: "run";
+    options: QscanOptions;
+    /** The set of {@link ConfigurableKey}s the user set via a flag. */
+    explicit: Set<ConfigurableKey>;
+}
+/** Result of {@link parseArgs}: either resolved options or a meta action. */
+export type ParsedArgs = ParsedRun | {
+    kind: "help";
+} | {
+    kind: "version";
+};
+/** Thrown on malformed input; the CLI maps this to exit code 2. */
+export declare class ArgError extends Error {
+    readonly name = "ArgError";
+}
+/** Default options, before any flags are applied. */
+export declare function defaultOptions(): QscanOptions;
+/**
+ * Parse a raw argv slice (i.e. without `node` and the script path).
+ *
+ * @throws {ArgError} On unknown flags, missing values, or invalid enum values.
+ */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+/** Validate/normalize a `--format` value. */
+export declare function asFormat(value: string): QscanFormat;
+/** Validate/normalize a non-negative integer flag value. */
+export declare function asInt(value: string, flag: string): number;
+/** Validate/normalize a severity value. */
+export declare function asSeverity(value: string): Severity;
+/**
+ * Rank a severity: lower number = more severe.
+ * `critical` → 0, `info` → 4.
+ */
+export declare function severityRank(severity: Severity): number;
+/**
+ * Whether `severity` is at or above `threshold` in seriousness.
+ * E.g. `high` meets a `medium` threshold; `low` does not.
+ */
+export declare function meetsThreshold(severity: Severity, threshold: Severity): boolean;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/args.js

@@ -0,0 +1,200 @@
+/**
+ * Zero-dependency command-line argument parsing for qScan.
+ *
+ * Hand-rolled rather than pulled from a library to keep the package free of
+ * runtime dependencies. The grammar is deliberately small: long flags
+ * (`--flag`, `--flag value`, `--flag=value`), a couple of short aliases
+ * (`-o`, `-v`, `-h`), repeatable `--ignore`, and a single optional positional
+ * path. Unknown flags are a usage error.
+ */
+/** Severities ordered most → least severe; index 0 is the most severe. */
+export const SEVERITY_ORDER = ["critical", "high", "medium", "low", "info"];
+const FORMATS = ["human", "json", "sarif", "cbom"];
+/** Thrown on malformed input; the CLI maps this to exit code 2. */
+export class ArgError extends Error {
+    name = "ArgError";
+}
+/** Default options, before any flags are applied. */
+export function defaultOptions() {
+    return {
+        path: ".",
+        format: "human",
+        severityThreshold: "high",
+        source: true,
+        dependencies: true,
+        config: true,
+        ignore: [],
+        include: [],
+        noDefaultIgnores: false,
+        scanMinified: false,
+        changed: false,
+        parallel: false,
+        quiet: false,
+        noConfigFile: false,
+    };
+}
+/**
+ * Parse a raw argv slice (i.e. without `node` and the script path).
+ *
+ * @throws {ArgError} On unknown flags, missing values, or invalid enum values.
+ */
+export function parseArgs(argv) {
+    const options = defaultOptions();
+    const explicit = new Set();
+    let positional;
+    // Manual index walk so flags can consume the following token as a value.
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        // `--flag=value` → split into flag + inline value.
+        let inlineValue;
+        let flag = arg;
+        if (arg.startsWith("--") && arg.includes("=")) {
+            const eq = arg.indexOf("=");
+            flag = arg.slice(0, eq);
+            inlineValue = arg.slice(eq + 1);
+        }
+        /** Consume a value for `flag`: prefer the inline `=value`, else the next token. */
+        const takeValue = () => {
+            if (inlineValue !== undefined)
+                return inlineValue;
+            const next = argv[i + 1];
+            if (next === undefined || (next.startsWith("-") && next !== "-")) {
+                throw new ArgError(`option "${flag}" requires a value`);
+            }
+            i++;
+            return next;
+        };
+        switch (flag) {
+            case "-h":
+            case "--help":
+                return { kind: "help" };
+            case "-v":
+            case "--version":
+                return { kind: "version" };
+            case "--format":
+                options.format = asFormat(takeValue());
+                break;
+            case "--cbom":
+                options.format = "cbom";
+                break;
+            case "-o":
+            case "--output":
+                options.output = takeValue();
+                break;
+            case "--severity-threshold":
+                options.severityThreshold = asSeverity(takeValue());
+                explicit.add("severityThreshold");
+                break;
+            case "--no-source":
+                options.source = false;
+                explicit.add("source");
+                break;
+            case "--no-deps":
+                options.dependencies = false;
+                explicit.add("dependencies");
+                break;
+            case "--no-config":
+                options.config = false;
+                explicit.add("config");
+                break;
+            case "--ignore":
+                options.ignore.push(takeValue());
+                explicit.add("ignore");
+                break;
+            case "--include":
+                options.include.push(takeValue());
+                explicit.add("include");
+                break;
+            case "--max-file-size":
+                options.maxFileSize = asInt(takeValue(), "--max-file-size");
+                explicit.add("maxFileSize");
+                break;
+            case "--no-default-ignores":
+                options.noDefaultIgnores = true;
+                explicit.add("noDefaultIgnores");
+                break;
+            case "--scan-minified":
+                options.scanMinified = true;
+                explicit.add("scanMinified");
+                break;
+            // `quantakrypto.config.json` FILE controls (distinct from `--no-config`, which
+            // toggles config/TLS *detector* scanning above).
+            case "--config":
+                options.configFile = takeValue();
+                break;
+            case "--no-config-file":
+                options.noConfigFile = true;
+                break;
+            case "--changed":
+                options.changed = true;
+                break;
+            case "--since":
+                options.since = takeValue();
+                options.changed = true; // --since implies incremental mode
+                break;
+            case "--parallel":
+                options.parallel = true;
+                break;
+            case "--concurrency":
+                options.concurrency = asInt(takeValue(), "--concurrency");
+                options.parallel = true; // an explicit worker count implies parallel
+                break;
+            case "--baseline":
+                options.baseline = takeValue();
+                explicit.add("baseline");
+                break;
+            case "--write-baseline":
+                options.writeBaseline = takeValue();
+                break;
+            case "--quiet":
+                options.quiet = true;
+                break;
+            default:
+                if (flag.startsWith("-") && flag !== "-") {
+                    throw new ArgError(`unknown option "${flag}"`);
+                }
+                if (positional !== undefined) {
+                    throw new ArgError(`unexpected extra argument "${arg}" (path already set to "${positional}")`);
+                }
+                positional = arg;
+                break;
+        }
+    }
+    if (positional !== undefined)
+        options.path = positional;
+    return { kind: "run", options, explicit };
+}
+/** Validate/normalize a `--format` value. */
+export function asFormat(value) {
+    if (FORMATS.includes(value))
+        return value;
+    throw new ArgError(`invalid --format "${value}" (expected one of: ${FORMATS.join(", ")})`);
+}
+/** Validate/normalize a non-negative integer flag value. */
+export function asInt(value, flag) {
+    if (!/^\d+$/.test(value)) {
+        throw new ArgError(`invalid ${flag} "${value}" (expected a non-negative integer)`);
+    }
+    return Number.parseInt(value, 10);
+}
+/** Validate/normalize a severity value. */
+export function asSeverity(value) {
+    if (SEVERITY_ORDER.includes(value))
+        return value;
+    throw new ArgError(`invalid severity "${value}" (expected one of: ${SEVERITY_ORDER.join(", ")})`);
+}
+/**
+ * Rank a severity: lower number = more severe.
+ * `critical` → 0, `info` → 4.
+ */
+export function severityRank(severity) {
+    return SEVERITY_ORDER.indexOf(severity);
+}
+/**
+ * Whether `severity` is at or above `threshold` in seriousness.
+ * E.g. `high` meets a `medium` threshold; `low` does not.
+ */
+export function meetsThreshold(severity, threshold) {
+    return severityRank(severity) <= severityRank(threshold);
+}
+//# sourceMappingURL=args.js.map

package/dist/args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.js","sourceRoot":"","sources":["../src/args.ts"],"names":[],"mappings":"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"}

package/dist/baseline.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Baseline support for qScan — a thin adapter over the **canonical** baseline
+ * implementation in `@quantakrypto/core` (P1-1).
+ *
+ * Historically qScan carried its own baseline scheme (12-char hash of
+ * `ruleId|file|snippet|line`) that was incompatible with the GitHub Action's.
+ * Both have been unified onto core's single source of truth, so this module no
+ * longer defines its own format or hashing — it re-exports core's primitives
+ * and adds only the small filename-resolution / API-shape conveniences the CLI
+ * and `@quantakrypto/action` rely on.
+ *
+ * The on-disk format is core's {@link Baseline}: `{ version, fingerprints }`,
+ * where each fingerprint is a full, line-INSENSITIVE SHA-256 (so unrelated edits
+ * that shift line numbers no longer invalidate a baseline).
+ */
+import { baselineFromFindings, BASELINE_VERSION, fingerprintFinding, loadBaseline, saveBaseline } from "@quantakrypto/core";
+import type { Baseline, Finding } from "@quantakrypto/core";
+export { baselineFromFindings, BASELINE_VERSION, fingerprintFinding, loadBaseline, saveBaseline };
+export type { Baseline };
+/**
+ * Compute a stable fingerprint for a finding. Alias for core's
+ * {@link fingerprintFinding}; kept under the historical name `fingerprint` for
+ * source compatibility with existing call sites and tests.
+ */
+export declare const fingerprint: typeof fingerprintFinding;
+/**
+ * Partition findings into those kept and those suppressed by a baseline.
+ *
+ * Wraps core's {@link coreApplyBaseline} (which takes a {@link Baseline} and
+ * returns `{ newFindings, suppressed }`) but preserves qScan's historical
+ * `{ kept, suppressed }` shape and its lenient `ReadonlySet<string>` overload so
+ * existing callers keep working.
+ *
+ * @param findings All findings produced by a scan.
+ * @param baseline Either a {@link Baseline} object or a set of accepted
+ *   fingerprints.
+ */
+export declare function applyBaseline(findings: readonly Finding[], baseline: Baseline | ReadonlySet<string>): {
+    kept: Finding[];
+    suppressed: Finding[];
+};
+/**
+ * Build a {@link Baseline} from a set of findings (deduped + sorted). Alias for
+ * core's {@link baselineFromFindings} under qScan's historical name.
+ */
+export declare function buildBaseline(findings: readonly Finding[]): Baseline;
+/**
+ * Read a baseline file from disk and return its accepted fingerprints as a set.
+ *
+ * Unlike core's tolerant {@link loadBaseline} (which returns an empty baseline
+ * for a missing/unparseable file), this preserves qScan's historical *strict*
+ * contract: a missing or malformed file is an error, surfaced to the CLI as an
+ * I/O failure (exit 2).
+ *
+ * @throws {Error} If the file cannot be read or is not valid baseline JSON.
+ */
+export declare function readBaseline(path: string): Promise<Set<string>>;
+/** Serialize and write a baseline to disk (pretty-printed, trailing newline). */
+export declare function writeBaseline(path: string, baseline: Baseline): Promise<void>;
+//# sourceMappingURL=baseline.d.ts.map

package/dist/baseline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.d.ts","sourceRoot":"","sources":["../src/baseline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAEL,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,YAAY,EACb,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAClG,YAAY,EAAE,QAAQ,EAAE,CAAC;AAEzB;;;;GAIG;AACH,eAAO,MAAM,WAAW,2BAAqB,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,OAAO,EAAE,EAC5B,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC,MAAM,CAAC,GACvC;IAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAAC,UAAU,EAAE,OAAO,EAAE,CAAA;CAAE,CAO5C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,QAAQ,CAEpE;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAoBrE;AAED,iFAAiF;AACjF,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAQnF"}