auditor-lambda 0.3.41 → 0.6.0

package/dist/extractors/analyzers/css.js

@@ -0,0 +1,101 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { graphEdge, normalizeGraphPath } from "../graphPathUtils.js";
+import { getTreeSitterParser } from "./treeSitter.js";
+import { resolveResourceUrl } from "./resourceUrl.js";
+const CSS_IMPORT_EDGE_CONFIDENCE = 0.9;
+const CSS_URL_EDGE_CONFIDENCE = 0.82;
+const MAX_CSS_SOURCE_BYTES = 512 * 1024;
+function supports(file) {
+    return normalizeGraphPath(file).toLowerCase().endsWith(".css");
+}
+function unquote(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 &&
+        ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/** First quoted or unquoted literal value beneath a node (string / url arg). */
+function literalValue(node) {
+    // tree-sitter-css string_value includes the surrounding quotes; plain_value
+    // (unquoted url() args) does not.
+    const value = node.descendantsOfType(["string_value", "plain_value"])[0];
+    return value ? unquote(value.text) : undefined;
+}
+function collectFileEdges(fromPath, root, pathLookup, edges) {
+    const importTargets = new Set();
+    // @import "x.css";  and  @import url("x.css");
+    for (const statement of root.descendantsOfType("import_statement")) {
+        const url = literalValue(statement);
+        if (!url)
+            continue;
+        const target = resolveResourceUrl(fromPath, url, pathLookup);
+        if (!target || target === fromPath || importTargets.has(target))
+            continue;
+        importTargets.add(target);
+        edges.push(graphEdge({
+            from: fromPath,
+            to: target,
+            kind: "css-import",
+            confidence: CSS_IMPORT_EDGE_CONFIDENCE,
+            reason: `CSS @import references '${target}'.`,
+        }));
+    }
+    // url(...) references in declarations (background images, fonts, …).
+    const seenUrls = new Set(importTargets);
+    for (const call of root.descendantsOfType("call_expression")) {
+        if (!/^\s*url\s*\(/i.test(call.text))
+            continue;
+        const url = literalValue(call);
+        if (!url)
+            continue;
+        const target = resolveResourceUrl(fromPath, url, pathLookup);
+        if (!target || target === fromPath || seenUrls.has(target))
+            continue;
+        seenUrls.add(target);
+        edges.push(graphEdge({
+            from: fromPath,
+            to: target,
+            kind: "css-url",
+            confidence: CSS_URL_EDGE_CONFIDENCE,
+            reason: `CSS url() references '${target}'.`,
+        }));
+    }
+}
+async function analyze(files, context) {
+    if (files.length === 0)
+        return { edges: [] };
+    const parser = await getTreeSitterParser("css", context.dependencyPath);
+    if (!parser)
+        return { edges: [] };
+    const root = resolve(context.root);
+    const edges = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(resolve(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.length > MAX_CSS_SOURCE_BYTES)
+            continue;
+        try {
+            const tree = parser.parse(content);
+            collectFileEdges(normalizeGraphPath(file), tree.rootNode, context.pathLookup, edges);
+        }
+        catch {
+            // Degrade to the floor for this file.
+        }
+    }
+    return { edges };
+}
+export const cssAnalyzer = {
+    id: "css",
+    dependency: "web-tree-sitter",
+    supports,
+    analyze,
+};

package/dist/extractors/analyzers/html.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageAnalyzer } from "./types.js";
+export declare const htmlAnalyzer: LanguageAnalyzer;

package/dist/extractors/analyzers/html.js

@@ -0,0 +1,92 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { graphEdge, normalizeGraphPath } from "../graphPathUtils.js";
+import { getTreeSitterParser } from "./treeSitter.js";
+import { resolveResourceUrl } from "./resourceUrl.js";
+// Above the regex floor's html-resource-link so the merge prefers the parsed
+// edge for the same (from, to).
+const HTML_RESOURCE_EDGE_CONFIDENCE = 0.96;
+const MAX_HTML_SOURCE_BYTES = 512 * 1024;
+const HTML_EXTENSIONS = [".html", ".htm"];
+// tag → the attribute carrying its resource reference.
+const RESOURCE_ATTRIBUTE = {
+    script: "src",
+    link: "href",
+    img: "src",
+};
+function supports(file) {
+    const lower = normalizeGraphPath(file).toLowerCase();
+    return HTML_EXTENSIONS.some((extension) => lower.endsWith(extension));
+}
+function attributeValue(tag, name) {
+    for (const attribute of tag.descendantsOfType("attribute")) {
+        const attributeName = attribute
+            .descendantsOfType("attribute_name")[0]
+            ?.text?.toLowerCase();
+        if (attributeName !== name)
+            continue;
+        const value = attribute.descendantsOfType("attribute_value")[0]?.text;
+        if (value && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
+function collectFileEdges(fromPath, root, pathLookup, edges) {
+    const seen = new Set();
+    for (const tag of root.descendantsOfType("start_tag")) {
+        const tagName = tag.descendantsOfType("tag_name")[0]?.text?.toLowerCase();
+        if (!tagName)
+            continue;
+        const attribute = RESOURCE_ATTRIBUTE[tagName];
+        if (!attribute)
+            continue;
+        const url = attributeValue(tag, attribute);
+        if (!url)
+            continue;
+        const target = resolveResourceUrl(fromPath, url, pathLookup);
+        if (!target || target === fromPath || seen.has(target))
+            continue;
+        seen.add(target);
+        edges.push(graphEdge({
+            from: fromPath,
+            to: target,
+            kind: "html-resource",
+            confidence: HTML_RESOURCE_EDGE_CONFIDENCE,
+            reason: `HTML <${tagName} ${attribute}> references '${target}'.`,
+        }));
+    }
+}
+async function analyze(files, context) {
+    if (files.length === 0)
+        return { edges: [] };
+    const parser = await getTreeSitterParser("html", context.dependencyPath);
+    if (!parser)
+        return { edges: [] };
+    const root = resolve(context.root);
+    const edges = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(resolve(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.length > MAX_HTML_SOURCE_BYTES)
+            continue;
+        try {
+            const tree = parser.parse(content);
+            collectFileEdges(normalizeGraphPath(file), tree.rootNode, context.pathLookup, edges);
+        }
+        catch {
+            // Degrade to the floor for this file.
+        }
+    }
+    return { edges };
+}
+export const htmlAnalyzer = {
+    id: "html",
+    dependency: "web-tree-sitter",
+    supports,
+    analyze,
+};

package/dist/extractors/analyzers/merge.d.ts

@@ -0,0 +1,14 @@
+import type { GraphEdge } from "@audit-tools/shared";
+export declare const TS_IMPORT_EDGE_CONFIDENCE = 0.99;
+export declare const TS_REEXPORT_EDGE_CONFIDENCE = 0.99;
+export declare const TS_EXTENDS_EDGE_CONFIDENCE = 0.97;
+export declare const TS_IMPLEMENTS_EDGE_CONFIDENCE = 0.97;
+export declare const TS_CALL_EDGE_CONFIDENCE = 0.9;
+/**
+ * Merge analyzer edges into an existing floor bucket (e.g. `graphs.imports`).
+ * Within a known relationship group, edges sharing (from, to) collapse to the
+ * highest-confidence one (ties favour the later/analyzer edge); ungrouped kinds
+ * keep their per-kind identity. Self-edges are dropped. Result is deduped and
+ * sorted, matching the floor's ordering contract.
+ */
+export declare function mergeAnalyzerEdges(floor: GraphEdge[], analyzer: GraphEdge[]): GraphEdge[];

package/dist/extractors/analyzers/merge.js

@@ -0,0 +1,85 @@
+// Analyzer edge confidences are set above their regex-floor counterparts so the
+// group-aware merge below prefers the compiler-derived edge for the same
+// (from, to) relationship. Floor import kinds sit at 0.95 (see graph.ts).
+export const TS_IMPORT_EDGE_CONFIDENCE = 0.99;
+export const TS_REEXPORT_EDGE_CONFIDENCE = 0.99;
+export const TS_EXTENDS_EDGE_CONFIDENCE = 0.97;
+export const TS_IMPLEMENTS_EDGE_CONFIDENCE = 0.97;
+export const TS_CALL_EDGE_CONFIDENCE = 0.9;
+/**
+ * Kinds that represent the same underlying relationship collapse together during
+ * a merge (highest confidence wins). Kinds with no group keep their distinct
+ * (from, to, kind) identity — so floor-only relationships such as
+ * `heuristic-container-edge` or `heuristic-auth-session-link` are never dropped
+ * by an analyzer that happens to connect the same two nodes a different way.
+ */
+const EDGE_GROUP = {
+    // import relationship
+    esm: "import",
+    "re-export": "import",
+    "dynamic-import": "import",
+    commonjs: "import",
+    "ts-import": "import",
+    "ts-reexport": "import",
+    // Python imports: the tree-sitter analyzer (py-*) supersedes the regex floor
+    // (python-*) for the same (from, to).
+    "python-import": "import",
+    "python-from-import": "import",
+    "py-import": "import",
+    "py-from-import": "import",
+    // HTML resource references: the tree-sitter analyzer (html-resource)
+    // supersedes the regex floor (html-resource-link).
+    "html-resource-link": "html-resource",
+    "html-resource": "html-resource",
+    // inheritance relationship
+    "ts-extends": "inheritance",
+    "ts-implements": "inheritance",
+    // call relationship
+    "ts-call": "call",
+};
+function edgeGroupOf(edge) {
+    return edge.kind ? EDGE_GROUP[edge.kind] : undefined;
+}
+function confidenceOf(edge) {
+    return typeof edge.confidence === "number" && Number.isFinite(edge.confidence)
+        ? edge.confidence
+        : 0;
+}
+function groupedKey(edge, group) {
+    return `${edge.from}\0${edge.to}\0${group}`;
+}
+function ungroupedKey(edge) {
+    return `${edge.from}\0${edge.to}\0${edge.kind ?? ""}`;
+}
+function sortEdges(edges) {
+    return edges.sort((a, b) => a.from.localeCompare(b.from) ||
+        a.to.localeCompare(b.to) ||
+        (a.kind ?? "").localeCompare(b.kind ?? ""));
+}
+/**
+ * Merge analyzer edges into an existing floor bucket (e.g. `graphs.imports`).
+ * Within a known relationship group, edges sharing (from, to) collapse to the
+ * highest-confidence one (ties favour the later/analyzer edge); ungrouped kinds
+ * keep their per-kind identity. Self-edges are dropped. Result is deduped and
+ * sorted, matching the floor's ordering contract.
+ */
+export function mergeAnalyzerEdges(floor, analyzer) {
+    const grouped = new Map();
+    const ungrouped = new Map();
+    for (const edge of [...floor, ...analyzer]) {
+        if (edge.from === edge.to)
+            continue;
+        const group = edgeGroupOf(edge);
+        if (group) {
+            const key = groupedKey(edge, group);
+            const existing = grouped.get(key);
+            if (!existing || confidenceOf(edge) >= confidenceOf(existing)) {
+                grouped.set(key, edge);
+            }
+        }
+        else {
+            ungrouped.set(ungroupedKey(edge), edge);
+        }
+    }
+    return sortEdges([...grouped.values(), ...ungrouped.values()]);
+}

package/dist/extractors/analyzers/python.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageAnalyzer } from "./types.js";
+export declare const pythonAnalyzer: LanguageAnalyzer;

package/dist/extractors/analyzers/python.js

@@ -0,0 +1,104 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { graphEdge, normalizeGraphPath } from "../graphPathUtils.js";
+import { isPythonSourcePath, resolvePythonFromImportTargets, resolvePythonImportTarget, } from "../graphPythonImports.js";
+import { getTreeSitterParser } from "./treeSitter.js";
+// Set above the regex floor's 0.95 so the merge prefers the AST-resolved edge
+// for the same (from, to). Resolution itself is shared with the floor, so the
+// only difference is parse-grade extraction.
+const PY_IMPORT_EDGE_CONFIDENCE = 0.97;
+const MAX_PYTHON_SOURCE_BYTES = 512 * 1024;
+function supports(file) {
+    return isPythonSourcePath(file);
+}
+/** The bare module text for one `import` name (unwrapping `x.y as z`). */
+function importModuleText(nameNode) {
+    const moduleNode = nameNode.type === "aliased_import"
+        ? nameNode.childForFieldName("name")
+        : nameNode;
+    const text = moduleNode?.text?.trim();
+    return text && text.length > 0 ? text : undefined;
+}
+function collectFileEdges(fromPath, root, pathLookup, edges) {
+    const seen = new Set();
+    const push = (target, kind, specifier) => {
+        if (target === fromPath)
+            return;
+        const key = `${kind}\0${target}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        edges.push(graphEdge({
+            from: fromPath,
+            to: target,
+            kind,
+            confidence: PY_IMPORT_EDGE_CONFIDENCE,
+            reason: `tree-sitter resolved Python import '${specifier}' to '${target}'.`,
+        }));
+    };
+    for (const node of root.descendantsOfType("import_statement")) {
+        for (const nameNode of childrenForField(node, "name")) {
+            const specifier = importModuleText(nameNode);
+            if (!specifier)
+                continue;
+            const target = resolvePythonImportTarget(fromPath, specifier, pathLookup);
+            if (target)
+                push(target, "py-import", specifier);
+        }
+    }
+    for (const node of root.descendantsOfType("import_from_statement")) {
+        const moduleNode = node.childForFieldName("module_name");
+        const moduleSpecifier = moduleNode?.text?.trim();
+        if (!moduleSpecifier)
+            continue;
+        const importedNames = childrenForField(node, "name")
+            .map((nameNode) => importModuleText(nameNode))
+            .filter((name) => Boolean(name));
+        for (const { specifier, target } of resolvePythonFromImportTargets(fromPath, moduleSpecifier, importedNames, pathLookup)) {
+            push(target, "py-from-import", specifier);
+        }
+    }
+}
+/** web-tree-sitter Node#childrenForFieldName, guarded for older runtimes. */
+function childrenForField(node, field) {
+    const fn = node.childrenForFieldName;
+    if (typeof fn === "function") {
+        return fn.call(node, field) ?? [];
+    }
+    const single = node.childForFieldName(field);
+    return single ? [single] : [];
+}
+async function analyze(files, context) {
+    if (files.length === 0)
+        return { edges: [] };
+    const parser = await getTreeSitterParser("python", context.dependencyPath);
+    if (!parser)
+        return { edges: [] };
+    const root = resolve(context.root);
+    const edges = [];
+    for (const file of files) {
+        let content;
+        try {
+            content = await readFile(resolve(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (content.length > MAX_PYTHON_SOURCE_BYTES)
+            continue;
+        try {
+            const tree = parser.parse(content);
+            collectFileEdges(normalizeGraphPath(file), tree.rootNode, context.pathLookup, edges);
+        }
+        catch {
+            // A parse failure on one file degrades to the floor for that file.
+        }
+    }
+    return { edges };
+}
+export const pythonAnalyzer = {
+    id: "python",
+    dependency: "web-tree-sitter",
+    supports,
+    analyze,
+};

package/dist/extractors/analyzers/registry.d.ts

@@ -0,0 +1,33 @@
+import { type AnalyzerSetting } from "@audit-tools/shared";
+import type { AnalyzerPlanEntry, LanguageAnalyzer } from "./types.js";
+/**
+ * Registered language analyzers, in within-phase order (seam → TS/JS →
+ * Python → HTML → CSS). SQL is a registry stub (recognises `.sql`, emits no
+ * edges yet). The tree-sitter analyzers (Python/HTML/CSS) load their grammar
+ * from the optional `web-tree-sitter` dependency and degrade to the regex
+ * floor when it cannot be resolved.
+ */
+export declare const ANALYZER_REGISTRY: LanguageAnalyzer[];
+export declare function getAnalyzerById(id: string): LanguageAnalyzer | undefined;
+/**
+ * Deterministically resolve, without installing anything, how each registered
+ * analyzer would run for this repo. The conversation-first CLI uses this to
+ * decide whether to propose an install before the enrichment executor runs.
+ *
+ * Resolution rules:
+ *  - 0 supported in-scope files            → `not_applicable`
+ *  - setting `skip`                         → `skip`
+ *  - dependency resolves (repo|cache)       → `repo` | `cache`
+ *  - dependency absent                      → `absent` (executor installs only
+ *    for `ephemeral`/`permanent`; `auto` may prompt; `repo` falls to the floor)
+ */
+export declare function resolveAnalyzerPlan(root: string, analyzers: Record<string, AnalyzerSetting> | undefined, includedFiles: string[], options?: {
+    cacheRoot?: string;
+}): AnalyzerPlanEntry[];
+/**
+ * A plan entry whose dependency is absent and whose setting is `auto` (or unset)
+ * with in-scope files — the only case that warrants proposing an install in the
+ * conversation-first flow. (ephemeral/permanent install silently; repo/skip fall
+ * to the floor silently.)
+ */
+export declare function needsInstallDecision(entry: AnalyzerPlanEntry): boolean;

package/dist/extractors/analyzers/registry.js

@@ -0,0 +1,100 @@
+import { resolveAnalyzerDep, } from "@audit-tools/shared";
+import { typescriptAnalyzer } from "./typescript.js";
+import { pythonAnalyzer } from "./python.js";
+import { htmlAnalyzer } from "./html.js";
+import { cssAnalyzer } from "./css.js";
+import { sqlAnalyzer } from "./sql.js";
+/**
+ * Registered language analyzers, in within-phase order (seam → TS/JS →
+ * Python → HTML → CSS). SQL is a registry stub (recognises `.sql`, emits no
+ * edges yet). The tree-sitter analyzers (Python/HTML/CSS) load their grammar
+ * from the optional `web-tree-sitter` dependency and degrade to the regex
+ * floor when it cannot be resolved.
+ */
+export const ANALYZER_REGISTRY = [
+    typescriptAnalyzer,
+    pythonAnalyzer,
+    htmlAnalyzer,
+    cssAnalyzer,
+    sqlAnalyzer,
+];
+export function getAnalyzerById(id) {
+    return ANALYZER_REGISTRY.find((analyzer) => analyzer.id === id);
+}
+function settingFor(analyzers, id) {
+    return analyzers?.[id] ?? "auto";
+}
+/**
+ * Deterministically resolve, without installing anything, how each registered
+ * analyzer would run for this repo. The conversation-first CLI uses this to
+ * decide whether to propose an install before the enrichment executor runs.
+ *
+ * Resolution rules:
+ *  - 0 supported in-scope files            → `not_applicable`
+ *  - setting `skip`                         → `skip`
+ *  - dependency resolves (repo|cache)       → `repo` | `cache`
+ *  - dependency absent                      → `absent` (executor installs only
+ *    for `ephemeral`/`permanent`; `auto` may prompt; `repo` falls to the floor)
+ */
+export function resolveAnalyzerPlan(root, analyzers, includedFiles, options = {}) {
+    const depOptions = options.cacheRoot ? { cacheRoot: options.cacheRoot } : {};
+    return ANALYZER_REGISTRY.map((analyzer) => {
+        const setting = settingFor(analyzers, analyzer.id);
+        const supportedCount = includedFiles.filter((file) => analyzer.supports(file)).length;
+        if (supportedCount === 0) {
+            return {
+                id: analyzer.id,
+                dependency: analyzer.dependency,
+                setting,
+                resolution: "not_applicable",
+                supportedCount,
+            };
+        }
+        if (setting === "skip") {
+            return {
+                id: analyzer.id,
+                dependency: analyzer.dependency,
+                setting,
+                resolution: "skip",
+                supportedCount,
+            };
+        }
+        if (!analyzer.dependency) {
+            // No dependency required: always available.
+            return {
+                id: analyzer.id,
+                dependency: analyzer.dependency,
+                setting,
+                resolution: "repo",
+                supportedCount,
+            };
+        }
+        const resolved = resolveAnalyzerDep(analyzer.dependency, root, depOptions);
+        if (resolved.via === "repo" || resolved.via === "cache") {
+            return {
+                id: analyzer.id,
+                dependency: analyzer.dependency,
+                setting,
+                resolution: resolved.via,
+                path: resolved.path,
+                supportedCount,
+            };
+        }
+        return {
+            id: analyzer.id,
+            dependency: analyzer.dependency,
+            setting,
+            resolution: "absent",
+            supportedCount,
+        };
+    });
+}
+/**
+ * A plan entry whose dependency is absent and whose setting is `auto` (or unset)
+ * with in-scope files — the only case that warrants proposing an install in the
+ * conversation-first flow. (ephemeral/permanent install silently; repo/skip fall
+ * to the floor silently.)
+ */
+export function needsInstallDecision(entry) {
+    return entry.resolution === "absent" && entry.setting === "auto";
+}

package/dist/extractors/analyzers/resourceUrl.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve an HTML/CSS resource reference (script src, link href, @import, url())
+ * to a repo-relative file path, or undefined. Root-relative URLs ("/assets/x")
+ * resolve from the repo root; everything else is relative to the referencing
+ * file. Query strings and fragments are stripped before resolution.
+ */
+export declare function resolveResourceUrl(fromPath: string, url: string, pathLookup: Map<string, string>): string | undefined;

package/dist/extractors/analyzers/resourceUrl.js

@@ -0,0 +1,25 @@
+import { posix } from "node:path";
+import { normalizeGraphPath, resolveCandidate } from "../graphPathUtils.js";
+// Protocol (http:, data:, mailto:, …), protocol-relative (//), and fragment (#)
+// URLs point outside the repository and are never resolved to a local file.
+const EXTERNAL_URL_PATTERN = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+/**
+ * Resolve an HTML/CSS resource reference (script src, link href, @import, url())
+ * to a repo-relative file path, or undefined. Root-relative URLs ("/assets/x")
+ * resolve from the repo root; everything else is relative to the referencing
+ * file. Query strings and fragments are stripped before resolution.
+ */
+export function resolveResourceUrl(fromPath, url, pathLookup) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0 || EXTERNAL_URL_PATTERN.test(trimmed)) {
+        return undefined;
+    }
+    const withoutQuery = trimmed.split(/[?#]/, 1)[0] ?? "";
+    if (withoutQuery.length === 0) {
+        return undefined;
+    }
+    const candidate = withoutQuery.startsWith("/")
+        ? withoutQuery.slice(1)
+        : posix.join(posix.dirname(normalizeGraphPath(fromPath)), withoutQuery);
+    return resolveCandidate(candidate, pathLookup);
+}

package/dist/extractors/analyzers/sql.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageAnalyzer } from "./types.js";
+export declare const sqlAnalyzer: LanguageAnalyzer;

package/dist/extractors/analyzers/sql.js

@@ -0,0 +1,19 @@
+import { normalizeGraphPath } from "../graphPathUtils.js";
+/**
+ * SQL is intentionally a registry stub (per the refactor plan): the seam
+ * recognises `.sql` files but emits no edges yet. Registering it keeps the
+ * capability surface honest — `analyzer_capability.json` records SQL as
+ * applicable-but-empty rather than silently invisible — and leaves a single
+ * place to add cross-file resolution (views/foreign keys) later.
+ */
+function supports(file) {
+    return normalizeGraphPath(file).toLowerCase().endsWith(".sql");
+}
+function analyze() {
+    return { edges: [] };
+}
+export const sqlAnalyzer = {
+    id: "sql",
+    supports,
+    analyze,
+};

package/dist/extractors/analyzers/treeSitter.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared web-tree-sitter loader for the Tier-S parser analyzers (Python / HTML /
+ * CSS). web-tree-sitter is a pure-WASM runtime — no native compilation — so a
+ * grammar parses identically on every platform; grammars ship as `.wasm` files
+ * in `tree-sitter-wasms` (out/tree-sitter-<lang>.wasm).
+ *
+ * Everything here degrades to `undefined` on any failure (missing dependency,
+ * missing grammar, init error) so a caller simply keeps the deterministic regex
+ * floor. The runtime is initialised once and parsed grammars are cached.
+ */
+export interface TsNode {
+    type: string;
+    text: string;
+    namedChildren: TsNode[];
+    childForFieldName(field: string): TsNode | null;
+    descendantsOfType(type: string | string[]): TsNode[];
+}
+export interface TsTree {
+    rootNode: TsNode;
+}
+export interface TsLanguage {
+    __brand?: "tree-sitter-language";
+}
+export interface TsParser {
+    setLanguage(language: TsLanguage): void;
+    parse(source: string): TsTree;
+}
+/**
+ * Obtain a parser bound to `grammar` (e.g. "python", "html", "css"), or
+ * `undefined` if web-tree-sitter or the grammar wasm cannot be loaded.
+ */
+export declare function getTreeSitterParser(grammar: string, dependencyPath?: string): Promise<TsParser | undefined>;
+/** Test seam: reset the memoised runtime/grammar caches. */
+export declare function __resetTreeSitterForTests(): void;