@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/parse/tree-store.js

@@ -0,0 +1,236 @@
+/**
+ * THE TREE STORE  (how a scan stops running out of memory)
+ * ========================================================
+ *
+ * THE PROBLEM, STATED HONESTLY.
+ *
+ * A tree-sitter syntax tree does not live in JavaScript memory. It lives in a
+ * WebAssembly heap that the garbage collector cannot see into, so a tree is
+ * never collected, however dead it looks - the only thing that frees one is an
+ * explicit call to tree.delete().
+ *
+ * Until this module existed, nothing in this project called delete(). Every file
+ * parsed stayed parsed until the process exited. Measured on Django:
+ *
+ *     248 files   0.9 MB source   173 MB peak
+ *     992 files   6.9 MB source   525 MB peak      ~59x per marginal byte
+ *
+ * which puts the hard ceiling at roughly 44 MB of source on an 8 GB machine.
+ * Most serious repositories are bigger than that. The scan does not slow down
+ * at the ceiling; it is killed by the operating system, which is a worse
+ * failure than a slow answer because it produces no answer at all.
+ *
+ * THE EXPLANATION THAT WAS IN THE CODE, AND WHY IT WAS WRONG.
+ *
+ * A comment above the parse loop said the trees had to be held because
+ * cross-file tracing must be able to resolve into any file at any time, and
+ * that this was why `--no-cross-file` existed. Plausible, and false. Measured:
+ *
+ *     cross-file ON     528.8 MB
+ *     cross-file OFF    535.8 MB
+ *
+ * Turning the feature off freed nothing, because the trees were never freed in
+ * either mode. The stated cause was a rationalisation of an accident. It is
+ * recorded here because a wrong explanation is more expensive than no
+ * explanation: it stops anybody looking.
+ *
+ * WHAT THIS MODULE DOES.
+ *
+ * It owns every tree in the scan and holds as many as a stated budget allows,
+ * evicting the least recently used one when the budget is exceeded. A file
+ * whose tree was evicted is simply parsed again when something needs it. So:
+ *
+ *   - a project that fits in the budget behaves exactly as before, parses each
+ *     file exactly once, and runs at exactly the old speed;
+ *   - a project that does not fit gets slower instead of getting killed.
+ *
+ * Time is a renewable resource and a dead process is not.
+ *
+ * PINNING - THE PART THAT WOULD BE A CRASH IF IT WERE WRONG.
+ *
+ * Evicting a tree frees the WebAssembly memory that every Node object from it
+ * points into. A Node whose tree has been deleted is not an error; it is a
+ * dangling pointer into a heap that now holds something else, and reading it
+ * yields silent nonsense. So a tree is pinned for as long as anything might
+ * still hold a node from it, and eviction skips pinned entries entirely, even
+ * when that means going over budget. Going over budget is visible in the stats
+ * and is the right answer: correctness first, then memory, then speed.
+ */
+import { parseSourceSync } from './parser.js';
+/**
+ * How many bytes of WebAssembly heap one byte of source costs once parsed.
+ *
+ * MEASURED, not guessed: 6.9 MB of Django source produced a 525 MB peak against
+ * a ~120 MB floor (Node plus seven loaded grammars), which is about 59x. Sixty
+ * is used because the number varies by language and an underestimate is the
+ * dangerous direction - it would let the store believe it is inside a budget it
+ * has already blown.
+ *
+ * The estimate only decides WHEN to evict. Nothing is ever wrong because this
+ * number is off; the scan just holds slightly more or less than intended.
+ */
+export const TREE_BYTES_PER_SOURCE_BYTE = 60;
+/**
+ * Default budget: roughly a gigabyte of trees, which is about 17 MB of source
+ * held at once. Chosen so that every project this tool has been run against so
+ * far fits entirely and therefore parses each file exactly once - the redesign
+ * should cost nothing on the sizes people actually scan, and only start trading
+ * time for memory past the point where the old code died.
+ */
+export const DEFAULT_TREE_BUDGET_BYTES = 1024 * 1024 * 1024;
+/**
+ * Find the node at an exact byte range in a freshly parsed tree.
+ *
+ * This is the hinge of the whole design. The index records a function body as
+ * two byte offsets instead of a Node, because a Node keeps its tree alive and
+ * the point is to let trees go. When the tracer finally wants that body, the
+ * file is parsed again and the node is looked up here.
+ *
+ * Two things make it safe. The parse is deterministic - same bytes, same
+ * grammar, same tree - so the node is certainly there. And the result is
+ * CHECKED: the range and the node type must both match what was recorded, or
+ * this returns null and the caller declines to resolve. Tracing into a node we
+ * merely believe is the right one would manufacture exactly the kind of
+ * confident, wrong proof this project exists to avoid.
+ *
+ * The walk upward is needed because descendantForIndex returns the SMALLEST
+ * node covering a range, and a node can share its exact extent with its parent
+ * (a block that is its own statement, an expression that is its own body). The
+ * recorded type disambiguates them.
+ */
+export function nodeAtRange(root, startIndex, endIndex, type) {
+    let node = root.descendantForIndex(startIndex, endIndex);
+    let hops = 0;
+    while (node && hops < 64) {
+        if (node.startIndex === startIndex && node.endIndex === endIndex && node.type === type) {
+            return node;
+        }
+        node = node.parent;
+        hops++;
+    }
+    return null;
+}
+export function createTreeStore(budgetBytes = DEFAULT_TREE_BUDGET_BYTES) {
+    const entries = new Map();
+    let heldBytes = 0;
+    let peakEstimatedBytes = 0;
+    let clock = 0;
+    let parses = 0;
+    let reparses = 0;
+    let evictions = 0;
+    let spilled = false;
+    let overBudgetWhileAllPinned = 0;
+    const touch = (entry) => {
+        entry.lastUsed = ++clock;
+    };
+    const drop = (entry) => {
+        if (!entry.tree)
+            return;
+        entry.tree.delete();
+        entry.tree = null;
+        heldBytes -= entry.estimatedBytes;
+        evictions++;
+        spilled = true;
+    };
+    /** Evict least-recently-used unpinned trees until we are inside the budget. */
+    const makeRoom = () => {
+        if (heldBytes <= budgetBytes)
+            return;
+        const candidates = [...entries.values()]
+            .filter((e) => e.tree !== null && e.pins === 0)
+            .sort((a, b) => a.lastUsed - b.lastUsed);
+        for (const candidate of candidates) {
+            if (heldBytes <= budgetBytes)
+                return;
+            drop(candidate);
+        }
+        // Everything still resident is pinned. We go over budget rather than free
+        // a tree somebody is holding a node from. Counted, never hidden.
+        if (heldBytes > budgetBytes)
+            overBudgetWhileAllPinned++;
+    };
+    const note = () => {
+        if (heldBytes > peakEstimatedBytes)
+            peakEstimatedBytes = heldBytes;
+    };
+    return {
+        admit(path, source, grammar, tree) {
+            const existing = entries.get(path);
+            if (existing) {
+                // Re-admitting the same path would leak the tree already held for it.
+                if (existing.tree && existing.tree !== tree)
+                    existing.tree.delete();
+                else if (existing.tree === null)
+                    heldBytes += existing.estimatedBytes;
+                existing.tree = tree;
+                touch(existing);
+                note();
+                makeRoom();
+                return;
+            }
+            const entry = {
+                path,
+                source,
+                grammar,
+                estimatedBytes: source.length * TREE_BYTES_PER_SOURCE_BYTE,
+                tree,
+                pins: 0,
+                lastUsed: ++clock,
+            };
+            entries.set(path, entry);
+            heldBytes += entry.estimatedBytes;
+            parses++;
+            note();
+            makeRoom();
+        },
+        get(path) {
+            const entry = entries.get(path);
+            if (!entry) {
+                throw new Error(`No file registered at ${path}. Every file must be admitted during the ` +
+                    'first pass; asking for one that was not is a bug, not a missing file.');
+            }
+            if (entry.tree) {
+                touch(entry);
+                return entry.tree;
+            }
+            entry.tree = parseSourceSync(entry.source, entry.grammar);
+            heldBytes += entry.estimatedBytes;
+            parses++;
+            reparses++;
+            touch(entry);
+            note();
+            makeRoom();
+            return entry.tree;
+        },
+        pin(path) {
+            const entry = entries.get(path);
+            if (entry)
+                entry.pins++;
+        },
+        releaseAll() {
+            for (const entry of entries.values())
+                entry.pins = 0;
+            makeRoom();
+        },
+        disposeAll() {
+            for (const entry of entries.values()) {
+                if (entry.tree)
+                    entry.tree.delete();
+                entry.tree = null;
+            }
+            heldBytes = 0;
+            entries.clear();
+        },
+        stats: () => ({
+            budgetBytes,
+            filesResident: [...entries.values()].filter((e) => e.tree !== null).length,
+            peakEstimatedBytes,
+            parses,
+            reparses,
+            evictions,
+            spilled,
+            overBudgetWhileAllPinned,
+        }),
+    };
+}
+//# sourceMappingURL=tree-store.js.map

