@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/parse/parser.d.ts

@@ -0,0 +1,126 @@
+/**
+ * WHAT IS AN AST? (read this once, then the rest of the project makes sense)
+ * =========================================================================
+ *
+ * When you write:
+ *
+ *     const total = price + tax;
+ *
+ * your computer does not see a sentence. It sees a TREE. "AST" stands for
+ * Abstract Syntax Tree: "abstract" because it throws away things that don't
+ * change meaning (spaces, most punctuation), "syntax" because it captures the
+ * grammar of the language, and "tree" because code nests inside code.
+ *
+ * That line becomes something like:
+ *
+ *     lexical_declaration
+ *      +- variable_declarator
+ *          +- name: identifier          "total"
+ *          +- value: binary_expression
+ *              +- left:     identifier  "price"
+ *              +- operator: "+"
+ *              +- right:    identifier  "tax"
+ *
+ * Why this matters enormously for a security scanner:
+ *
+ * The old way (what most cheap scanners do, and what earlier versions of this
+ * project did) is to search the raw TEXT with regular expressions. Text search
+ * cannot tell the difference between:
+ *
+ *     db.query("SELECT * FROM users WHERE id = " + userId)   <- real problem
+ *     // db.query("SELECT * FROM users WHERE id = " + userId)  <- a comment
+ *     log("db.query is unsafe when you do \" + userId\"")      <- a string
+ *
+ * All three contain the same characters. Only one is a vulnerability. An AST
+ * knows which is which, because the parser already decided "this is a comment",
+ * "this is a string literal", "this is a real function call". We get that
+ * accuracy for free, and it is the entire reason we use tree-sitter.
+ *
+ * Tree-sitter is Github's parser toolkit. It is fast, it is error-tolerant
+ * (it produces a usable tree even for code that doesn't compile - important,
+ * because real repositories contain broken files), and it has mature grammars
+ * for dozens of languages that all behave the same way.
+ */
+import { Language, type Node, type Tree } from 'web-tree-sitter';
+import { type LanguageSpec } from './languages.js';
+/**
+ * WHERE DO THE .wasm GRAMMARS COME FROM?
+ *
+ * On Node they are files in node_modules. In a browser they are URLs fetched
+ * over HTTP. That is the ONLY difference between the two platforms in the whole
+ * analysis path, so it is the only thing abstracted: everything else - parsing,
+ * rules, taint - is identical code running in both places.
+ *
+ * A loader returns whatever `Language.load` accepts: a path, a URL, or bytes.
+ */
+export type GrammarLoader = (grammar: string) => string | Uint8Array | Promise<string | Uint8Array>;
+/** Called once by whichever shell is in charge (CLI or browser worker). */
+export declare function configureParsing(options: {
+    loadGrammar: GrammarLoader;
+    init?: () => Promise<void>;
+}): void;
+/**
+ * Boot the WebAssembly runtime. Must happen once before any parsing.
+ * We memoise the promise so calling this from ten places still only boots once.
+ */
+export declare function initEngine(): Promise<void>;
+export declare function getLanguage(grammar: string): Promise<Language>;
+/** A place where tree-sitter could not make sense of the source. */
+export interface ParseIssue {
+    readonly kind: 'ERROR' | 'MISSING';
+    readonly line: number;
+    readonly column: number;
+    readonly text: string;
+}
+/** Everything downstream code needs about one parsed file. */
+export interface ParsedFile {
+    readonly path: string;
+    readonly language: LanguageSpec;
+    /** May differ from language.grammar for dialects (.tsx uses the tsx grammar). */
+    readonly grammar: string;
+    readonly detectedBy: 'extension' | 'shebang';
+    readonly source: string;
+    readonly tree: Tree;
+    readonly root: Node;
+    /**
+     * Parse problems, reported not hidden. A file with issues is still scanned -
+     * tree-sitter recovers - but the report says so, because findings from a
+     * partially-understood file deserve less trust.
+     */
+    readonly parseIssues: readonly ParseIssue[];
+}
+export type ParseOutcome = {
+    readonly status: 'parsed';
+    readonly file: ParsedFile;
+} | {
+    readonly status: 'skipped';
+    readonly path: string;
+    readonly reason: string;
+};
+/** Parse a string of code you already have in memory. Used by tests and by `ast`. */
+export declare function parseSource(source: string, grammar: string): Promise<Tree>;
+/**
+ * Parse WITHOUT awaiting, for a grammar that has already been loaded.
+ *
+ * WHY THIS EXISTS. A syntax tree lives in WebAssembly memory, which the
+ * JavaScript garbage collector cannot see into and will never reclaim; the only
+ * way to free one is to call tree.delete() by hand. Holding every tree in a
+ * repository at once therefore costs about sixty times the source - measured,
+ * not guessed - and that is the ceiling a large scan dies against.
+ *
+ * The fix is to free trees and parse a file again if something needs it later.
+ * "Later" is inside the tracer, which is synchronous all the way down, so the
+ * re-parse has to be synchronous too.
+ *
+ * It is safe to demand that here because loading is what is actually async, and
+ * by the time anything re-parses, every grammar in the scan has already been
+ * loaded during the first pass. If that assumption ever breaks, this throws
+ * rather than silently returning nothing - a missing tree would look exactly
+ * like a file with no vulnerabilities in it.
+ */
+export declare function parseSourceSync(source: string, grammar: string): Tree;
+/**
+ * Work out a file's language and parse it, from text already in memory.
+ * No filesystem, no platform assumptions - this is what the browser calls too.
+ */
+export declare function parseSourceFile(filePath: string, source: string): Promise<ParseOutcome>;

