@sikkuumiii/defuse 0.0.0-stage → 0.5.0

package/dist/src/engine/scan.d.ts

@@ -0,0 +1,80 @@
+/**
+ * THE NODE SHELL
+ * ==============
+ *
+ * Everything that only makes sense on a machine with a filesystem: walking a
+ * directory, honouring --exclude, reading bytes, and shortening paths against
+ * the working directory so terminal output stays readable.
+ *
+ * The analysis itself is NOT here. It moved to src/core/analyze.ts when the
+ * browser UI arrived, so the web version could run the same code rather than a
+ * lookalike. What is left is the pipeline seam:
+ *
+ *   collectFiles  ->  read text  ->  analyze()  ->  a ScanResult
+ *
+ * If you find yourself wanting to change how a FINDING is produced, this is the
+ * wrong file - that belongs in core/analyze.ts, where the browser sees it too.
+ */
+import { type AnalysisResult } from '../core/analyze.js';
+import { type CoverageReport } from '../core/coverage.js';
+import type { Finding } from '../core/finding.js';
+import { type RuntimeCheckResult } from '../platform/runtime-version.js';
+import type { DependencyReport } from '../platform/dependency-rule.js';
+export type { FileParseProblem, Suppression } from '../core/analyze.js';
+export interface ScanOptions {
+    /** Only run these rule ids. Empty = all. */
+    readonly only?: readonly string[];
+    /** Glob-ish paths to skip entirely. Reported, never silently applied. */
+    readonly exclude?: readonly string[];
+    /** Turn off cross-file resolution (faster, less memory, fewer findings). */
+    readonly noCrossFile?: boolean;
+    /** Print progress to stderr. */
+    readonly onProgress?: (done: number, total: number, file: string) => void;
+}
+export interface ScanResult {
+    readonly target: string;
+    readonly findings: readonly Finding[];
+    /** Lines the tracer proved safe. Reported so "clean" can mean "checked". */
+    readonly verifiedClean: AnalysisResult['verifiedClean'];
+    /** Branches and cases not followed because they cannot run, with the reason. */
+    readonly unreachableCode: AnalysisResult['unreachableCode'];
+    /** Map and list reads answered by key or position, with the write that answers each. */
+    readonly collectionReadsResolved: AnalysisResult['collectionReadsResolved'];
+    /** Calls where a trace ended because the result is new data, not the argument. */
+    readonly tracesStoppedAtNewData: AnalysisResult['tracesStoppedAtNewData'];
+    /**
+     * Which PHP the project declares, and what php.net's facts say about it -
+     * platform/runtime-version.ts. Null when --only left the check out.
+     */
+    readonly runtimeVersions: RuntimeCheckResult | null;
+    /**
+     * What `scan --deps` read and asked osv.dev. Absent when the check did not run -
+     * scan() never sets it; the CLI adds it, because it is the one network call.
+     */
+    readonly dependencies?: DependencyReport;
+    /** Per-file participation, so a file a flow passes through is never "clean". */
+    readonly fileRoles: AnalysisResult['fileRoles'];
+    /** Where the tracer ran out, counted for this scan. */
+    readonly traceLimits: AnalysisResult['traceLimits'];
+    readonly stats: AnalysisResult['stats'] & {
+        readonly filesFound: number;
+        readonly filesWithParseErrors: number;
+    };
+    readonly byLanguage: AnalysisResult['byLanguage'];
+    readonly parseProblems: AnalysisResult['parseProblems'];
+    readonly oversizedFiles: readonly string[];
+    /** What --exclude removed. A gap the user chose is still a gap worth printing. */
+    readonly excluded: {
+        readonly patterns: readonly string[];
+        readonly fileCount: number;
+        readonly directories: readonly string[];
+    };
+    /** Findings the code explicitly asked us to ignore. Reported, never hidden. */
+    readonly suppressions: AnalysisResult['suppressions'];
+    readonly coverage: CoverageReport;
+    /** How cross-file resolution went. */
+    readonly crossFile: AnalysisResult['crossFile'];
+    /** What the scan spent on syntax trees, and whether it had to spill. */
+    readonly treeMemory: AnalysisResult['treeMemory'];
+}
+export declare function scan(target: string, options?: ScanOptions): Promise<ScanResult>;

