weavatrix 0.1.0

package/src/graph/builder/lang-js.js

@@ -0,0 +1,168 @@
+// JS / TS / JSX / TSX extractor for the built-in graph builder.
+// Symbols: functions, generators, classes, methods, top-level const/let/var (data + arrow/fn consts).
+// Imports: ESM `import`, CJS `require`, path-aliases (tsconfig/vite), and barrel re-exports (`export … from`).
+// Calls: bare `foo()`. Heritage: `class X extends Y`. Everything runs through the shared ctx (see internal-builder.js).
+const CALLABLE = /arrow_function|function|function_expression|generator_function/;
+
+const FUNCS = `
+  (function_declaration name: (identifier) @fn)
+  (generator_function_declaration name: (identifier) @fn)
+  (class_declaration name: (_) @class)
+  (method_definition name: (_) @method)`;
+const TOPVARS = `
+  (program (lexical_declaration (variable_declarator) @decl))
+  (program (variable_declaration (variable_declarator) @decl))
+  (program (export_statement (lexical_declaration (variable_declarator) @decl)))
+  (program (export_statement (variable_declaration (variable_declarator) @decl)))`;
+const REQUIRE = `(variable_declarator name: (_) @lhs value: (call_expression function: (identifier) @req arguments: (arguments (string (string_fragment) @src))))`;
+
+export default {
+  family: "js",
+  grammars: ["javascript", "typescript", "tsx"],
+  exts: { ".js": "javascript", ".jsx": "javascript", ".mjs": "javascript", ".cjs": "javascript", ".ts": "typescript", ".tsx": "tsx" },
+  isWeb: false,
+  calls: `(call_expression function: (identifier) @callee)`,
+  heritage: [`(class_heritage (identifier) @super)`, `(class_heritage (extends_clause value: (identifier) @super))`],
+
+  pass1(ctx) {
+    const { grammar, tree, fileRel, caps, field, addSym, addImportEdge, addExternalImport, markExported, imports, resolveJsImport, resolveAlias } = ctx;
+    // exported-ness of a declaration = an export_statement ancestor (export function/class/const …).
+    // BOUNDED climb: web-tree-sitter's node.parent is O(depth) (re-walks a cursor from the root each call),
+    // so an UNBOUNDED walk to `program` for every symbol was O(depth^3) and HUNG the build for minutes/hours
+    // on deeply-nested / minified / bundled JS (regression). An export_statement is always a NEAR ancestor of
+    // the declaration head (≤ ~5 hops), and hitting a statement_block means we're nested inside a function →
+    // not a module-level export → bail immediately. See [[graph-builder-internalization]].
+    // early-out on statement_block (we're nested inside a function → not a module-level export) keeps this
+    // O(1) for nested symbols; program is the top; the hop cap is the backstop. A method of an EXPORTED class
+    // is only ~4 hops to its export_statement (method → class_body → class_declaration → export_statement),
+    // so we do NOT bail at class_body — that preserves the exported flag for such methods.
+    const isExportedDecl = (node) => {
+      let p = node.parent;
+      for (let hops = 0; p && hops < 6; hops++) {
+        if (p.type === "export_statement") return true;
+        if (p.type === "program" || p.type === "statement_block") return false;
+        p = p.parent;
+      }
+      return false;
+    };
+    // a bare (package) specifier = non-relative AND not a path alias; alias-that-missed is a broken local, not a dep
+    const isBareSpec = (spec) => !!spec && !spec.startsWith(".") && resolveAlias(spec) == null;
+    // broken local import (relative or alias path resolving to no file) — recorded for the "unresolved-import"
+    // finding. Asset imports (svg/css-modules-adjacent/fonts/…) and ?query-suffixed specs that resolve once
+    // the query is stripped (Vite ?raw/?url/?worker) are NOT code-graph concerns.
+    const ASSET_RE = /\.(svg|png|jpe?g|gif|webp|avif|ico|bmp|woff2?|ttf|eot|otf|mp[34]|webm|wasm|pdf|txt|md|html?)$/i;
+    const recordUnresolved = (rawSpec, kind, line) => {
+      const clean = String(rawSpec || "").split("?")[0];
+      if (!clean || ASSET_RE.test(clean)) return;
+      if (clean !== rawSpec && resolveJsImport(fileRel, clean)) return; // only the ?query broke resolution
+      addExternalImport({ spec: rawSpec, kind, line, unresolved: true });
+    };
+
+    // ---- symbols (export flag captured at declaration time) ----
+    for (const cap of caps(grammar, FUNCS, tree.rootNode)) {
+      addSym(cap.node.text, cap.node.startPosition.row + 1, cap.name !== "class", {
+        sourceNode: cap.node.parent,
+        ...(isExportedDecl(cap.node) ? { exported: true } : {})
+      });
+    }
+    for (const cap of caps(grammar, TOPVARS, tree.rootNode)) {
+      const nameNode = field(cap.node, "name"); if (!nameNode || nameNode.type !== "identifier") continue;
+      const val = field(cap.node, "value");
+      addSym(nameNode.text, nameNode.startPosition.row + 1, !!(val && CALLABLE.test(val.type)), {
+        sourceNode: val || cap.node,
+        ...(isExportedDecl(cap.node) ? { exported: true } : {})
+      });
+    }
+
+    // ---- ESM imports ----
+    for (const cap of caps(grammar, `(import_statement) @imp`, tree.rootNode)) {
+      const node = cap.node; const srcNode = field(node, "source");
+      const rawSpec = srcNode ? srcNode.text.replace(/^['"`]|['"`]$/g, "") : "";
+      const tgt = resolveJsImport(fileRel, rawSpec);
+      if (!tgt) {
+        if (isBareSpec(rawSpec)) addExternalImport({ spec: rawSpec, kind: "esm", line: node.startPosition.row + 1 });
+        else if (rawSpec) recordUnresolved(rawSpec, "esm", node.startPosition.row + 1);
+        continue;
+      }
+      addImportEdge(tgt);
+      const clause = node.namedChildren.find((c) => c.type === "import_clause"); if (!clause) continue;
+      for (const c of clause.namedChildren) {
+        if (c.type === "identifier") imports.set(c.text, { imported: "default", targetFile: tgt });
+        else if (c.type === "namespace_import") { const id = c.namedChildren.find((x) => x.type === "identifier"); if (id) imports.set(id.text, { imported: "*", targetFile: tgt }); }
+        else if (c.type === "named_imports") for (const s of c.namedChildren) { if (s.type !== "import_specifier") continue; const nm = field(s, "name"), al = field(s, "alias"); if (nm) imports.set((al || nm).text, { imported: nm.text, targetFile: tgt }); }
+      }
+    }
+
+    // ---- CJS require (declarator form: local bindings + import edges) ----
+    for (const cap of caps(grammar, REQUIRE, tree.rootNode)) {
+      if (cap.name !== "src") continue;
+      let dv = cap.node; while (dv && dv.type !== "variable_declarator") dv = dv.parent;
+      const tgt = resolveJsImport(fileRel, cap.node.text); if (!tgt) continue;
+      addImportEdge(tgt);
+      const lhs = dv && field(dv, "name");
+      if (lhs && lhs.type === "identifier") imports.set(lhs.text, { imported: "*", targetFile: tgt });
+      else if (lhs && lhs.type === "object_pattern") for (const p of lhs.namedChildren) { const key = field(p, "key") || (p.type === "shorthand_property_identifier_pattern" ? p : null); const val = field(p, "value"); const local = (val && val.type === "identifier") ? val : key; if (key && local) imports.set(local.text, { imported: key.text, targetFile: tgt }); }
+    }
+
+    // ---- CJS require, ALL forms (side-effect require("dotenv/config") included): bare-pkg records +
+    // non-literal require(x) → dynamic marker so dep analysis can suppress false "unused" positives ----
+    for (const cap of caps(grammar, `(call_expression function: (identifier) @fn)`, tree.rootNode)) {
+      if (cap.node.text !== "require") continue;
+      const call = cap.node.parent; const args = field(call, "arguments");
+      const arg = args && args.namedChildren ? args.namedChildren[0] : null;
+      const line = call.startPosition.row + 1;
+      if (arg && arg.type === "string") {
+        const rawSpec = arg.text.replace(/^['"`]|['"`]$/g, "");
+        if (resolveJsImport(fileRel, rawSpec)) continue;
+        if (isBareSpec(rawSpec)) addExternalImport({ spec: rawSpec, kind: "cjs", line });
+        else recordUnresolved(rawSpec, "cjs", line);
+      } else {
+        addExternalImport({ dynamic: true, kind: "cjs", line });
+      }
+    }
+
+    // ---- dynamic import(): literal bare → package record; literal local → dynamic marker with target;
+    // non-literal → bare dynamic marker ----
+    for (const cap of caps(grammar, `(call_expression function: (import) @imp)`, tree.rootNode)) {
+      const call = cap.node.parent; const args = field(call, "arguments");
+      const arg = args && args.namedChildren ? args.namedChildren[0] : null;
+      const line = call.startPosition.row + 1;
+      if (arg && arg.type === "string") {
+        const rawSpec = arg.text.replace(/^['"`]|['"`]$/g, "");
+        const tgt = resolveJsImport(fileRel, rawSpec);
+        if (tgt) addExternalImport({ dynamic: true, spec: rawSpec, target: tgt, kind: "dynamic", line });
+        else if (isBareSpec(rawSpec)) addExternalImport({ spec: rawSpec, kind: "dynamic", line });
+        else if (rawSpec) recordUnresolved(rawSpec, "dynamic", line);
+      } else {
+        addExternalImport({ dynamic: true, kind: "dynamic", line });
+      }
+    }
+
+    // ---- re-exports (barrel/index files): edge so the real target isn't falsely DEAD; bare source → external ----
+    for (const cap of caps(grammar, `(export_statement source: (string (string_fragment) @src))`, tree.rootNode)) {
+      if (cap.name !== "src") continue;
+      const rawSpec = cap.node.text;
+      const tgt = resolveJsImport(fileRel, rawSpec);
+      if (tgt) addImportEdge(tgt);
+      else if (isBareSpec(rawSpec)) addExternalImport({ spec: rawSpec, kind: "reexport", line: cap.node.startPosition.row + 1 });
+      else if (rawSpec) recordUnresolved(rawSpec, "reexport", cap.node.startPosition.row + 1);
+    }
+
+    // ---- export markers beyond declarations: `export { a, b }`, `export default X`, CJS module.exports ----
+    for (const cap of caps(grammar, `(export_statement (export_clause (export_specifier name: (identifier) @n)))`, tree.rootNode)) {
+      let st = cap.node.parent; while (st && st.type !== "export_statement") st = st.parent;
+      if (st && !field(st, "source")) markExported(cap.node.text); // with a source it's a re-export, not a local symbol
+    }
+    for (const cap of caps(grammar, `(export_statement value: (identifier) @def)`, tree.rootNode)) markExported(cap.node.text);
+    for (const cap of caps(grammar, `(assignment_expression left: (member_expression) @lhs right: (identifier) @rhs)`, tree.rootNode)) {
+      if (cap.name !== "rhs") continue;
+      const lhs = field(cap.node.parent, "left"); const l = lhs ? lhs.text : "";
+      if (l === "module.exports" || l.startsWith("exports.") || l.startsWith("module.exports.")) markExported(cap.node.text);
+    }
+    for (const cap of caps(grammar, `(assignment_expression left: (member_expression) right: (object (shorthand_property_identifier) @p))`, tree.rootNode)) {
+      let ae = cap.node.parent; while (ae && ae.type !== "assignment_expression") ae = ae.parent;
+      const lhs = ae && field(ae, "left");
+      if (lhs && (lhs.text === "module.exports" || lhs.text.startsWith("exports."))) markExported(cap.node.text);
+    }
+  },
+};

package/src/graph/builder/lang-python.js

@@ -0,0 +1,78 @@
+// Python extractor. Symbols: def/class (methods included) + module-level assignments (data consts).
+// Imports: `import a.b [as c]` and `from [.]*mod import name [as alias]` with dotted + relative (leading-dot)
+// resolution to <path>.py / <path>/__init__.py — tried from the repo root, src/ (src-layout), and the
+// importing file's own directory (script-style sys.path). Absolute imports that resolve to NO repo file
+// are recorded as external imports (stdlib → builtin, else ecosystem "PyPI") for dependency analysis.
+// Calls: bare `foo()`. Heritage: class superclasses.
+import { pySpecToPkg, PY_STDLIB } from "./spec-pkg.js";
+
+export default {
+  family: "py",
+  grammars: ["python"],
+  exts: { ".py": "python", ".pyi": "python" },
+  isWeb: false,
+  calls: `(call function: (identifier) @callee)`,
+  heritage: [`(class_definition superclasses: (argument_list (identifier) @super))`],
+
+  pass1(ctx) {
+    const { grammar, tree, fileRel, caps, field, addSym, addImportEdge, addExternalImport, imports, resolvePyPath, pyBaseDir, pyTopDirs } = ctx;
+    // the importing file's own dir is on sys.path when it runs as a script — try siblings for absolute
+    // imports, EXCEPT stdlib names (a sibling logging.py must not shadow `import logging`; py3 absolute
+    // imports always pick the stdlib, and a wrong internal edge distorts dead-code + reachability)
+    const scriptDir = pyBaseDir(fileRel, 1);
+    const resolveAbs = (parts) => resolvePyPath("", parts) || (scriptDir && !PY_STDLIB.has(parts[0]) ? resolvePyPath(scriptDir, parts) : null);
+    const recordExternal = (dottedName, line) => {
+      const top = String(dottedName).split(".")[0];
+      if (pyTopDirs && pyTopDirs.has(top)) return; // repo-local namespace package (no __init__.py) — internal, not a dep
+      const r = pySpecToPkg(top);
+      if (r && !r.ambiguous) addExternalImport({ spec: dottedName, pkg: r.pkg, builtin: r.builtin, ecosystem: "PyPI", kind: "py-import", line });
+    };
+
+    // ---- symbols (decorated defs are framework-entered — @app.route/@app.event/@pytest.fixture — the
+    // flag keeps dead-code checks from calling them dead; tree wraps them in decorated_definition) ----
+    for (const cap of caps(grammar, `(function_definition name: (identifier) @fn) (class_definition name: (identifier) @class)`, tree.rootNode)) {
+      const decorated = cap.node.parent?.parent?.type === "decorated_definition";
+      addSym(cap.node.text, cap.node.startPosition.row + 1, cap.name === "fn", {
+        sourceNode: cap.node.parent,
+        ...(decorated ? { decorated: true } : {})
+      });
+    }
+    for (const cap of caps(grammar, `(module (expression_statement (assignment left: (identifier) @var)))`, tree.rootNode))
+      addSym(cap.node.text, cap.node.startPosition.row + 1, false, { sourceNode: cap.node.parent });
+
+    // ---- import a.b [as c] ----
+    for (const cap of caps(grammar, `(import_statement) @imp`, tree.rootNode)) {
+      for (const child of cap.node.namedChildren) {
+        const modNode = child.type === "aliased_import" ? field(child, "name") : (child.type === "dotted_name" ? child : null);
+        if (!modNode) continue;
+        const parts = modNode.text.split(".");
+        const tgt = resolveAbs(parts);
+        if (tgt) { addImportEdge(tgt); const local = child.type === "aliased_import" ? field(child, "alias")?.text : parts[0]; if (local) imports.set(local, { imported: "*", targetFile: tgt }); }
+        else recordExternal(modNode.text, modNode.startPosition.row + 1);
+      }
+    }
+
+    // ---- from [.]*mod import name [, name as alias] ----
+    for (const cap of caps(grammar, `(import_from_statement) @imp`, tree.rootNode)) {
+      const node = cap.node; const modNode = field(node, "module_name");
+      let dots = 0, modParts = [];
+      if (modNode) {
+        if (modNode.type === "relative_import") { const t = modNode.text; while (dots < t.length && t[dots] === ".") dots++; const rest = t.slice(dots); modParts = rest ? rest.split(".") : []; }
+        else if (modNode.type === "dotted_name") modParts = modNode.text.split(".");
+      }
+      const baseDir = pyBaseDir(fileRel, dots);
+      const names = node.namedChildren.filter((c) => c !== modNode && (c.type === "dotted_name" || c.type === "aliased_import"));
+      let externalDone = false; // one record per statement, not per imported name
+      for (const nm of names) {
+        const impName = nm.type === "aliased_import" ? field(nm, "name")?.text : nm.text;
+        const local = nm.type === "aliased_import" ? field(nm, "alias")?.text : impName;
+        if (!impName) continue;
+        const asSub = resolvePyPath(baseDir, [...modParts, impName]) || (dots === 0 ? resolveAbs([...modParts, impName]) : null);   // name may itself be a submodule file
+        if (asSub) { addImportEdge(asSub); if (local) imports.set(local, { imported: "*", targetFile: asSub }); continue; }
+        const modFile = resolvePyPath(baseDir, modParts) || (dots === 0 ? resolveAbs(modParts) : null);
+        if (modFile) { addImportEdge(modFile); if (local) imports.set(local, { imported: impName, targetFile: modFile }); }
+        else if (dots === 0 && modParts.length && !externalDone) { externalDone = true; recordExternal(modParts.join("."), node.startPosition.row + 1); }
+      }
+    }
+  },
+};

package/src/graph/builder/lang-rust.js

@@ -0,0 +1,45 @@
+// Rust extractor. Symbols: fn (incl. impl methods) + struct/enum/trait/type/mod + const/static
+// (+ macro_rules!/union via optional queries). Calls: `foo()` / `x.foo()` / `path::foo()` (name only).
+// Heritage: `impl Trait for Type` resolves only when the impl block sits inside a tracked symbol
+// (e.g. a mod) — a top-level impl has no enclosing symbol to anchor the edge, so v1 usually skips it.
+// `use` paths map to files only through the crate's module tree, which needs Cargo layout resolution —
+// no import edges in v1; cross-file connectivity comes from the name-based calls pass plus the
+// same-folder scope (mod.rs convention).
+const SYMS_CORE = `
+  (function_item name: (identifier) @method)
+  (struct_item name: (type_identifier) @class)
+  (enum_item name: (type_identifier) @class)
+  (trait_item name: (type_identifier) @class)
+  (type_item name: (type_identifier) @class)
+  (mod_item name: (identifier) @class)
+  (const_item name: (identifier) @field)
+  (static_item name: (identifier) @field)`;
+// Grammar-version-dependent node types, compiled SEPARATELY (one unknown type voids its whole query).
+const SYMS_OPTIONAL = [
+  `(macro_definition name: (identifier) @method)`,
+  `(union_item name: (type_identifier) @class)`,
+];
+
+export default {
+  family: "rust",
+  grammars: ["rust"],
+  exts: { ".rs": "rust" },
+  isWeb: false,
+  calls: `
+    (call_expression function: (identifier) @callee)
+    (call_expression function: (field_expression field: (field_identifier) @callee))
+    (call_expression function: (scoped_identifier name: (identifier) @callee))`,
+  heritage: [
+    `(impl_item trait: (type_identifier) @super)`,
+    `(impl_item trait: (generic_type type: (type_identifier) @super))`,
+  ],
+
+  pass1(ctx) {
+    const { grammar, tree, caps, addSym } = ctx;
+    for (const src of [SYMS_CORE, ...SYMS_OPTIONAL]) {
+      for (const cap of caps(grammar, src, tree.rootNode)) {
+        addSym(cap.node.text, cap.node.startPosition.row + 1, cap.name === "method", { sourceNode: cap.node.parent });
+      }
+    }
+  },
+};

package/src/graph/builder/spec-pkg.js

@@ -0,0 +1,87 @@
+// specToPkg(spec) — map an import specifier to its npm package name, a Node builtin, or null for
+// relative/absolute/URL specifiers. The core primitive for dependency analysis (unused/missing deps):
+// "axios/lib/core" → axios, "@scope/name/sub" → @scope/name, "node:fs/promises" + "fs/promises" → fs
+// (builtin), "./x" → null. See DEPS_SECURITY_PLAN.md (P0).
+
+// Builtins importable WITHOUT the node: prefix. Prefix-only builtins (node:test, node:sea, node:sqlite)
+// are deliberately NOT here — bare "test" is a legitimate npm package name; node:-prefixed specifiers
+// are always classified builtin regardless of this set.
+export const NODE_BUILTINS = new Set([
+  "assert", "async_hooks", "buffer", "child_process", "cluster", "console", "constants", "crypto",
+  "dgram", "diagnostics_channel", "dns", "domain", "events", "fs", "http", "http2", "https", "inspector",
+  "module", "net", "os", "path", "perf_hooks", "process", "punycode", "querystring", "readline", "repl",
+  "stream", "string_decoder", "sys", "timers", "tls", "trace_events", "tty", "url", "util", "v8", "vm",
+  "wasi", "worker_threads", "zlib",
+]);
+
+export function specToPkg(spec) {
+  const s = String(spec || "").trim();
+  if (!s || s.startsWith(".") || s.startsWith("/") || /^[A-Za-z]:[\\/]/.test(s)) return null; // relative/absolute/local
+  if (s.startsWith("#")) return null; // package.json "imports" subpath (self-internal), not a dependency
+  if (/^(https?|data|file):/.test(s)) return null; // URL-style imports aren't manifest deps
+  if (s.startsWith("node:")) return { pkg: s.slice(5).split("/")[0], builtin: true };
+  if (s === "bun" || s.startsWith("bun:")) return { pkg: s, builtin: true }; // Bun runtime modules (bun:test, bun:sqlite) — never npm deps
+  if (s.startsWith("npm:")) return specToPkg(s.slice(4)); // Deno/import-map npm: specifiers alias real npm packages
+  if (/^[a-z][\w+.-]*:/.test(s)) return null; // other scheme-style specifiers (jsr:, deno:, virtual:, …) aren't manifest deps
+  const parts = s.split("/");
+  const pkg = s.startsWith("@") ? (parts.length >= 2 ? `${parts[0]}/${parts[1]}` : s) : parts[0];
+  if (NODE_BUILTINS.has(pkg)) return { pkg, builtin: true };
+  return { pkg, builtin: false };
+}
+
+// ---- Go: import path → module (declared in go.mod) or stdlib. Stdlib packages have a dotless first
+// segment (fmt, net/http, encoding/json — and cgo's "C"); everything else is a module path. Prefer the
+// longest go.mod require prefix (exact module identity); fall back to a host-convention guess so
+// MISSING modules still get a sane name (github.com/owner/repo, gopkg.in/pkg.v3, k8s.io/client-go).
+const GO_DEEP_HOSTS = new Set(["github.com", "gitlab.com", "bitbucket.org", "golang.org", "go.googlesource.com"]);
+export function goSpecToPkg(importPath, { requires = [], ownModule = "" } = {}) {
+  const s = String(importPath || "").trim();
+  if (!s) return null;
+  const segs = s.split("/");
+  if (!segs[0].includes(".")) return { pkg: s, builtin: true }; // stdlib + "C"
+  if (ownModule && (s === ownModule || s.startsWith(ownModule + "/"))) return null; // own module → internal (broken path, not a dep)
+  let best = "";
+  for (const r of requires) { const p = typeof r === "string" ? r : r.path; if ((s === p || s.startsWith(p + "/")) && p.length > best.length) best = p; }
+  if (best) return { pkg: best, builtin: false };
+  let n = GO_DEEP_HOSTS.has(segs[0]) ? 3 : 2;
+  if (segs[0] === "gopkg.in") n = /\.v\d+$/.test(segs[1] || "") ? 2 : 3;
+  return { pkg: segs.slice(0, Math.min(n, segs.length)).join("/"), builtin: false };
+}
+
+// ---- Python: top-level imported module → PyPI distribution (or stdlib). PY_STDLIB ≈ CPython 3.12
+// sys.stdlib_module_names (public names) + legacy stalwarts, so old codebases classify cleanly too.
+export const PY_STDLIB = new Set(("__future__ __main__ _thread abc aifc argparse array ast asyncio atexit audioop base64 bdb binascii bisect builtins bz2 " +
+  "calendar cgi cgitb chunk cmath cmd code codecs codeop collections colorsys compileall concurrent configparser contextlib contextvars copy copyreg cProfile crypt csv ctypes curses " +
+  "dataclasses datetime dbm decimal difflib dis distutils doctest email encodings ensurepip enum errno faulthandler fcntl filecmp fileinput fnmatch fractions ftplib functools " +
+  "gc getopt getpass gettext glob graphlib grp gzip hashlib heapq hmac html http imaplib imghdr imp importlib inspect io ipaddress itertools json keyword " +
+  "linecache locale logging lzma mailbox mailcap marshal math mimetypes mmap modulefinder msilib msvcrt multiprocessing netrc nntplib ntpath numbers " +
+  "operator optparse os ossaudiodev pathlib pdb pickle pickletools pipes pkgutil platform plistlib poplib posixpath pprint profile pstats pty pwd py_compile pyclbr pydoc queue quopri " +
+  "random re readline reprlib resource rlcompleter runpy sched secrets select selectors shelve shlex shutil signal site smtplib sndhdr socket socketserver spwd sqlite3 ssl stat statistics " +
+  "sre_compile sre_constants sre_parse string stringprep struct subprocess sunau symtable sys sysconfig syslog tabnanny tarfile telnetlib tempfile termios textwrap threading time timeit tkinter token tokenize tomllib " +
+  "trace traceback tracemalloc tty turtle types typing unicodedata unittest urllib uu uuid venv warnings wave weakref webbrowser winreg winsound wsgiref xdrlib xml xmlrpc zipapp zipfile zipimport zlib zoneinfo").split(" "));
+
+// import name → PyPI dist where they differ. Generic python-X / X-python / X[2]-binary equivalence is
+// handled by the matcher in dep-check; this map covers the truly irregular names.
+export const PY_IMPORT_TO_DIST = {
+  yaml: "PyYAML", cv2: "opencv-python", PIL: "Pillow", sklearn: "scikit-learn", skimage: "scikit-image",
+  bs4: "beautifulsoup4", dateutil: "python-dateutil", dotenv: "python-dotenv", jose: "python-jose",
+  magic: "python-magic", multipart: "python-multipart", docx: "python-docx", pptx: "python-pptx",
+  fitz: "PyMuPDF", OpenSSL: "pyOpenSSL", Crypto: "pycryptodome", nacl: "PyNaCl", jwt: "PyJWT",
+  MySQLdb: "mysqlclient", attr: "attrs", attrs: "attrs", git: "GitPython", github: "PyGithub",
+  kafka: "kafka-python", grpc: "grpcio", serial: "pyserial", usb: "pyusb", zmq: "pyzmq",
+  websocket: "websocket-client", socks: "PySocks", telegram: "python-telegram-bot",
+  speech_recognition: "SpeechRecognition", wx: "wxPython", cairo: "pycairo", gi: "PyGObject",
+  mpl_toolkits: "matplotlib", pkg_resources: "setuptools", Levenshtein: "python-Levenshtein",
+  ldap: "python-ldap", memcache: "python-memcached", slugify: "python-slugify", decouple: "python-decouple",
+  engineio: "python-engineio", socketio: "python-socketio", ruamel: "ruamel.yaml", flask: "Flask",
+  win32api: "pywin32", win32com: "pywin32", win32con: "pywin32", win32gui: "pywin32", pythoncom: "pywin32", pywintypes: "pywin32",
+};
+// namespace roots shared by many dists (google.protobuf/google.cloud.* …) — too ambiguous to name one
+// package; "src" is a repo-layout artifact (stale sys.path import), never a PyPI dist.
+export const PY_AMBIGUOUS_TOP = new Set(["google", "src"]);
+export function pySpecToPkg(topModule) {
+  const t = String(topModule || "").trim();
+  if (!t) return null;
+  if (PY_STDLIB.has(t)) return { pkg: t, builtin: true };
+  return { pkg: PY_IMPORT_TO_DIST[t] || t, builtin: false, ambiguous: PY_AMBIGUOUS_TOP.has(t) };
+}

package/src/graph/graph-filter.js

@@ -0,0 +1,44 @@
+// Pure graph filters applied to a built graph.json (no I/O). graph-builder itself has no test/scope
+// filter, so we post-process the graph object: drop test nodes, keep only a subpath, etc.
+
+export function isTestPath(path) {
+  return /(^|[\\/])(__tests?__|tests?)([\\/]|$)|\.(test|itest|spec|e2e)\.|_test\.go$|(^|[\\/])test_[^\\/]*\.py$/i.test(String(path || ""));
+}
+
+// Filter a built graph.json by test-mode: drop test nodes ("no-tests") or keep only tests + the
+// nodes they depend on ("tests-only"). graph-builder update has no test filter, so we do it post-build.
+export function filterGraphForMode(graph, mode) {
+  if (mode !== "no-tests" && mode !== "tests-only") return graph;
+  const nodes = graph.nodes || [];
+  const links = graph.links || [];
+  const endpoint = (value) => (value && typeof value === "object" ? value.id : value);
+  let keep;
+  if (mode === "no-tests") {
+    keep = new Set(nodes.filter((node) => !isTestPath(node.source_file)).map((node) => node.id));
+  } else {
+    const testIds = new Set(nodes.filter((node) => isTestPath(node.source_file)).map((node) => node.id));
+    keep = new Set(testIds);
+    for (const link of links) {
+      if (testIds.has(endpoint(link.source))) keep.add(endpoint(link.target)); // a test's dependency
+    }
+  }
+  return {
+    ...graph,
+    nodes: nodes.filter((node) => keep.has(node.id)),
+    links: links.filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target)))
+  };
+}
+
+// Keep only nodes under a subpath (path-scope), drop links touching removed nodes.
+export function filterGraphByScope(graph, scope) {
+  if (!scope) return graph;
+  const norm = (p) => String(p || "").replace(/\\/g, "/");
+  const prefix = norm(scope).replace(/\/+$/, "") + "/";
+  const endpoint = (value) => (value && typeof value === "object" ? value.id : value);
+  const keep = new Set((graph.nodes || []).filter((node) => (norm(node.source_file) + "/").startsWith(prefix)).map((node) => node.id));
+  return {
+    ...graph,
+    nodes: (graph.nodes || []).filter((node) => keep.has(node.id)),
+    links: (graph.links || []).filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target)))
+  };
+}