package/dist/src/parse/parser.js

@@ -0,0 +1,202 @@
+/**
+ * WHAT IS AN AST? (read this once, then the rest of the project makes sense)
+ * =========================================================================
+ *
+ * When you write:
+ *
+ *     const total = price + tax;
+ *
+ * your computer does not see a sentence. It sees a TREE. "AST" stands for
+ * Abstract Syntax Tree: "abstract" because it throws away things that don't
+ * change meaning (spaces, most punctuation), "syntax" because it captures the
+ * grammar of the language, and "tree" because code nests inside code.
+ *
+ * That line becomes something like:
+ *
+ *     lexical_declaration
+ *      +- variable_declarator
+ *          +- name: identifier          "total"
+ *          +- value: binary_expression
+ *              +- left:     identifier  "price"
+ *              +- operator: "+"
+ *              +- right:    identifier  "tax"
+ *
+ * Why this matters enormously for a security scanner:
+ *
+ * The old way (what most cheap scanners do, and what earlier versions of this
+ * project did) is to search the raw TEXT with regular expressions. Text search
+ * cannot tell the difference between:
+ *
+ *     db.query("SELECT * FROM users WHERE id = " + userId)   <- real problem
+ *     // db.query("SELECT * FROM users WHERE id = " + userId)  <- a comment
+ *     log("db.query is unsafe when you do \" + userId\"")      <- a string
+ *
+ * All three contain the same characters. Only one is a vulnerability. An AST
+ * knows which is which, because the parser already decided "this is a comment",
+ * "this is a string literal", "this is a real function call". We get that
+ * accuracy for free, and it is the entire reason we use tree-sitter.
+ *
+ * Tree-sitter is Github's parser toolkit. It is fast, it is error-tolerant
+ * (it produces a usable tree even for code that doesn't compile - important,
+ * because real repositories contain broken files), and it has mature grammars
+ * for dozens of languages that all behave the same way.
+ */
+import { Language, Parser } from 'web-tree-sitter';
+import { detectLanguage } from './languages.js';
+let grammarLoader = null;
+let engineInit = null;
+/** Called once by whichever shell is in charge (CLI or browser worker). */
+export function configureParsing(options) {
+    grammarLoader = options.loadGrammar;
+    engineInit = options.init ?? null;
+    engineReady = null;
+    parserCache.clear();
+    languageCache.clear();
+}
+let engineReady = null;
+/**
+ * Boot the WebAssembly runtime. Must happen once before any parsing.
+ * We memoise the promise so calling this from ten places still only boots once.
+ */
+export async function initEngine() {
+    engineReady ??= engineInit ? engineInit() : Parser.init();
+    await engineReady;
+}
+/** Grammar name -> loaded Parser. Loading a grammar costs ~10-40ms, so we cache. */
+const parserCache = new Map();
+async function getParser(grammar) {
+    const cached = parserCache.get(grammar);
+    if (cached)
+        return cached;
+    await initEngine();
+    if (!grammarLoader) {
+        throw new Error('No grammar loader configured. Call configureParsing() first - ' +
+            'src/parse/node-grammars.ts for the CLI, ui/worker.js for the browser.');
+    }
+    const language = await Language.load(await grammarLoader(grammar));
+    const parser = new Parser();
+    parser.setLanguage(language);
+    parserCache.set(grammar, parser);
+    return parser;
+}
+/** The tree-sitter Language object, needed to compile queries. */
+const languageCache = new Map();
+export async function getLanguage(grammar) {
+    const cached = languageCache.get(grammar);
+    if (cached)
+        return cached;
+    const parser = await getParser(grammar);
+    const language = parser.language;
+    if (!language)
+        throw new Error(`Grammar ${grammar} loaded but exposed no language`);
+    languageCache.set(grammar, language);
+    return language;
+}
+const MAX_REPORTED_ISSUES = 25;
+/**
+ * Walk the whole tree looking for the two ways tree-sitter admits defeat:
+ *   ERROR   - "I found characters here I cannot fit into the grammar"
+ *   MISSING - "the grammar says something must be here; I inserted a fake one"
+ *
+ * We use an explicit stack rather than recursion because deeply nested files
+ * (minified code, generated code) can blow the JavaScript call stack.
+ */
+function collectParseIssues(root) {
+    if (!root.hasError)
+        return [];
+    const issues = [];
+    const stack = [root];
+    while (stack.length > 0 && issues.length < MAX_REPORTED_ISSUES) {
+        const node = stack.pop();
+        if (!node)
+            break;
+        if (node.type === 'ERROR' || node.isMissing) {
+            issues.push({
+                kind: node.isMissing ? 'MISSING' : 'ERROR',
+                line: node.startPosition.row + 1,
+                column: node.startPosition.column + 1,
+                text: (node.text ?? '').replace(/\s+/g, ' ').trim().slice(0, 60),
+            });
+            // Don't descend into an error subtree; its children are noise.
+            continue;
+        }
+        // Only descend where an error actually lives - a huge speed win.
+        if (node.hasError) {
+            for (let i = node.childCount - 1; i >= 0; i--) {
+                const child = node.child(i);
+                if (child)
+                    stack.push(child);
+            }
+        }
+    }
+    return issues;
+}
+/** Parse a string of code you already have in memory. Used by tests and by `ast`. */
+export async function parseSource(source, grammar) {
+    const parser = await getParser(grammar);
+    const tree = parser.parse(source);
+    if (!tree)
+        throw new Error(`Parser returned no tree for grammar ${grammar}`);
+    return tree;
+}
+/**
+ * Parse WITHOUT awaiting, for a grammar that has already been loaded.
+ *
+ * WHY THIS EXISTS. A syntax tree lives in WebAssembly memory, which the
+ * JavaScript garbage collector cannot see into and will never reclaim; the only
+ * way to free one is to call tree.delete() by hand. Holding every tree in a
+ * repository at once therefore costs about sixty times the source - measured,
+ * not guessed - and that is the ceiling a large scan dies against.
+ *
+ * The fix is to free trees and parse a file again if something needs it later.
+ * "Later" is inside the tracer, which is synchronous all the way down, so the
+ * re-parse has to be synchronous too.
+ *
+ * It is safe to demand that here because loading is what is actually async, and
+ * by the time anything re-parses, every grammar in the scan has already been
+ * loaded during the first pass. If that assumption ever breaks, this throws
+ * rather than silently returning nothing - a missing tree would look exactly
+ * like a file with no vulnerabilities in it.
+ */
+export function parseSourceSync(source, grammar) {
+    const parser = parserCache.get(grammar);
+    if (!parser) {
+        throw new Error(`Grammar ${grammar} is not loaded, so it cannot be parsed synchronously. ` +
+            'Every grammar must be loaded by the first (async) pass before anything re-parses.');
+    }
+    const tree = parser.parse(source);
+    if (!tree)
+        throw new Error(`Parser returned no tree for grammar ${grammar}`);
+    return tree;
+}
+/**
+ * Work out a file's language and parse it, from text already in memory.
+ * No filesystem, no platform assumptions - this is what the browser calls too.
+ */
+export async function parseSourceFile(filePath, source) {
+    // A binary file that happens to end in .js would waste a parse and produce
+    // garbage findings. NUL bytes are the cheap, reliable binary tell.
+    if (source.includes('\u0000')) {
+        return { status: 'skipped', path: filePath, reason: 'binary file' };
+    }
+    const firstLine = source.slice(0, source.indexOf('\n') + 1 || 200);
+    const match = detectLanguage(filePath, firstLine);
+    if (!match) {
+        return { status: 'skipped', path: filePath, reason: 'unsupported file type' };
+    }
+    const tree = await parseSource(source, match.grammar);
+    return {
+        status: 'parsed',
+        file: {
+            path: filePath,
+            language: match.spec,
+            grammar: match.grammar,
+            detectedBy: match.detectedBy,
+            source,
+            tree,
+            root: tree.rootNode,
+            parseIssues: collectParseIssues(tree.rootNode),
+        },
+    };
+}
+//# sourceMappingURL=parser.js.map