package/dist/src/engine/scan.js

@@ -0,0 +1,129 @@
+/**
+ * THE NODE SHELL
+ * ==============
+ *
+ * Everything that only makes sense on a machine with a filesystem: walking a
+ * directory, honouring --exclude, reading bytes, and shortening paths against
+ * the working directory so terminal output stays readable.
+ *
+ * The analysis itself is NOT here. It moved to src/core/analyze.ts when the
+ * browser UI arrived, so the web version could run the same code rather than a
+ * lookalike. What is left is the pipeline seam:
+ *
+ *   collectFiles  ->  read text  ->  analyze()  ->  a ScanResult
+ *
+ * If you find yourself wanting to change how a FINDING is produced, this is the
+ * wrong file - that belongs in core/analyze.ts, where the browser sees it too.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { analyze } from '../core/analyze.js';
+import { buildCoverageReport } from '../core/coverage.js';
+import { SCANNABLE_EXTENSIONS } from '../parse/languages.js';
+import { useNodeGrammars } from '../parse/node-grammars.js';
+import { checkRuntimeVersions, RUNTIME_VERSION_RULE } from '../platform/runtime-version.js';
+import { collectFiles } from './walk.js';
+export async function scan(target, options = {}) {
+    // Tell the parser it is running on Node before anything loads a grammar.
+    // The browser worker makes the equivalent call with its own loader.
+    useNodeGrammars();
+    const walk = await collectFiles(target, {
+        scannable: SCANNABLE_EXTENSIONS,
+        exclude: options.exclude ?? [],
+    });
+    // Read the text. A file we cannot read simply never reaches the analyzer;
+    // it shows up as the gap between filesFound and filesParsed.
+    const inputs = [];
+    for (const filePath of walk.files) {
+        try {
+            inputs.push({ path: filePath, source: await readFile(filePath, 'utf8') });
+        }
+        catch {
+            // permissions, a broken symlink, a race with a build tool
+        }
+    }
+    /**
+     * DEFUSE_TREE_BUDGET_MB - how much WebAssembly heap the scan may hold in syntax
+     * trees before it starts freeing the least recently used one.
+     *
+     * An environment variable rather than a flag, deliberately. It exists to be
+     * turned down hard in testing: the interesting question about the tree store
+     * is not "does it work when nothing is ever evicted" but "are the findings
+     * still identical when almost everything is". A budget of 1 MB forces a
+     * re-parse for nearly every cross-file hop, which is exactly the condition
+     * the identity check should be run under.
+     *
+     * Anyone who genuinely needs it in production can set it, and the value used
+     * is printed in the report either way.
+     */
+    const budgetMb = Number(process.env['DEFUSE_TREE_BUDGET_MB']);
+    const treeBudget = Number.isFinite(budgetMb) && budgetMb > 0 ? Math.round(budgetMb * 1024 * 1024) : undefined;
+    const result = await analyze(inputs, {
+        ...(options.only ? { only: options.only } : {}),
+        ...(options.noCrossFile !== undefined ? { noCrossFile: options.noCrossFile } : {}),
+        ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+        ...(treeBudget !== undefined ? { treeBudgetBytes: treeBudget } : {}),
+        toDisplay: (absolutePath) => path.relative(process.cwd(), absolutePath) || absolutePath,
+    });
+    /*
+     * THE RUNTIME VERSION CHECK reads declarations, not code, so it runs beside
+     * the analysis rather than inside it. Its findings join the same list - a
+     * PHP release with a known critical flaw belongs next to the code problems,
+     * not in a footnote - and they are all signature-based by construction.
+     */
+    const runtimeVersions = !options.only || options.only.length === 0 || options.only.includes(RUNTIME_VERSION_RULE.id)
+        ? await (async () => {
+            const files = [];
+            for (const filePath of walk.runtimeFiles) {
+                try {
+                    files.push({
+                        path: path.relative(process.cwd(), filePath) || filePath,
+                        text: await readFile(filePath, 'utf8'),
+                    });
+                }
+                catch {
+                    // unreadable - same treatment as a source file
+                }
+            }
+            return checkRuntimeVersions(files, {
+                today: new Date().toISOString().slice(0, 10),
+                phpFilesScanned: result.byLanguage['php'] ?? 0,
+            });
+        })()
+        : null;
+    return {
+        target,
+        findings: [...result.findings, ...(runtimeVersions?.findings ?? [])],
+        verifiedClean: result.verifiedClean,
+        unreachableCode: result.unreachableCode,
+        collectionReadsResolved: result.collectionReadsResolved,
+        tracesStoppedAtNewData: result.tracesStoppedAtNewData,
+        runtimeVersions,
+        fileRoles: result.fileRoles,
+        traceLimits: result.traceLimits,
+        stats: {
+            ...result.stats,
+            filesFound: walk.files.length,
+            filesSkipped: walk.files.length - result.stats.filesParsed,
+            filesWithParseErrors: result.parseProblems.length,
+        },
+        byLanguage: result.byLanguage,
+        parseProblems: result.parseProblems,
+        oversizedFiles: walk.oversizedFiles,
+        excluded: {
+            patterns: options.exclude ?? [],
+            fileCount: walk.excludedCount,
+            directories: walk.excludedDirectories,
+        },
+        suppressions: result.suppressions,
+        crossFile: result.crossFile,
+        treeMemory: result.treeMemory,
+        // Rebuilt here because only the walker knows which file types it passed
+        // over - the analyzer never saw them.
+        coverage: buildCoverageReport([...walk.skippedByExtension.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 12)
+            .map(([ext, count]) => `${ext} (${count} file${count === 1 ? '' : 's'})`)),
+    };
+}
+//# sourceMappingURL=scan.js.map