package/dist/src/parse/tree-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-store.js","sourceRoot":"","sources":["../../../src/parse/tree-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAmD5D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CACzB,IAAU,EACV,UAAkB,EAClB,QAAgB,EAChB,IAAY;IAEZ,IAAI,IAAI,GAAgB,IAAI,CAAC,kBAAkB,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACtE,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,OAAO,IAAI,IAAI,IAAI,GAAG,EAAE,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,UAAU,KAAK,UAAU,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvF,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;QACnB,IAAI,EAAE,CAAC;IACT,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,WAAW,GAAG,yBAAyB;IACrE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IACzC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,wBAAwB,GAAG,CAAC,CAAC;IAEjC,MAAM,KAAK,GAAG,CAAC,KAAY,EAAQ,EAAE;QACnC,KAAK,CAAC,QAAQ,GAAG,EAAE,KAAK,CAAC;IAC3B,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,CAAC,KAAY,EAAQ,EAAE;QAClC,IAAI,CAAC,KAAK,CAAC,IAAI;YAAE,OAAO;QACxB,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;QAClB,SAAS,IAAI,KAAK,CAAC,cAAc,CAAC;QAClC,SAAS,EAAE,CAAC;QACZ,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC,CAAC;IAEF,+EAA+E;IAC/E,MAAM,QAAQ,GAAG,GAAS,EAAE;QAC1B,IAAI,SAAS,IAAI,WAAW;YAAE,OAAO;QAErC,MAAM,UAAU,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;aACrC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;aAC9C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAE3C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,IAAI,SAAS,IAAI,WAAW;gBAAE,OAAO;YACrC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClB,CAAC;QAED,0EAA0E;QAC1E,iEAAiE;QACjE,IAAI,SAAS,GAAG,WAAW;YAAE,wBAAwB,EAAE,CAAC;IAC1D,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,SAAS,GAAG,kBAAkB;YAAE,kBAAkB,GAAG,SAAS,CAAC;IACrE,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI;YAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACnC,IAAI,QAAQ,EAAE,CAAC;gBACb,sEAAsE;gBACtE,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;oBAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;qBAC/D,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI;oBAAE,SAAS,IAAI,QAAQ,CAAC,cAAc,CAAC;gBACtE,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC;gBACrB,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAChB,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,CAAC;gBACX,OAAO;YACT,CAAC;YAED,MAAM,KAAK,GAAU;gBACnB,IAAI;gBACJ,MAAM;gBACN,OAAO;gBACP,cAAc,EAAE,MAAM,CAAC,MAAM,GAAG,0BAA0B;gBAC1D,IAAI;gBACJ,IAAI,EAAE,CAAC;gBACP,QAAQ,EAAE,EAAE,KAAK;aAClB,CAAC;YACF,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACzB,SAAS,IAAI,KAAK,CAAC,cAAc,CAAC;YAClC,MAAM,EAAE,CAAC;YACT,IAAI,EAAE,CAAC;YACP,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,GAAG,CAAC,IAAI;YACN,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CACb,yBAAyB,IAAI,2CAA2C;oBACtE,uEAAuE,CAC1E,CAAC;YACJ,CAAC;YACD,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACf,KAAK,CAAC,KAAK,CAAC,CAAC;gBACb,OAAO,KAAK,CAAC,IAAI,CAAC;YACpB,CAAC;YACD,KAAK,CAAC,IAAI,GAAG,eAAe,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YAC1D,SAAS,IAAI,KAAK,CAAC,cAAc,CAAC;YAClC,MAAM,EAAE,CAAC;YACT,QAAQ,EAAE,CAAC;YACX,KAAK,CAAC,KAAK,CAAC,CAAC;YACb,IAAI,EAAE,CAAC;YACP,QAAQ,EAAE,CAAC;YACX,OAAO,KAAK,CAAC,IAAI,CAAC;QACpB,CAAC;QAED,GAAG,CAAC,IAAI;YACN,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,KAAK;gBAAE,KAAK,CAAC,IAAI,EAAE,CAAC;QAC1B,CAAC;QAED,UAAU;YACR,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE;gBAAE,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;YACrD,QAAQ,EAAE,CAAC;QACb,CAAC;QAED,UAAU;YACR,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;gBACrC,IAAI,KAAK,CAAC,IAAI;oBAAE,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBACpC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC;YACpB,CAAC;YACD,SAAS,GAAG,CAAC,CAAC;YACd,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;QAED,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACZ,WAAW;YACX,aAAa,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,MAAM;YAC1E,kBAAkB;YAClB,MAAM;YACN,QAAQ;YACR,SAAS;YACT,OAAO;YACP,wBAAwB;SACzB,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/src/platform/dependency-rule.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The dependency check's rule text and report shape, kept apart from deps.ts
+ * because the reports (which also run in the browser) need them and deps.ts
+ * reads the file system. Browser-safe: no imports.
+ */
+export declare const DEPENDENCY_RULE: {
+    readonly id: "vulnerable-dependency";
+    readonly name: "Library version with a published advisory";
+    readonly owasp: "A03:2025 Software Supply Chain Failures";
+    readonly summary: "A library this project pins has a published security advisory for that exact version.";
+    readonly fix: "Upgrade the library to a fixed version and regenerate the lockfile.";
+    readonly explanation: string;
+    readonly limitations: string;
+};
+/** What the dependency check read and asked, for the report's "what was checked" section. */
+export interface DependencyReport {
+    readonly source: 'api.osv.dev';
+    readonly checkedAt: string;
+    readonly read: ReadonlyArray<{
+        readonly file: string;
+        readonly packages: number;
+        readonly skipped: readonly string[];
+    }>;
+    readonly notRead: readonly string[];
+    readonly checked: number;
+    readonly incomplete: readonly string[];
+}