package/dist/src/parse/parser.js.map

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

package/dist/src/parse/tree-store.d.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 type { Node, Tree } from 'web-tree-sitter';
+/**
+ * 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 declare 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 declare const DEFAULT_TREE_BUDGET_BYTES: number;
+export interface TreeStoreStats {
+    readonly budgetBytes: number;
+    /** Files whose tree is resident right now. */
+    readonly filesResident: number;
+    /** The most tree memory this scan ever estimated it was holding. */
+    readonly peakEstimatedBytes: number;
+    /** Parses performed in total, including the first one of each file. */
+    readonly parses: number;
+    /** Parses that happened only because an earlier tree had been evicted. */
+    readonly reparses: number;
+    readonly evictions: number;
+    /**
+     * True when the budget was exceeded and something had to be evicted - i.e.
+     * the project did not fit. Reported, because it is the difference between
+     * "this scan was slow" and "this scan was slow FOR A REASON".
+     */
+    readonly spilled: boolean;
+    /**
+     * Times the budget was blown because every resident tree was pinned. Not an
+     * error, but the one way this design can still use unbounded memory, so it is
+     * counted rather than assumed away.
+     */
+    readonly overBudgetWhileAllPinned: number;
+}
+export interface TreeStore {
+    /** Declare a file and hand over the tree the first pass already produced. */
+    admit(path: string, source: string, grammar: string, tree: Tree): void;
+    /** The tree for a known file, parsing it again if it was evicted. */
+    get(path: string): Tree;
+    /** Hold this file's tree until releaseAll(). Nested pins are counted. */
+    pin(path: string): void;
+    /** Drop every pin. Call only where no Node from any file is still held. */
+    releaseAll(): void;
+    /** Free everything. The store is unusable afterwards. */
+    disposeAll(): void;
+    stats(): TreeStoreStats;
+}
+/**
+ * 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 declare function nodeAtRange(root: Node, startIndex: number, endIndex: number, type: string): Node | null;
+export declare function createTreeStore(budgetBytes?: number): TreeStore;