@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/core/finding.js

@@ -0,0 +1,178 @@
+/**
+ * THE HONESTY CONTRACT
+ * ====================
+ *
+ * This file is the most important file in the project. Everything else is
+ * plumbing. Read this one carefully.
+ *
+ * Defuse promises one thing that Snyk / Semgrep / SonarQube do not
+ * promise clearly: every single finding tells you HOW SURE we are, in a way you
+ * can act on. There are exactly two levels, and they mean precise things:
+ *
+ *   "signature-based"  We matched a SHAPE in your code. We saw a pattern that
+ *                      is *often* a vulnerability. We did NOT trace where the
+ *                      data actually came from. This might be a real bug, or it
+ *                      might be completely safe. YOU still have to look.
+ *
+ *   "flow-verified"    We traced actual data, step by step, from a place an
+ *                      attacker controls (a "source", e.g. an HTTP request)
+ *                      all the way into a dangerous operation (a "sink", e.g.
+ *                      a database query), and we confirmed nothing cleaned it
+ *                      up along the way. We can show you every hop.
+ *
+ * A RULE CAN ONLY EVER PRODUCE "signature-based". Only the taint engine can
+ * produce the other label.
+ *
+ * We do not enforce that with willpower or a code review checklist. We enforce
+ * it with the type system:
+ *
+ *   - A FlowVerifiedFinding REQUIRES a non-empty `flowPath` of concrete steps.
+ *   - Only the taint engine can build one. A rule cannot, because a rule only
+ *     ever sees a single shape - it has no idea where the value came from.
+ *   - So a rule physically cannot emit a "flow-verified" finding: there is no
+ *     path it could supply, and TypeScript refuses to compile the attempt.
+ *
+ * That is the difference between a promise and a guarantee.
+ *
+ * ARCHITECTURAL DECISION (matters later): we are modelling Finding as a
+ * "discriminated union" - two shapes sharing one `confidence` tag - rather than
+ * one flat object with an optional flag. The taint engine supplies the second
+ * shape, and every report renderer is forced by the compiler to handle it.
+ * Nothing silently upgrades its own confidence.
+ */
+import { LANGUAGES } from '../parse/languages.js';
+export const SEVERITY_ORDER = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    info: 0,
+};
+/**
+ * The constructor for everything the RULE engine produces.
+ *
+ * Note what it does not accept: there is no `confidence` parameter. A rule
+ * author cannot pass "flow-verified" even by mistake, because the value is
+ * hard-coded here and nowhere else.
+ */
+export function signatureFinding(input) {
+    return {
+        ruleId: input.ruleId,
+        ruleName: input.ruleName,
+        cwe: input.cwe,
+        owasp: input.owasp,
+        severity: input.severity,
+        message: input.message,
+        location: input.location,
+        reasoning: input.reasoning,
+        limitations: input.limitations,
+        detectedAt: input.detectedAt ?? new Date().toISOString(),
+        confidence: 'signature-based',
+        verified: false,
+        flowPath: null,
+    };
+}
+/**
+ * THE SECOND CONSTRUCTOR.
+ *
+ * For the whole first stretch of this project, this function threw. It was a
+ * deliberate, documented stub: the type for a flow-verified finding existed, so
+ * anyone could read what the claim would REQUIRE, but nothing could produce one.
+ *
+ * It is real now, and the requirement did not soften. Note the runtime checks
+ * below: a flow-verified finding must carry a path that BEGINS at a source and
+ * ENDS at a sink. Not "a path". Not "some steps". If the taint engine ever
+ * hands over a path that doesn't start where attacker data enters and finish
+ * where it does damage, this throws rather than emitting the claim.
+ *
+ * The type system stops a rule from lying. This function stops the ENGINE from
+ * lying - including a future version of it written by someone in a hurry.
+ */
+export function flowVerifiedFinding(input) {
+    const path = input.flowPath;
+    if (path.length < 2) {
+        throw new Error(`flowVerifiedFinding: a verified path needs at least a source and a sink, got ${path.length} step(s).`);
+    }
+    if (path[0]?.kind !== 'source') {
+        throw new Error(`flowVerifiedFinding: path must begin at a source, begins at '${path[0]?.kind}'.`);
+    }
+    if (path[path.length - 1]?.kind !== 'sink') {
+        throw new Error(`flowVerifiedFinding: path must end at a sink, ends at '${path[path.length - 1]?.kind}'.`);
+    }
+    // A path containing a sanitiser is, by definition, not a confirmed exploit.
+    // If the engine ever tries to report one, that is a bug in the engine and we
+    // would rather crash the scan than publish the claim.
+    const sanitised = path.find((step) => step.kind === 'sanitizer');
+    if (sanitised) {
+        throw new Error(`flowVerifiedFinding: path contains a sanitiser (${sanitised.description}) - that is a CLEAN flow, not a verified vulnerability.`);
+    }
+    return {
+        ruleId: input.ruleId,
+        ruleName: input.ruleName,
+        cwe: input.cwe,
+        owasp: input.owasp,
+        severity: input.severity,
+        message: input.message,
+        location: input.location,
+        reasoning: input.reasoning,
+        limitations: input.limitations,
+        detectedAt: input.detectedAt ?? new Date().toISOString(),
+        confidence: 'flow-verified',
+        verified: true,
+        flowPath: path,
+        unmodelledHops: input.unmodelledHops ?? [],
+    };
+}
+/** What this build of the engine can and cannot do. Printed in every report. */
+export const ENGINE_CAPABILITIES = {
+    /**
+     * What the banner prints, on the terminal and in the browser.
+     *
+     * A phase number used to live here. It described OUR build order, not
+     * anything a user of the tool can act on - and it went stale the moment work
+     * happened out of order: the banner read "PHASE 3C" while the version string
+     * read "phase2", which is precisely the kind of small lie this project exists
+     * to not tell. A capability label cannot drift, because it can only change
+     * when the engine actually changes.
+     */
+    analysisLabel: 'SIGNATURE + DATA FLOW',
+    version: '0.5.0',
+    implemented: [
+        `Tree-sitter AST parsing for ${LANGUAGES.map((l) => l.displayName).join(', ')}`,
+        'Pattern (signature) matching over real syntax trees, not text/regex',
+        `Taint analysis in all ${LANGUAGES.length} languages: source to sink, following values into other functions AND - in every language except PHP - into other files through resolved imports`,
+        'Prepared-statement awareness: arguments bound to a prepared query are parameters, not instructions',
+        'Kind-scoped sanitiser recognition - an HTML escaper does not clear a SQL sink',
+        'Retraction: a signature guess is withdrawn when the tracer proves a sanitiser runs',
+        'Verified-clean reporting: lines the tracer reached and proved safe are listed, so "no finding here" can be told apart from "never looked here"',
+        'One engine, two shells: the terminal and the browser run the same compiled analysis module, not two implementations of it',
+        'Receiver state: a tainted argument dirties the object it was handed to, so `sb.append(dirty)` and `list.add(dirty)` are followed - and a sink that takes NO arguments because the payload was loaded earlier (`pb.command(list); pb.start()`) is recognised',
+        'Return-value sinks in Python: a Flask/Django view that returns an HTML string is treated as writing the response body, so the commonest reflected XSS in Python is seen at all - and the escaped version is credited as clean rather than merely unflagged',
+        'Escape proof before complaint (JavaScript/TypeScript): before reporting a value written into HTML, local variables, local render helpers and their arguments are resolved to see whether every spliced-in value is a literal, a number, or the output of a known escaper. A finding that survives names the exact sub-expression it could not prove safe.',
+        'SQL is recognised by statement SHAPE (SELECT paired with FROM, INSERT with INTO) inside a bounded window, not by keywords scattered anywhere in the text - so a paragraph of prose containing "call" and "where" is not a query',
+        'Per-rule and per-language coverage reporting, including gaps',
+    ],
+    notImplemented: [
+        'Third-party code: only files inside the scan are resolved. A call into node_modules, a JAR or a vendored package ends the trace.',
+        'Ambiguous imports: when several files in scope define the same function name, we decline to guess and the trace stops there. The count is reported.',
+        'Re-exports, dynamic imports, computed requires, and build-tool path aliases (tsconfig paths, webpack) are not resolved.',
+        'Whether a function is actually EXPORTED is not checked - a module-private helper with a matching name could be entered.',
+        'Call chains deeper than four functions are not followed, and a call that resolves by name to a function already being followed on the same path - recursion, or a same-named method on another object - is not re-entered. At either stop the value is carried on as an ASSUMPTION that the unread call preserves it, and the finding names the call and why it was not read. So a sanitiser hidden past a stop is missed and the line is reported; before this was fixed the stop declared the value clean, which cost BenchmarkJava 38 real vulnerabilities.',
+        'Calls are resolved by NAME, with two checks where the language makes them sound: in Java, Go, C and C++ a call must pass a number of arguments the target accepts, and in Java a call on a receiver of a declared type only reaches methods declared in that type. An interface-typed receiver therefore reaches no body at all, and the value is carried past it as a named assumption.',
+        'Object and field state: `obj.field = dirty` and `sb.append(dirty)` are invisible - we track variables, not the interiors of objects.',
+        'Sources are recognised by expression shape (req.query, request.form), not by proving the object really is a request.',
+        'Branch conditions are evaluated only when they are fixed at compile time: literals, arithmetic, comparisons and logic over them, a local DECLARED once with such a value (in Python, PHP and a JavaScript `var`: written once at the top of the function, since those have no block-scoped declarations), a character literal, and Java\'s `charAt` on a string literal. A name that is a parameter, a field, incremented, passed by address or reference, part of a destructuring or multi-value write, or written more than once is not fixed; nor is anything in C++ unless it is declared const or constexpr, since a reference can write to it invisibly; nor anything in a function that uses eval, with, arguments, $$name, extract() or exec(), that C code can goto into, or that did not parse cleanly. Only exact arithmetic is folded: no octal literals, no division outside integer languages, and no value outside the range its declared type holds. Such a condition decides `if`, ternaries and switch statements (Java, JavaScript, TypeScript, C, C++, PHP and Go - not Python\'s `match`); strings are never compared, so a switch on a string stays undecided. Every branch or case skipped this way is listed in diagnostics.unreachableCodeSkipped with the decision behind it. Every other condition is not read, so we make the weaker claim that a CONDITIONAL write cannot prove a value clean: taint set anywhere survives a clean assignment inside an if/else, switch or loop, while an unconditional one still clears it. That errs toward reporting a value that might be clean rather than staying silent about one that might be dirty - and it is why `if (cond) bar = dirty; else bar = "safe";` is still reported.',
+        'Loops are not iterated to a fixpoint, so a value that becomes tainted late in a loop body is missed.',
+        'Containers are tainted whole, not per element: after `list.add(clean)` and `list.add(dirty)`, or after `Object[] a = {"safe", dirty}`, every read from that container is treated as dirty. This is the price of following values into objects at all, and it errs toward reporting rather than missing. TWO EXCEPTIONS, Java only, where every write the collection can receive is visible: a map created locally as `new HashMap<>()` or `new LinkedHashMap<>()` and touched by nothing but straight-line `put("literal", value);` statements and reads answers `get("literal")` with the last put under that key; and a list created locally as `new ArrayList<>()` or `new LinkedList<>()` and touched by nothing but straight-line `add(value);` and `remove(n);` statements and reads is replayed, so `get(n)` returns what sits at that position. Anything else - a conditional write, a variable key or index, the collection handed to anything, any other method - keeps the whole-collection answer. A stored value that can change in place (a StringBuilder, an array, a list) is not read this way, since an alias could change it unseen. Every read answered this way is listed in diagnostics.collectionReadsResolved.',
+        'Framework awareness is PER-FRAMEWORK and partial. Recognised: Express/Koa request objects, Flask/Django/DRF request objects, URL path parameters named by a Flask or FastAPI route decorator, NestJS @Param/@Query/@Body/@Headers parameters, Spring and JAX-RS parameter annotations, servlet getters, net/http and Gin/Echo context values, PHP superglobals and $request accessors. NOT recognised, and each one is a silent zero: any house-built REST layer (elasticsearch\'s own RestRequest is 783 uses in one repository), Micronaut, Quarkus outside JAX-RS, Vert.x, Play, NestJS decorators other than @Param, @Query, @Body and @Headers, FastAPI query parameters a route path does not name and Pydantic body models, and Express ROUTING itself - a value that only becomes attacker-controlled through a framework binding we do not list is never seen as a source. The report now prints how many sources were recognised, so a zero is visible rather than reading as a clean bill.',
+        'The escape proof is JavaScript and TypeScript only, and same-file only. An escaper imported from another module, applied by a framework, or reached through more than six nested calls reads as unproven - so Python, Java, PHP and Go HTML sinks still report on shape alone.',
+        'MEMORY SCALES WITH THE SOURCE, at roughly 7x its bytes plus a fixed ~300MB for Node and the seven WebAssembly grammars. Syntax trees live in a WASM heap that JavaScript garbage collection cannot touch, so they are freed explicitly: the scan holds as many as DEFUSE_TREE_BUDGET_MB allows and parses a file again if something needs it after its tree was dropped. Measured on one 54MB corpus, same binary, only the budget changed: 1474MB peak holding everything, 716MB with a 256MB tree budget, findings byte-identical, 7% slower. That puts the practical ceiling near 1.1GB of source on an 8GB machine. A scan that does not fit gets SLOWER rather than being killed, and the report says so - diagnostics.treeMemory.reparses above zero means files were parsed more than once. THE PREVIOUS VERSION OF THIS NOTE WAS WRONG, and is recorded here rather than quietly deleted: it said trees were never freed "because cross-file tracing needs to resolve into any file at any time", and cited a 120MB ceiling. Cross-file had nothing to do with it - measured, --no-cross-file used 535.8MB against 528.8MB with it on, because nothing called delete() in either mode. The ceiling was real; the explanation for it was invented.',
+        'Expressions nested deeper than 400 levels are not walked. Hand-written code never reaches this; generated, minified and stress-test files do. The count is reported as a blind spot rather than silently skipped - an earlier version had no limit at all and one such file killed an entire 25,809-file scan with a stack overflow, losing every finding in it.',
+        'Vendor documentation example credentials (a key matching a published format but ending in EXAMPLE, or filled with 0000/1234567890) are treated as placeholders and not reported. A real credential that happened to look like one would be missed.',
+    ],
+    meaningOfConfidence: {
+        'signature-based': 'Pattern matched in the syntax tree. Data flow NOT traced. May be a false positive.',
+        'flow-verified': 'Attacker-controlled data was traced from a source into a sink - across functions and, where imports resolve, across files - with no sanitiser on the path. Every hop is listed in flowPath, with its own file and line.',
+    },
+};
+//# sourceMappingURL=finding.js.map