package/dist/src/engine/scan.js.map

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

package/dist/src/engine/shapes.d.ts

@@ -0,0 +1,47 @@
+/**
+ * THE SHAPE LAYER
+ * ===============
+ *
+ * This is the translator between "five different languages" and "one set of
+ * rules". It uses tree-sitter's QUERY LANGUAGE, which is worth understanding
+ * because it is the only unfamiliar syntax in this project.
+ *
+ * A tree-sitter query is a pattern written as nested parentheses that describes
+ * a shape of tree, with @names marking the parts you want back:
+ *
+ *     (call_expression
+ *       function: (member_expression
+ *         object: (_) @receiver
+ *         property: (property_identifier) @method)
+ *       arguments: (arguments) @args) @call
+ *
+ * Read it as: "find a call_expression; its `function` child must be a
+ * member_expression (that's the `a.b` shape); give me whatever is on the left
+ * of the dot as @receiver, the name after the dot as @method, the argument list
+ * as @args, and the whole call as @call."
+ *
+ * `(_)` means "any node". Field names before the colon (`function:`,
+ * `object:`) are the ROLE labels you saw in the AST dump. Matching on roles
+ * instead of child positions is what makes these patterns stable.
+ *
+ * Every language below gets its own query because the grammars use different
+ * node names for the same idea - JavaScript says `call_expression`, Python says
+ * `call`, Java says `method_invocation`. The OUTPUT is identical for all five,
+ * and that output is what rules see.
+ *
+ * ADDING A LANGUAGE LATER means adding two query strings to this file. No rule
+ * changes.
+ */
+import type { Shape } from '../rules/contract.js';
+import type { LanguageId } from '../parse/languages.js';
+import { type ParsedFile } from '../parse/parser.js';
+/**
+ * Lower one parsed file into the flat list of shapes rules will see.
+ * Order is source order, which makes reports read top-to-bottom like the file.
+ */
+export declare function extractShapes(file: ParsedFile, language: LanguageId): Promise<Shape[]>;
+/** Exposed so a self-check can compile every query against every grammar. */
+export declare const SHAPE_QUERY_SOURCES: {
+    readonly calls: Record<LanguageId, string>;
+    readonly assignments: Record<LanguageId, string>;
+};

package/dist/src/engine/shapes.js