package/dist/src/platform/dependency-rule.js

@@ -0,0 +1,21 @@
+/**
+ * The dependency check's rule text and report shape, kept apart from deps.ts
+ * because the reports (which also run in the browser) need them and deps.ts
+ * reads the file system. Browser-safe: no imports.
+ */
+export const DEPENDENCY_RULE = {
+    id: 'vulnerable-dependency',
+    name: 'Library version with a published advisory',
+    owasp: 'A03:2025 Software Supply Chain Failures',
+    summary: 'A library this project pins has a published security advisory for that exact version.',
+    fix: 'Upgrade the library to a fixed version and regenerate the lockfile.',
+    explanation: 'Most of the code a project runs was written by someone else and arrives through its lockfile. ' +
+        'When a pinned library version has a published advisory, the flaw is installed with it - whatever ' +
+        'the project\'s own code does. The fix is usually an upgrade, not a code change.',
+    limitations: 'Says the vulnerable version is installed, not that this project calls the vulnerable part - many ' +
+        'advisories cover one function the project never uses. Reads package-lock.json, composer.lock, ' +
+        'requirements.txt (== pins only) and go.mod; other lockfiles are listed as not read. Advisories come ' +
+        'from osv.dev at scan time, so the same lockfile can gain findings tomorrow. Runs only with --deps, ' +
+        'because it is the one check that sends anything off the machine: package names and versions, never code.',
+};
+//# sourceMappingURL=dependency-rule.js.map