package/dist/src/core/finding.js.map

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

package/dist/src/core/licence.d.ts

@@ -0,0 +1,50 @@
+/**
+ * THE LICENCE, IN ONE PLACE
+ * =========================
+ *
+ * WHY A MODULE AND NOT A STRING IN THREE FILES.
+ *
+ * This project has been bitten four times by the same shape of bug: a fact
+ * written down in prose next to the same fact held in data, and the two
+ * drifting apart. The README claimed 112 checks while 207 ran. It claimed
+ * 13.8% recall for roughly twenty versions after that stopped being true. The
+ * engine's own limitation text explained the memory ceiling with a cause that
+ * a two-line experiment disproved.
+ *
+ * A licence is a worse place for that to happen than a count is. "This is
+ * AGPL-3.0" printed in a terminal, "UNLICENSED" in package.json and an MIT file
+ * on disk is not a cosmetic inconsistency - it is three different legal claims
+ * about the same program, and the person who gets hurt is whoever believed one
+ * of them. So the licence is declared once here, and a test fails if the
+ * LICENSE file or package.json disagrees.
+ *
+ * WHY AGPL-3.0 SPECIFICALLY.
+ *
+ * The tool can be run as a network service - `npm run ui` serves the browser
+ * shell, and the same compiled engine runs inside it. Under a permissive
+ * licence somebody could host exactly that, modify it, and never publish a
+ * line. Section 13 of the AGPL is the clause that closes it: anyone who runs a
+ * MODIFIED version and lets other people interact with it over a network must
+ * offer those users the corresponding source.
+ *
+ * Note what that does NOT say. Using this tool on your own private code puts no
+ * obligation on you whatsoever, and neither does running it unmodified inside
+ * your company. The obligation attaches to distributing or network-serving a
+ * CHANGED version. Scanning a closed-source repository with it is exactly the
+ * intended use and carries no licence consequence for the code being scanned.
+ */
+/** SPDX identifier. Must match package.json's `license` field exactly. */
+export declare const LICENCE_SPDX = "AGPL-3.0-only";
+/** The first line of the LICENSE file, checked against it by the test suite. */
+export declare const LICENCE_FILE_HEADING = "GNU AFFERO GENERAL PUBLIC LICENSE";
+/** One line, for the bottom of `--help`. */
+export declare const LICENCE_LINE: string;
+/**
+ * The section 13 notice, for the browser UI.
+ *
+ * The UI is the reason the licence is AGPL rather than GPL, so this is the one
+ * place the notice is not merely good manners. It is shown rather than buried
+ * in a file nobody opens, because section 13 says "prominently offer" and a
+ * link in a LICENSE file the user never sees is not an offer.
+ */
+export declare const NETWORK_SOURCE_NOTICE: string;