@@ -0,0 +1,328 @@
+/**
+ * THE SHAPE LAYER
+ * ===============
+ *
+ * This is the translator between "five different languages" and "one set of
+ * rules". It uses tree-sitter's QUERY LANGUAGE, which is worth understanding
+ * because it is the only unfamiliar syntax in this project.
+ *
+ * A tree-sitter query is a pattern written as nested parentheses that describes
+ * a shape of tree, with @names marking the parts you want back:
+ *
+ *     (call_expression
+ *       function: (member_expression
+ *         object: (_) @receiver
+ *         property: (property_identifier) @method)
+ *       arguments: (arguments) @args) @call
+ *
+ * Read it as: "find a call_expression; its `function` child must be a
+ * member_expression (that's the `a.b` shape); give me whatever is on the left
+ * of the dot as @receiver, the name after the dot as @method, the argument list
+ * as @args, and the whole call as @call."
+ *
+ * `(_)` means "any node". Field names before the colon (`function:`,
+ * `object:`) are the ROLE labels you saw in the AST dump. Matching on roles
+ * instead of child positions is what makes these patterns stable.
+ *
+ * Every language below gets its own query because the grammars use different
+ * node names for the same idea - JavaScript says `call_expression`, Python says
+ * `call`, Java says `method_invocation`. The OUTPUT is identical for all five,
+ * and that output is what rules see.
+ *
+ * ADDING A LANGUAGE LATER means adding two query strings to this file. No rule
+ * changes.
+ */
+import { Query } from 'web-tree-sitter';
+import { getLanguage } from '../parse/parser.js';
+/* ---------------------------------------------------------------------------
+ * CALL SITES: "something is being called with arguments"
+ * ------------------------------------------------------------------------ */
+/** Shared by C and C++, because C++ is a superset of these two shapes. */
+const C_CALL_QUERY = `
+  (call_expression
+    function: (identifier) @method
+    arguments: (argument_list) @args) @call
+  (call_expression
+    function: (field_expression argument: (_) @receiver field: (field_identifier) @method)
+    arguments: (argument_list) @args) @call
+`;
+const CALL_QUERIES = {
+    javascript: `
+    (call_expression
+      function: (member_expression object: (_) @receiver property: (property_identifier) @method)
+      arguments: (arguments) @args) @call
+    (call_expression
+      function: (identifier) @method
+      arguments: (arguments) @args) @call
+    (new_expression
+      constructor: (_) @method
+      arguments: (arguments) @args) @call
+  `,
+    // TypeScript's grammar is JavaScript's grammar plus types, so the call shapes
+    // are byte-for-byte identical. Kept as a separate entry rather than an alias
+    // so that a future TS-only pattern has an obvious home.
+    typescript: `
+    (call_expression
+      function: (member_expression object: (_) @receiver property: (property_identifier) @method)
+      arguments: (arguments) @args) @call
+    (call_expression
+      function: (identifier) @method
+      arguments: (arguments) @args) @call
+    (new_expression
+      constructor: (_) @method
+      arguments: (arguments) @args) @call
+  `,
+    python: `
+    (call
+      function: (attribute object: (_) @receiver attribute: (identifier) @method)
+      arguments: (argument_list) @args) @call
+    (call
+      function: (identifier) @method
+      arguments: (argument_list) @args) @call
+  `,
+    java: `
+    (method_invocation
+      object: (_) @receiver
+      name: (identifier) @method
+      arguments: (argument_list) @args) @call
+    (method_invocation
+      name: (identifier) @method
+      arguments: (argument_list) @args) @call
+    (object_creation_expression
+      type: (_) @method
+      arguments: (argument_list) @args) @call
+  `,
+    go: `
+    (call_expression
+      function: (selector_expression operand: (_) @receiver field: (field_identifier) @method)
+      arguments: (argument_list) @args) @call
+    (call_expression
+      function: (identifier) @method
+      arguments: (argument_list) @args) @call
+  `,
+    // PHP has three call shapes: a bare function, a method on an object, and a
+    // static method on a class. `echo` is deliberately NOT here - it is a
+    // statement, not a call, and the XSS rule handles it separately.
+    php: `
+    (function_call_expression
+      function: (name) @method
+      arguments: (arguments) @args) @call
+    (member_call_expression
+      object: (_) @receiver
+      name: (name) @method
+      arguments: (arguments) @args) @call
+    (scoped_call_expression
+      scope: (_) @receiver
+      name: (name) @method
+      arguments: (arguments) @args) @call
+    (object_creation_expression
+      (name) @method
+      (arguments) @args) @call
+  `,
+    /*
+     * C. Two shapes only, because C has two: a bare call, and a call through a
+     * struct member. Every node type and field name below was read off the real
+     * grammar with a query probe rather than assumed - the same discipline the
+     * PHP entry learned the hard way, when `if_statement` turned out to use
+     * `body` where every other grammar uses `consequence`.
+     */
+    c: C_CALL_QUERY,
+    /*
+     * C++ is C plus namespaces. `std::system(cmd)` parses as a
+     * qualified_identifier, NOT an identifier, so a query that only matched the
+     * C shapes would miss it - and reaching system() through <cstdlib> is the
+     * stylistically CORRECT way to do it in C++, which means the well-written
+     * code would be the code that slipped through.
+     */
+    cpp: `
+    ${C_CALL_QUERY}
+    (call_expression
+      function: (qualified_identifier name: (identifier) @method)
+      arguments: (argument_list) @args) @call
+  `,
+};
+/* ---------------------------------------------------------------------------
+ * ASSIGNMENTS: "a name is being bound to a value"
+ *
+ * Deliberately broad: it covers `x = v`, `const x = v`, object/dict entries
+ * `{ key: v }`, and keyword arguments `f(key=v)`. Hardcoded credentials hide in
+ * all of those, and so does `element.innerHTML = ...`.
+ * ------------------------------------------------------------------------ */
+const JS_ASSIGN_QUERY = `
+  (assignment_expression left: (_) @target right: (_) @value) @assign
+  (variable_declarator name: (_) @target value: (_) @value) @assign
+  (pair key: (_) @target value: (_) @value) @assign
+  (augmented_assignment_expression left: (_) @target right: (_) @value) @assign
+`;
+const C_ASSIGN_QUERY = `
+  (assignment_expression left: (_) @target right: (_) @value) @assign
+  (init_declarator declarator: (_) @target value: (_) @value) @assign
+`;
+const ASSIGNMENT_QUERIES = {
+    php: `
+    (assignment_expression left: (_) @target right: (_) @value) @assign
+    (property_element (variable_name) @target (_) @value) @assign
+    (echo_statement "echo" @target (_) @value) @assign
+  `,
+    javascript: JS_ASSIGN_QUERY,
+    typescript: `
+    ${JS_ASSIGN_QUERY}
+    (public_field_definition name: (_) @target value: (_) @value) @assign
+  `,
+    python: `
+    (assignment left: (_) @target right: (_) @value) @assign
+    (pair key: (_) @target value: (_) @value) @assign
+    (keyword_argument name: (identifier) @target value: (_) @value) @assign
+  `,
+    java: `
+    (variable_declarator name: (identifier) @target value: (_) @value) @assign
+    (assignment_expression left: (_) @target right: (_) @value) @assign
+  `,
+    go: `
+    (short_var_declaration left: (expression_list) @target right: (expression_list) @value) @assign
+    (assignment_statement left: (expression_list) @target right: (expression_list) @value) @assign
+    (var_spec name: (identifier) @target value: (expression_list) @value) @assign
+    (const_spec name: (identifier) @target value: (expression_list) @value) @assign
+    (keyed_element (literal_element (identifier) @target) (literal_element (_) @value)) @assign
+  `,
+    /*
+     * C and C++ share these. `init_declarator` is the declaration-with-value
+     * form (`char *p = getenv(...)`), and its @target captures the DECLARATOR
+     * rather than a bare name - so `*name = getenv("USER")` yields a target of
+     * `*name`, pointer star included. The tracer strips it; see POINTER_PREFIX
+     * in taint/tracer.ts. Recorded here because it is the kind of detail that
+     * silently halves a language's coverage if nobody notices it.
+     */
+    c: C_ASSIGN_QUERY,
+    cpp: C_ASSIGN_QUERY,
+};
+/* ------------------------------------------------------------------------ */
+/** Compiled queries are expensive to build and cheap to reuse. Cache per grammar. */
+const queryCache = new Map();
+async function compile(grammar, key, source) {
+    const cacheKey = `${grammar}:${key}`;
+    const cached = queryCache.get(cacheKey);
+    if (cached)
+        return cached;
+    const language = await getLanguage(grammar);
+    const query = new Query(language, source);
+    queryCache.set(cacheKey, query);
+    return query;
+}
+function collapse(text) {
+    return (text ?? '').replace(/\s+/g, ' ').trim();
+}
+/** Pull one capture out of a match. Returns null when the capture is optional. */
+function captured(match, name) {
+    for (const capture of match.captures) {
+        if (capture.name === name)
+            return capture.node;
+    }
+    return null;
+}
+/**
+ * Argument lists contain punctuation as well as expressions. `namedChildren`
+ * gives us only the meaningful ones - see the "named vs anonymous" note in
+ * astDump.ts.
+ */
+function argumentNodes(argsNode) {
+    if (!argsNode)
+        return [];
+    return argsNode.namedChildren
+        .filter((n) => n !== null)
+        // PHP wraps every argument in an `argument` node, so the expression a rule
+        // wants to examine sits one level down. Without this unwrap every PHP
+        // argument reads as the node type `argument` and no content check matches.
+        .map((n) => (n.type === 'argument' ? (n.namedChildren.find((c) => c !== null) ?? n) : n));
+}
+/**
+ * Go writes `a, b := f(), g()` - both sides are lists. When the lists line up
+ * we pair them; when they don't (a multi-return call) we bind every name to the
+ * single value node, which is honest enough for signature matching and is
+ * flagged as a known imprecision in the Go coverage notes.
+ */
+function goPairs(target, value) {
+    const targets = target.type === 'expression_list' ? target.namedChildren : [target];
+    const values = value.type === 'expression_list' ? value.namedChildren : [value];
+    const pairs = [];
+    for (let i = 0; i < targets.length; i++) {
+        const t = targets[i];
+        if (!t)
+            continue;
+        const v = values.length === targets.length ? values[i] : values[0];
+        if (v)
+            pairs.push({ t, v });
+    }
+    return pairs;
+}
+/** Last dotted segment: "config.db.password" -> "password". */
+function lastSegment(text) {
+    const cleaned = text.replace(/\[["']?|["']?\]/g, '.').replace(/\.+$/, '');
+    const parts = cleaned.split('.');
+    return (parts[parts.length - 1] ?? cleaned).trim();
+}
+/**
+ * Lower one parsed file into the flat list of shapes rules will see.
+ * Order is source order, which makes reports read top-to-bottom like the file.
+ */
+export async function extractShapes(file, language) {
+    const shapes = [];
+    const seen = new Set();
+    const callQuery = await compile(file.grammar, 'calls', CALL_QUERIES[language]);
+    for (const match of callQuery.matches(file.root)) {
+        const call = captured(match, 'call');
+        const method = captured(match, 'method');
+        if (!call || !method)
+            continue;
+        // Java's two method_invocation patterns overlap (object is optional), so the
+        // same node can match twice. Dedupe by node id.
+        if (seen.has(call.id))
+            continue;
+        seen.add(call.id);
+        const receiver = captured(match, 'receiver');
+        const receiverText = collapse(receiver?.text);
+        const calleeName = collapse(method.text);
+        // Java's `method_invocation` has no `function` field - the receiver and the
+        // name are separate children - so we rebuild "receiver.name" by hand there.
+        const functionNode = call.childForFieldName('function') ?? call.childForFieldName('constructor');
+        const site = {
+            kind: 'call',
+            node: call,
+            calleeName,
+            receiverText,
+            calleeText: collapse(functionNode?.text ?? (receiverText ? `${receiverText}.${calleeName}` : calleeName)),
+            args: argumentNodes(captured(match, 'args')),
+        };
+        shapes.push(site);
+    }
+    const assignQuery = await compile(file.grammar, 'assignments', ASSIGNMENT_QUERIES[language]);
+    for (const match of assignQuery.matches(file.root)) {
+        const node = captured(match, 'assign');
+        const target = captured(match, 'target');
+        const value = captured(match, 'value');
+        if (!node || !target || !value)
+            continue;
+        if (seen.has(node.id))
+            continue;
+        seen.add(node.id);
+        const pairs = language === 'go' ? goPairs(target, value) : [{ t: target, v: value }];
+        for (const pair of pairs) {
+            const targetText = collapse(pair.t.text);
+            shapes.push({
+                kind: 'assignment',
+                node,
+                targetText,
+                targetName: lastSegment(targetText).replace(/^["']|["']$/g, ''),
+                value: pair.v,
+            });
+        }
+    }
+    shapes.sort((a, b) => a.node.startIndex - b.node.startIndex);
+    return shapes;
+}
+/** Exposed so a self-check can compile every query against every grammar. */
+export const SHAPE_QUERY_SOURCES = {
+    calls: CALL_QUERIES,
+    assignments: ASSIGNMENT_QUERIES,
+};
+//# sourceMappingURL=shapes.js.map

package/dist/src/engine/shapes.js.map

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

package/dist/src/engine/walk.d.ts

@@ -0,0 +1,60 @@
+/**
+ * FILE DISCOVERY
+ *
+ * Turning "scan this path" into "here is the list of files". Boring code, but
+ * two decisions in it matter:
+ *
+ * 1. We skip dependency and build directories. Scanning node_modules finds
+ *    thousands of "vulnerabilities" in other people's code that you cannot fix
+ *    and did not write. Dependency risk is a real and separate problem
+ *    (Software Composition Analysis) and it deserves its own tool, not noise
+ *    inside this one.
+ *
+ * 2. We record the extensions we skipped. That list feeds the coverage report,
+ *    so a scan of a repo that is 70% Ruby says "we did not look at 412 .rb
+ *    files" instead of quietly reporting "no issues found".
+ */
+export interface WalkResult {
+    readonly files: readonly string[];
+    /** Extension -> how many files with it we passed over. Feeds the coverage report. */
+    readonly skippedByExtension: ReadonlyMap<string, number>;
+    readonly oversizedFiles: readonly string[];
+    /** How many files --exclude removed. Printed, never silent. */
+    readonly excludedCount: number;
+    /**
+     * Directories --exclude pruned. Counted separately because we stop walking
+     * them, so we honestly do not know how many files were inside. Saying
+     * "0 files excluded" after skipping a whole tree would be its own small lie.
+     */
+    readonly excludedDirectories: readonly string[];
+    /**
+     * Files that declare which PHP the project runs on - Dockerfiles, compose
+     * files, composer.json, `.php-version`. Not source code, so not in `files`;
+     * the runtime version check reads them (platform/runtime-version.ts). The
+     * same directories are skipped as for code, so a dependency's composer.json
+     * under vendor/ is never mistaken for the project's own.
+     */
+    readonly runtimeFiles: readonly string[];
+}
+export interface WalkOptions {
+    /** Extensions we are able to parse. Everything else is counted and skipped. */
+    readonly scannable: readonly string[];
+    readonly maxBytes?: number;
+    /** Glob-ish patterns from --exclude. */
+    readonly exclude?: readonly string[];
+}
+/**
+ * Turn a glob into a regular expression.
+ *
+ * Supported, deliberately a small subset:
+ *   **   any number of path segments
+ *   *    anything except a path separator
+ *   ?    one character
+ * A pattern with no wildcards and no separator (e.g. `vendor`) matches any path
+ * SEGMENT with that name, which is what people mean by `--exclude=vendor`.
+ *
+ * Everything is matched against the path with forward slashes, so the same
+ * pattern works on Windows and Unix.
+ */
+export declare function globToRegExp(pattern: string): RegExp;
+export declare function collectFiles(target: string, options: WalkOptions): Promise<WalkResult>;