package/dist/src/platform/dependency-rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-rule.js","sourceRoot":"","sources":["../../../src/platform/dependency-rule.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,EAAE,EAAE,uBAAuB;IAC3B,IAAI,EAAE,2CAA2C;IACjD,KAAK,EAAE,yCAAyC;IAChD,OAAO,EAAE,uFAAuF;IAChG,GAAG,EAAE,qEAAqE;IAC1E,WAAW,EACT,gGAAgG;QAChG,mGAAmG;QACnG,iFAAiF;IACnF,WAAW,EACT,mGAAmG;QACnG,gGAAgG;QAChG,sGAAsG;QACtG,qGAAqG;QACrG,0GAA0G;CACpG,CAAC"}

package/dist/src/platform/deps.d.ts

@@ -0,0 +1,86 @@
+/**
+ * THE DEPENDENCY CHECK: DO THE LIBRARIES THIS PROJECT PINS HAVE KNOWN ADVISORIES?
+ * ==============================================================================
+ *
+ * Every other check reads the code a project wrote. Most of what a project
+ * runs, it did not write: it is in the lockfile. This reads the versions a
+ * lockfile pins and asks OSV (osv.dev, the open advisory database behind
+ * OSV-Scanner) which of them have published advisories.
+ *
+ * WHY IT IS A SEPARATE COMMAND. It is the one check that talks to the network.
+ * `defuse scan` promises nothing leaves the machine, and keeps that promise;
+ * `defuse deps` sends package names and versions - never code - to api.osv.dev,
+ * and says so before it does.
+ *
+ * WHAT IT CAN AND CANNOT CLAIM. A pinned version that matches an advisory says
+ * the vulnerable code is installed. It says nothing about whether this project
+ * ever calls it. Signature-grade by nature, and every result says so.
+ *
+ * Lockfiles it recognises but cannot read yet are listed by name, and lines it
+ * could not read are counted with the reason - never silently skipped.
+ */
+import { type SignatureFinding } from '../core/finding.js';
+import { DEPENDENCY_RULE, type DependencyReport } from './dependency-rule.js';
+export { DEPENDENCY_RULE, type DependencyReport };
+export type Ecosystem = 'npm' | 'PyPI' | 'Packagist' | 'Go';
+export interface Pinned {
+    readonly name: string;
+    readonly version: string;
+    readonly ecosystem: Ecosystem;
+    /** The lockfile it was read from, as found. */
+    readonly file: string;
+}
+export interface LockfileRead {
+    readonly file: string;
+    readonly packages: readonly Pinned[];
+    /** What was in the file but not checked, each with the reason. */
+    readonly skipped: readonly string[];
+}
+export interface Advisory {
+    readonly id: string;
+    readonly summary: string;
+    readonly aliases: readonly string[];
+    /** OSV's own rating where the source gives one (critical/high/medium/low), else "unrated". */
+    readonly severity: string;
+    /** Versions the advisory says fix it, for this package. Empty when none is published. */
+    readonly fixed: readonly string[];
+}
+export interface DependencyHit {
+    readonly pkg: Pinned;
+    readonly advisories: readonly Advisory[];
+}
+/** Recognised by name, not read yet. Listed in the output, never ignored in silence. */
+export declare const UNREAD_LOCKFILES: ReadonlySet<string>;
+/** Parse one lockfile by its file name. Null when the name is not one this reads. */
+export declare function readLockfile(file: string, text: string): LockfileRead | null;
+/** Every lockfile under `target`, read; plus the recognised ones that are not. `exclude` means what scan --exclude means. */
+export declare function findLockfiles(target: string, exclude?: readonly string[]): {
+    read: LockfileRead[];
+    unread: string[];
+};
+/**
+ * Ask OSV about every pinned package. Sends name, ecosystem and version only.
+ * `fetchImpl` is injectable so the tests can run without a network.
+ */
+export declare function queryOsv(pinned: readonly Pinned[], fetchImpl?: typeof fetch): Promise<{
+    hits: DependencyHit[];
+    checked: number;
+    incomplete: string[];
+}>;
+/**
+ * The whole check for `scan --deps`: find lockfiles, ask OSV, and return one
+ * signature-based finding per affected package, located on its lockfile line.
+ * `display` turns an absolute path into the one the report shows.
+ */
+export declare function checkDependencies(target: string, display: (file: string) => string, exclude?: readonly string[], fetchImpl?: typeof fetch): Promise<{
+    findings: SignatureFinding[];
+    report: DependencyReport;
+}>;
+export declare function dependencyFinding(hit: DependencyHit, lines: readonly string[], file: string): SignatureFinding;
+/**
+ * One flaw, one entry. OSV holds the same CVE once per database (GHSA-, GO-,
+ * PYSEC-...), so a project would otherwise see one bug listed two or three
+ * times. Entries naming each other, or sharing an alias, are folded into one;
+ * a rated entry wins over an unrated one, and every id is kept in `aliases`.
+ */
+export declare function mergeSame(advisories: readonly Advisory[]): Advisory[];