package/dist/src/core/licence.js

@@ -0,0 +1,56 @@
+/**
+ * THE LICENCE, IN ONE PLACE
+ * =========================
+ *
+ * WHY A MODULE AND NOT A STRING IN THREE FILES.
+ *
+ * This project has been bitten four times by the same shape of bug: a fact
+ * written down in prose next to the same fact held in data, and the two
+ * drifting apart. The README claimed 112 checks while 207 ran. It claimed
+ * 13.8% recall for roughly twenty versions after that stopped being true. The
+ * engine's own limitation text explained the memory ceiling with a cause that
+ * a two-line experiment disproved.
+ *
+ * A licence is a worse place for that to happen than a count is. "This is
+ * AGPL-3.0" printed in a terminal, "UNLICENSED" in package.json and an MIT file
+ * on disk is not a cosmetic inconsistency - it is three different legal claims
+ * about the same program, and the person who gets hurt is whoever believed one
+ * of them. So the licence is declared once here, and a test fails if the
+ * LICENSE file or package.json disagrees.
+ *
+ * WHY AGPL-3.0 SPECIFICALLY.
+ *
+ * The tool can be run as a network service - `npm run ui` serves the browser
+ * shell, and the same compiled engine runs inside it. Under a permissive
+ * licence somebody could host exactly that, modify it, and never publish a
+ * line. Section 13 of the AGPL is the clause that closes it: anyone who runs a
+ * MODIFIED version and lets other people interact with it over a network must
+ * offer those users the corresponding source.
+ *
+ * Note what that does NOT say. Using this tool on your own private code puts no
+ * obligation on you whatsoever, and neither does running it unmodified inside
+ * your company. The obligation attaches to distributing or network-serving a
+ * CHANGED version. Scanning a closed-source repository with it is exactly the
+ * intended use and carries no licence consequence for the code being scanned.
+ */
+/** SPDX identifier. Must match package.json's `license` field exactly. */
+export const LICENCE_SPDX = 'AGPL-3.0-only';
+/** The first line of the LICENSE file, checked against it by the test suite. */
+export const LICENCE_FILE_HEADING = 'GNU AFFERO GENERAL PUBLIC LICENSE';
+/** One line, for the bottom of `--help`. */
+export const LICENCE_LINE = `${LICENCE_SPDX} - free to use, including on closed-source code. ` +
+    'If you MODIFY it and let others use it over a network, section 13 says you ' +
+    'must offer them the source. See LICENSE.';
+/**
+ * The section 13 notice, for the browser UI.
+ *
+ * The UI is the reason the licence is AGPL rather than GPL, so this is the one
+ * place the notice is not merely good manners. It is shown rather than buried
+ * in a file nobody opens, because section 13 says "prominently offer" and a
+ * link in a LICENSE file the user never sees is not an offer.
+ */
+export const NETWORK_SOURCE_NOTICE = `Defuse is ${LICENCE_SPDX}. This page runs the same analysis engine as the ` +
+    'command line, entirely in your browser - nothing you load here is uploaded ' +
+    'anywhere. If you are running a MODIFIED copy of this tool as a service for ' +
+    'other people, the licence requires you to offer them its source.';
+//# sourceMappingURL=licence.js.map

package/dist/src/core/licence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"licence.js","sourceRoot":"","sources":["../../../src/core/licence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,eAAe,CAAC;AAE5C,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,mCAAmC,CAAC;AAExE,4CAA4C;AAC5C,MAAM,CAAC,MAAM,YAAY,GACvB,GAAG,YAAY,mDAAmD;IAClE,6EAA6E;IAC7E,0CAA0C,CAAC;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,aAAa,YAAY,mDAAmD;IAC5E,6EAA6E;IAC7E,6EAA6E;IAC7E,kEAAkE,CAAC"}

package/dist/src/core/paths.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PATH HELPERS WITH NO PLATFORM ATTACHED
+ *
+ * `node:path` was the last thing standing between the analysis code and a
+ * browser. The import graph needs to join and normalise paths, and Node's
+ * version of that pulls in a runtime the browser does not have.
+ *
+ * These are the four operations the resolver actually uses, written in plain
+ * JavaScript over forward slashes. Windows paths are normalised on the way in,
+ * so `C:\\src\\db.ts` and `C:/src/db.ts` compare equal - which matters, because
+ * a path that fails to match is an import edge silently not resolved.
+ */
+/** Backslashes to forward slashes. Everything else here assumes this ran. */
+export declare function toPosix(filePath: string): string;
+/** Collapse `.` and `..` segments. Keeps a leading `/` or a `C:` drive. */
+export declare function normalizePath(filePath: string): string;
+export declare function dirnameOf(filePath: string): string;
+export declare function basenameOf(filePath: string): string;
+export declare function joinPath(...parts: readonly string[]): string;
+/** Resolve a relative specifier against a directory. */
+export declare function resolveFrom(directory: string, relative: string): string;

package/dist/src/core/paths.js

@@ -0,0 +1,58 @@
+/**
+ * PATH HELPERS WITH NO PLATFORM ATTACHED
+ *
+ * `node:path` was the last thing standing between the analysis code and a
+ * browser. The import graph needs to join and normalise paths, and Node's
+ * version of that pulls in a runtime the browser does not have.
+ *
+ * These are the four operations the resolver actually uses, written in plain
+ * JavaScript over forward slashes. Windows paths are normalised on the way in,
+ * so `C:\\src\\db.ts` and `C:/src/db.ts` compare equal - which matters, because
+ * a path that fails to match is an import edge silently not resolved.
+ */
+/** Backslashes to forward slashes. Everything else here assumes this ran. */
+export function toPosix(filePath) {
+    return filePath.replace(/\\/g, '/');
+}
+/** Collapse `.` and `..` segments. Keeps a leading `/` or a `C:` drive. */
+export function normalizePath(filePath) {
+    const posix = toPosix(filePath);
+    const absolute = posix.startsWith('/');
+    const parts = [];
+    for (const segment of posix.split('/')) {
+        if (!segment || segment === '.')
+            continue;
+        if (segment === '..') {
+            const last = parts[parts.length - 1];
+            if (parts.length > 0 && last !== '..')
+                parts.pop();
+            else if (!absolute)
+                parts.push('..');
+            continue;
+        }
+        parts.push(segment);
+    }
+    return (absolute ? '/' : '') + parts.join('/');
+}
+export function dirnameOf(filePath) {
+    const posix = toPosix(filePath);
+    const cut = posix.lastIndexOf('/');
+    if (cut < 0)
+        return '';
+    return cut === 0 ? '/' : posix.slice(0, cut);
+}
+export function basenameOf(filePath) {
+    const posix = toPosix(filePath);
+    return posix.slice(posix.lastIndexOf('/') + 1);
+}
+export function joinPath(...parts) {
+    return normalizePath(parts.filter(Boolean).join('/'));
+}
+/** Resolve a relative specifier against a directory. */
+export function resolveFrom(directory, relative) {
+    const posix = toPosix(relative);
+    if (posix.startsWith('/'))
+        return normalizePath(posix);
+    return normalizePath(`${toPosix(directory)}/${posix}`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/core/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/core/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,6EAA6E;AAC7E,MAAM,UAAU,OAAO,CAAC,QAAgB;IACtC,OAAO,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACtC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACvC,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,GAAG;YAAE,SAAS;QAC1C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACrC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,IAAI;gBAAE,KAAK,CAAC,GAAG,EAAE,CAAC;iBAC9C,IAAI,CAAC,QAAQ;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrC,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB;IACxC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAG,KAAwB;IAClD,OAAO,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,WAAW,CAAC,SAAiB,EAAE,QAAgB;IAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IACvD,OAAO,aAAa,CAAC,GAAG,OAAO,CAAC,SAAS,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC;AACzD,CAAC"}

package/dist/src/core/score.d.ts

@@ -0,0 +1,137 @@
+/**
+ * THE GAUGES
+ * ==========
+ *
+ * Three needles. They are never added together, and this file will not let
+ * them be - there is no `overallScore` export, and there never should be.
+ *
+ * WHY THAT MATTERS. The comment at the top of finding.ts says it best:
+ *
+ *   "Severity = how bad is this if it turns out to be real? Deliberately
+ *    separate from confidence, which is how sure are we it's real?
+ *    Conflating those two numbers is the single most common lie in SAST
+ *    tooling: a tool shows one 'risk' bar and you cannot tell whether it
+ *    means 'probably harmless but catastrophic if not' or 'definitely real
+ *    but minor'."
+ *
+ * A single 0-500 risk dial IS that bar. So the dial got split along the exact
+ * line the project already draws:
+ *
+ *   VERIFIED EXPOSURE    severity, over findings we PROVED reach a sink
+ *   UNVERIFIED SURFACE   severity, over findings we only pattern-matched
+ *   ANALYSIS COVERAGE    how much of the code we could actually reason about
+ *
+ * Two of those are the same weights over two different confidence levels, kept
+ * side by side so you can see the shape of what is proven against the shape of
+ * what is merely suspected. Reading them together is the point; averaging them
+ * would destroy it.
+ *
+ * Every reading carries its own arithmetic in `working`, so the number can be
+ * CHECKED rather than believed. That is the whole standard here: a score you
+ * cannot recompute by hand is a vibe with a decimal point on it.
+ */
+import type { Severity } from './finding.js';
+import type { AnalysisResult } from './analyze.js';
+/**
+ * How much one finding contributes, by severity.
+ *
+ * These are a judgement, not a measurement, and calling them anything else
+ * would be the first lie. What makes them defensible is that they are FIXED,
+ * PUBLISHED and applied identically to both severity gauges - so while the
+ * absolute number is arbitrary, every comparison made with it is real: two
+ * criticals always outweigh three mediums, in both directions, in both shells.
+ */
+export declare const SEVERITY_WEIGHT: Readonly<Record<Severity, number>>;
+/** The top of the severity dials. A sum past this is reported, not hidden. */
+export declare const GAUGE_MAX = 500;
+export interface GaugeReading {
+    readonly id: 'verified-exposure' | 'unverified-surface' | 'analysis-coverage';
+    readonly label: string;
+    /** Where the needle sits. Already clamped to [0, max]. */
+    readonly value: number;
+    readonly max: number;
+    readonly unit: '' | '%';
+    /** One line under the needle: what it means, and what it does NOT mean. */
+    readonly meaning: string;
+    /** The arithmetic. Anyone can recompute the value from these lines. */
+    readonly working: readonly string[];
+    /**
+     * The raw total before clamping. Equal to `value` unless the scan blew past
+     * the top of the dial, in which case the dial is pinned and this is the
+     * truth. A pinned needle that quietly stops counting is a lie by omission.
+     */
+    readonly rawTotal: number;
+    readonly capped: boolean;
+    /**
+     * True when there was nothing to measure, as distinct from measuring zero.
+     *
+     * These are not the same fact and must never be drawn the same way. A scan of
+     * an empty file and a scan of ten lines of careful, correctly parameterised
+     * code both produced "0 findings, 94% coverage, no blind spots" - identical
+     * dashboards for "we checked and found nothing" and "there was nothing to
+     * check". The second is a result; the first is the absence of one.
+     */
+    readonly noReading: boolean;
+    /**
+     * What the total is MADE OF, largest severity first.
+     *
+     * A single needle throws this away, and on real code it throws away almost
+     * everything: across the corpus the severity dials sit between 0% and 24% of
+     * their scale, so the arc is a stub and the stub is all you get. "75" cannot
+     * tell you whether that is three criticals or twenty-five lows, and those are
+     * different afternoons.
+     *
+     * Empty for the coverage gauge, which is a ratio and has no composition.
+     */
+    readonly segments: readonly {
+        readonly severity: Severity;
+        readonly count: number;
+        readonly weight: number;
+        /** Share of this gauge's own total, 0-1. Zero when the total is zero. */
+        readonly share: number;
+    }[];
+}
+export interface ScoreReport {
+    readonly gauges: readonly GaugeReading[];
+    /**
+     * Nothing in this scan could be analysed - no statement, call or assignment
+     * ever reached a rule. Every reading below is vacuous when this is true, and
+     * any surface showing them has to say so rather than printing zeroes.
+     */
+    readonly examinedNothing: boolean;
+    /** Code constructs the rules actually looked at. The denominator of trust. */
+    readonly shapesExamined: number;
+    /**
+     * Places this scan is known to have stopped early. Not a gauge, because a
+     * count of blind spots is not a measurement of risk - but printed beside the
+     * gauges, because it is what tells you how much of the dial to trust.
+     */
+    readonly blindSpots: readonly {
+        readonly label: string;
+        readonly count: number;
+    }[];
+    /**
+     * How many attacker-controlled SOURCES the tracer recognised in this scan.
+     *
+     * Reported ALWAYS, including - especially - when it is zero, which is why it
+     * cannot live in blindSpots above: that list drops anything with a count of
+     * zero, and zero is the interesting reading here.
+     *
+     * Elasticsearch is why. 3,999 Java files, a REST API over the network, and
+     * zero flow-verified findings. It contains 0 `@RequestParam` and 0
+     * `getParameter()` - it has its own REST layer, which the dictionaries do not
+     * model, so there was never a source to start a trace from. "0 flows proven"
+     * read like good news and was actually "we could not begin".
+     *
+     * Every flow number in a report is downstream of this one.
+     */
+    readonly sourcesFound: number;
+}
+/**
+ * Build all three readings.
+ *
+ * `filesFound` comes from the walker (Node) or the drop handler (browser), so
+ * it is passed in rather than read off the result - the analyzer only ever
+ * sees the files that made it that far.
+ */
+export declare function scoreAnalysis(result: AnalysisResult, filesFound?: number): ScoreReport;