@4da/mcp-server 6.0.2 → 6.2.0

package/dist/tools/project-scope.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which project a planning or briefing answer is about.
+ *
+ * Measured 2026-10-07: upgrade_planner called from D:\4DA returned the 4DA
+ * app's cross-project plan, and its top steps were for navcal, verax and
+ * 4da-ledger. upgrade_planner and what_should_i_know now take `project_path`:
+ * omitted, it is the project the server was started for (FOURDA_PROJECT_DIR,
+ * else the working directory) when that directory is a project; `"*"` asks
+ * for every project.
+ */
+import type { FourDADatabase } from "../db.js";
+import { LiveIntelligence } from "../live/index.js";
+export declare const ALL_PROJECTS = "*";
+/** The project the server was started for: FOURDA_PROJECT_DIR (an unsubstituted "${...}" template is ignored), else cwd. */
+export declare function serverProjectDir(): string;
+/** True when `dir` holds a manifest or lockfile of a supported ecosystem. */
+export declare function isProjectDir(dir: string): boolean;
+/** Lowercased, forward slashes, no trailing slash: the form the app's plan stores project paths in. */
+export declare function normalizeProjectPath(p: string): string;
+/** True when `candidate` is `root` or inside it. */
+export declare function isWithin(candidate: string, root: string): boolean;
+export type ProjectScope = {
+    kind: "project";
+    path: string;
+    source: "argument" | "server_project";
+} | {
+    kind: "all";
+    reason: string;
+} | {
+    kind: "error";
+    error: string;
+};
+/**
+ * The scope for one call. An explicit path must be a directory on this
+ * machine; `"*"` is every project; omitted, the server's project when it is
+ * one, otherwise every project (a server started in a home directory has no
+ * project to narrow to).
+ */
+export declare function resolveProjectScope(projectPath: string | undefined): ProjectScope;
+/**
+ * The live layer for `scope`: the server's own when it already covers that
+ * root, otherwise a fresh one resolved from the project tree at that path (as
+ * vulnerability_scan does for its `project_path`).
+ */
+export declare function liveIntelFor<T extends Pick<LiveIntelligence, "getProjectRoot">>(liveIntel: T | null, db: FourDADatabase | null, scope: ProjectScope): T | LiveIntelligence | null;

package/dist/tools/project-scope.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Which project a planning or briefing answer is about.
+ *
+ * Measured 2026-10-07: upgrade_planner called from D:\4DA returned the 4DA
+ * app's cross-project plan, and its top steps were for navcal, verax and
+ * 4da-ledger. upgrade_planner and what_should_i_know now take `project_path`:
+ * omitted, it is the project the server was started for (FOURDA_PROJECT_DIR,
+ * else the working directory) when that directory is a project; `"*"` asks
+ * for every project.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getServerCacheDb } from "../live/cache.js";
+import { LiveIntelligence } from "../live/index.js";
+import { scanProjectTree, treeResolutionGroups } from "../project-tree.js";
+/** Files that make a directory a project (manifests and lockfiles of the supported ecosystems). */
+const PROJECT_MARKERS = [
+    "package.json",
+    "Cargo.toml",
+    "pyproject.toml",
+    "setup.py",
+    "requirements.txt",
+    "Pipfile",
+    "go.mod",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "bun.lock",
+    "Cargo.lock",
+    "poetry.lock",
+    "uv.lock",
+];
+export const ALL_PROJECTS = "*";
+/** The project the server was started for: FOURDA_PROJECT_DIR (an unsubstituted "${...}" template is ignored), else cwd. */
+export function serverProjectDir() {
+    const dir = process.env.FOURDA_PROJECT_DIR?.trim();
+    if (dir && !dir.includes("${"))
+        return dir;
+    return process.cwd();
+}
+/** True when `dir` holds a manifest or lockfile of a supported ecosystem. */
+export function isProjectDir(dir) {
+    return PROJECT_MARKERS.some((m) => {
+        try {
+            return fs.statSync(path.join(dir, m)).isFile();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Lowercased, forward slashes, no trailing slash: the form the app's plan stores project paths in. */
+export function normalizeProjectPath(p) {
+    return path.resolve(p).replace(/\\/g, "/").toLowerCase().replace(/\/+$/, "");
+}
+/** True when `candidate` is `root` or inside it. */
+export function isWithin(candidate, root) {
+    const c = normalizeProjectPath(candidate);
+    const r = normalizeProjectPath(root);
+    return c === r || c.startsWith(`${r}/`);
+}
+/**
+ * The scope for one call. An explicit path must be a directory on this
+ * machine; `"*"` is every project; omitted, the server's project when it is
+ * one, otherwise every project (a server started in a home directory has no
+ * project to narrow to).
+ */
+export function resolveProjectScope(projectPath) {
+    const given = projectPath?.trim();
+    if (given === ALL_PROJECTS)
+        return { kind: "all", reason: 'project_path "*" asks for every project' };
+    if (given) {
+        const abs = path.resolve(given);
+        let isDir = false;
+        try {
+            isDir = fs.statSync(abs).isDirectory();
+        }
+        catch {
+            isDir = false;
+        }
+        if (!isDir) {
+            return {
+                kind: "error",
+                error: `project_path "${given}" is not a directory on this machine. Pass the absolute path of a project root, "*" for every project, or omit it for ${serverProjectDir()}.`,
+            };
+        }
+        return { kind: "project", path: abs, source: "argument" };
+    }
+    const own = serverProjectDir();
+    if (isProjectDir(own))
+        return { kind: "project", path: path.resolve(own), source: "server_project" };
+    return { kind: "all", reason: `the server's directory ${own} is not a project (no manifest or lockfile)` };
+}
+/**
+ * The live layer for `scope`: the server's own when it already covers that
+ * root, otherwise a fresh one resolved from the project tree at that path (as
+ * vulnerability_scan does for its `project_path`).
+ */
+export function liveIntelFor(liveIntel, db, scope) {
+    if (scope.kind !== "project" || !liveIntel)
+        return liveIntel;
+    const root = liveIntel.getProjectRoot();
+    if (root && normalizeProjectPath(root) === normalizeProjectPath(scope.path))
+        return liveIntel;
+    // A scope the server did not start for: resolve that tree. The connection
+    // is only used for its cache (LiveCache never writes to the app's database).
+    let raw;
+    try {
+        raw = db?.getRawDb();
+    }
+    catch {
+        raw = undefined;
+    }
+    const scoped = new LiveIntelligence(raw ?? getServerCacheDb());
+    const { entries, discovery } = scanProjectTree(scope.path);
+    scoped.initFromProjectTree(scope.path, treeResolutionGroups(entries), discovery);
+    return scoped;
+}

package/dist/tools/record-feedback.js

@@ -17,7 +17,7 @@ Feedback actions:
 - "dismiss": User dismissed the item
 - "mark_irrelevant": User said the item is not relevant (also records a relevance label)
 
-Only "save" and "mark_irrelevant" are relevance labels; they are what 4DA's accuracy measurement reads. Use them only when the user actually says whether the item matters to them. This does not train content preferences.`,
+Only "save" and "mark_irrelevant" are relevance labels. Use them only when the user actually says whether the item matters to them. This does not train content preferences. Recorded in the 4DA desktop app's own interactions/feedback tables.`,
     inputSchema: {
         type: "object",
         properties: {

package/dist/tools/upgrade-impact-callsites.d.ts

@@ -39,6 +39,7 @@ export declare function scanRustSource(source: string, crateName: string, symbol
 export declare function scanCallSites(root: string, pkg: string, ecosystem: UpgradeEcosystem, opts?: {
     timeBudgetMs?: number;
     concurrency?: number;
+    importNames?: string[];
 }): Promise<CallSiteReport>;
 /**
  * Symbols (≥ 3 chars) that `text` names at a word boundary, case-sensitively.

package/dist/tools/upgrade-impact-callsites.js

@@ -18,12 +18,16 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { IgnoreRules } from "../gitignore.js";
+import { scanGoSource, scanPythonSource } from "./upgrade-impact-imports.js";
 const SKIP_DIRS = new Set([
     "node_modules", "target", ".git", "dist", "build", "out", ".next",
-    "coverage", "vendor", ".claude", ".venv",
+    "coverage", "vendor", ".claude", ".venv", "venv", "__pycache__", "site-packages",
 ]);
 const NPM_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte"]);
 const RUST_EXTS = new Set([".rs"]);
+const PY_EXTS = new Set([".py", ".pyi"]);
+const GO_EXTS = new Set([".go"]);
+const EXTS = { npm: NPM_EXTS, "crates.io": RUST_EXTS, PyPI: PY_EXTS, Go: GO_EXTS };
 const MAX_FILES = 6000;
 const MAX_FILE_BYTES = 1024 * 1024;
 const MAX_REPORTED_FILES = 50;
@@ -157,11 +161,25 @@ function listSources(root, exts, budget) {
  * all, and a scan that runs out of time says its counts are lower bounds.
  */
 export async function scanCallSites(root, pkg, ecosystem, opts = {}) {
-    const exts = ecosystem === "npm" ? NPM_EXTS : RUST_EXTS;
+    const exts = EXTS[ecosystem];
     const budget = { left: MAX_FILES };
     const symbols = new Set();
     const hits = [];
-    const needle = ecosystem === "npm" ? pkg : pkg.replace(/-/g, "_");
+    // PyPI: the module names the distribution is imported as (upgrade-impact-imports.ts).
+    const importNames = opts.importNames ?? [pkg];
+    const needles = ecosystem === "PyPI" ? importNames : [ecosystem === "crates.io" ? pkg.replace(/-/g, "_") : pkg];
+    const scan = (source) => {
+        switch (ecosystem) {
+            case "npm":
+                return scanNpmSource(source, pkg, symbols);
+            case "crates.io":
+                return scanRustSource(source, pkg, symbols);
+            case "PyPI":
+                return scanPythonSource(source, importNames, symbols);
+            case "Go":
+                return scanGoSource(source, pkg, symbols);
+        }
+    };
     const deadline = Date.now() + (opts.timeBudgetMs ?? CALLSITE_TIME_BUDGET_MS);
     const files = listSources(root, exts, budget);
     let next = 0;
@@ -183,9 +201,9 @@ export async function scanCallSites(root, pkg, ecosystem, opts = {}) {
             catch {
                 continue;
             }
-            if (!source.includes(needle))
+            if (!needles.some((n) => source.includes(n)))
                 continue;
-            const matches = ecosystem === "npm" ? scanNpmSource(source, pkg, symbols) : scanRustSource(source, pkg, symbols);
+            const matches = scan(source);
             if (matches > 0)
                 hits.push({ path: path.relative(root, file).split(path.sep).join("/"), matches });
         }

package/dist/tools/upgrade-impact-changelog.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Which changelog `upgrade_impact` reports, and what it says when there is none.
+ *
+ * Order: the changelog inside the target version's registry archive (always;
+ * Decision 1 option A), then, only when the user opted in with
+ * FOURDA_GITHUB_CHANGELOG and the archive does not cover the range, the
+ * GitHub fallback (a changelog file the project links, then its releases;
+ * Decision 1 option B). The GitHub result replaces the archive's only when it
+ * covers the range or has more of its releases.
+ *
+ * With the fallback off and no usable changelog, the answer says the
+ * changelog is unavailable and exactly how to enable the fallback, or that
+ * enabling it would not help (no GitHub repository). It never fills the gap
+ * with a guess.
+ */
+import { type ChangelogSection, type VersionOrder } from "../live/changelog.js";
+import { type ChangelogResult, type PublishedVersion, type RegistryIndex, type UpgradeNet } from "../live/upgrade-sources.js";
+export interface ResolvedChangelog {
+    changelog: ChangelogResult;
+    range: {
+        sections: ChangelogSection[];
+        coversRange: boolean;
+    };
+    /** Present when the archive did not cover the range: what the fallback did, or how to turn it on. */
+    github_fallback?: Record<string, unknown>;
+}
+export interface ChangelogRequest {
+    net: UpgradeNet;
+    index: RegistryIndex;
+    target: PublishedVersion;
+    from: string;
+    to: string;
+    firstInRange: string;
+    order: VersionOrder;
+    githubEnabled: boolean;
+    /** Repository to read releases from (Go: the proxy's VCS origin when known). */
+    repository: string | null;
+    /** Go: the module's tag prefix in its repository. */
+    tagPrefix?: string | null;
+}
+export declare function resolveChangelog(req: ChangelogRequest): Promise<ResolvedChangelog>;

package/dist/tools/upgrade-impact-changelog.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Which changelog `upgrade_impact` reports, and what it says when there is none.
+ *
+ * Order: the changelog inside the target version's registry archive (always;
+ * Decision 1 option A), then, only when the user opted in with
+ * FOURDA_GITHUB_CHANGELOG and the archive does not cover the range, the
+ * GitHub fallback (a changelog file the project links, then its releases;
+ * Decision 1 option B). The GitHub result replaces the archive's only when it
+ * covers the range or has more of its releases.
+ *
+ * With the fallback off and no usable changelog, the answer says the
+ * changelog is unavailable and exactly how to enable the fallback, or that
+ * enabling it would not help (no GitHub repository). It never fills the gap
+ * with a guess.
+ */
+import { selectRange } from "../live/changelog.js";
+import { GITHUB_CHANGELOG_ENV, getGithubChangelog, parseGithubRepo } from "../live/github-releases.js";
+import { getChangelog } from "../live/upgrade-sources.js";
+function rangeOf(result, req) {
+    return result.found && result.sections
+        ? selectRange(result.sections, req.from, req.to, req.firstInRange, req.order)
+        : { sections: [], coversRange: false };
+}
+export async function resolveChangelog(req) {
+    const archive = await getChangelog(req.net, req.index, req.target);
+    const archiveRange = rangeOf(archive, req);
+    if (archiveRange.coversRange)
+        return { changelog: archive, range: archiveRange };
+    const repo = parseGithubRepo(req.repository);
+    const pyLinks = (req.index.changelogLinks ?? []).filter((l) => /^https:\/\/(?:github\.com|raw\.githubusercontent\.com)\//i.test(l));
+    const archiveState = !archive.found
+        ? archive.reason ?? "no changelog in the archive"
+        : archiveRange.sections.length === 0
+            ? `${archive.file} has no section for these releases`
+            : `${archive.file} covers only part of the range`;
+    if (!req.githubEnabled) {
+        const where = repo ? `github.com/${repo.owner}/${repo.repo}` : null;
+        return {
+            changelog: archive,
+            range: archiveRange,
+            github_fallback: where || pyLinks.length > 0
+                ? {
+                    enabled: false,
+                    how_to_enable: `Set ${GITHUB_CHANGELOG_ENV}=true in this MCP server's environment to read the release notes ${where ? `on ${where}` : "the project links on GitHub"} when the archive has none. GitHub then receives the repository name and the version range only; GITHUB_TOKEN, if set, raises its rate limit.`,
+                }
+                : {
+                    enabled: false,
+                    note: `The package names no GitHub repository, so ${GITHUB_CHANGELOG_ENV} would not find release notes either; see release_notes_url.`,
+                },
+        };
+    }
+    const gh = await getGithubChangelog(req.net, {
+        pkg: req.index.name,
+        ecosystem: req.index.ecosystem,
+        repository: req.repository,
+        changelogLinks: req.index.changelogLinks,
+        from: req.from,
+        to: req.to,
+        tagPrefix: req.tagPrefix ?? null,
+        order: req.order,
+    });
+    if (!gh.found) {
+        return { changelog: archive, range: archiveRange, github_fallback: { enabled: true, used: false, reason: gh.reason } };
+    }
+    const ghRange = rangeOf(gh, req);
+    if (ghRange.coversRange || ghRange.sections.length > archiveRange.sections.length) {
+        return {
+            changelog: gh,
+            range: ghRange,
+            github_fallback: { enabled: true, used: true, source: gh.source, url: gh.url, archive: archiveState },
+        };
+    }
+    return {
+        changelog: archive,
+        range: archiveRange,
+        github_fallback: { enabled: true, used: false, reason: "the GitHub release notes cover no more of the range than the archive's changelog" },
+    };
+}

package/dist/tools/upgrade-impact-imports.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Python and Go import sites for `upgrade_impact`.
+ *
+ * Go is exact: a file imports a module by its path (`"github.com/jackc/pgx/v5"`
+ * or a package below it), and the identifiers it reaches through the package
+ * name (`pgx.Connect`) are the symbols a changelog entry can name.
+ *
+ * Python is not: a file imports a MODULE (`import yaml`), while an upgrade names
+ * a DISTRIBUTION (`PyYAML`), and nothing in the source links the two. The
+ * mapping comes, in order of trust, from:
+ *   1. the installed distribution's own metadata in this project's virtualenv
+ *      (`*.dist-info/top_level.txt`, else the top-level names in `RECORD`);
+ *   2. a short table of well-known distributions whose import name differs
+ *      (beautifulsoup4 -> bs4, Pillow -> PIL, PyYAML -> yaml, ...);
+ *   3. the distribution name itself with `-` and `.` read as `_`, which is
+ *      right for most packages and is reported as an ASSUMPTION every time,
+ *      so a count of zero files is never mistaken for "not used".
+ */
+export type ImportNameSource = "installed-metadata" | "known-mapping" | "assumed";
+export interface PythonImportNames {
+    names: string[];
+    source: ImportNameSource;
+    /** Where the installed metadata was read, relative to the project root. */
+    evidence?: string;
+}
+/** The module name(s) a distribution is imported as, and how that was established. */
+export declare function pythonImportNames(root: string | null, dist: string): PythonImportNames;
+/**
+ * Count imports of any of `names` in one Python file and collect the names it
+ * reaches: `from x import A, B` gives A and B; `import x` / `import x as y`
+ * gives the attributes used as `x.attr` / `y.attr`.
+ */
+export declare function scanPythonSource(source: string, names: string[], symbols: Set<string>): number;
+/** True when import path `imp` is module `mod` or a package inside it, not a different major (`mod/v2`). */
+export declare function goImportInModule(imp: string, mod: string): boolean;
+/** The package name an import path is used through: its last element, skipping a `/vN` suffix and gopkg.in's `.vN`. */
+export declare function goPackageName(imp: string): string;
+/**
+ * Count imports of a Go module (or packages inside it) in one file and collect
+ * the exported identifiers reached through each import's package name.
+ */
+export declare function scanGoSource(source: string, mod: string, symbols: Set<string>): number;

package/dist/tools/upgrade-impact-imports.js

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Python and Go import sites for `upgrade_impact`.
+ *
+ * Go is exact: a file imports a module by its path (`"github.com/jackc/pgx/v5"`
+ * or a package below it), and the identifiers it reaches through the package
+ * name (`pgx.Connect`) are the symbols a changelog entry can name.
+ *
+ * Python is not: a file imports a MODULE (`import yaml`), while an upgrade names
+ * a DISTRIBUTION (`PyYAML`), and nothing in the source links the two. The
+ * mapping comes, in order of trust, from:
+ *   1. the installed distribution's own metadata in this project's virtualenv
+ *      (`*.dist-info/top_level.txt`, else the top-level names in `RECORD`);
+ *   2. a short table of well-known distributions whose import name differs
+ *      (beautifulsoup4 -> bs4, Pillow -> PIL, PyYAML -> yaml, ...);
+ *   3. the distribution name itself with `-` and `.` read as `_`, which is
+ *      right for most packages and is reported as an ASSUMPTION every time,
+ *      so a count of zero files is never mistaken for "not used".
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { normalizePypiName } from "../live/upgrade-pypi.js";
+import { goBasePath, goPathMajor } from "../live/upgrade-go.js";
+/**
+ * Distributions whose import name is not their normalised name. Each is the
+ * package's documented import (PyPI page or the project's own docs); a
+ * distribution that installs several top-level modules lists them all.
+ */
+const KNOWN_IMPORT_NAMES = {
+    "beautifulsoup4": ["bs4"],
+    "pillow": ["PIL"],
+    "pyyaml": ["yaml"],
+    "scikit-learn": ["sklearn"],
+    "scikit-image": ["skimage"],
+    "opencv-python": ["cv2"],
+    "opencv-python-headless": ["cv2"],
+    "opencv-contrib-python": ["cv2"],
+    "opencv-contrib-python-headless": ["cv2"],
+    "python-dateutil": ["dateutil"],
+    "pyjwt": ["jwt"],
+    "python-dotenv": ["dotenv"],
+    "protobuf": ["google.protobuf"],
+    "attrs": ["attr", "attrs"],
+    "psycopg2-binary": ["psycopg2"],
+    "mysqlclient": ["MySQLdb"],
+    "pyserial": ["serial"],
+    "pyopenssl": ["OpenSSL"],
+    "pycryptodome": ["Crypto"],
+    "pycryptodomex": ["Cryptodome"],
+    "setuptools": ["setuptools", "pkg_resources"],
+    "python-multipart": ["multipart", "python_multipart"],
+    "djangorestframework": ["rest_framework"],
+    "django-cors-headers": ["corsheaders"],
+    "python-jose": ["jose"],
+    "ruamel.yaml": ["ruamel.yaml"],
+    "grpcio": ["grpc"],
+    "google-api-python-client": ["googleapiclient"],
+    "pymupdf": ["fitz", "pymupdf"],
+    "python-docx": ["docx"],
+    "python-pptx": ["pptx"],
+    "websocket-client": ["websocket"],
+    "pyzmq": ["zmq"],
+    "faiss-cpu": ["faiss"],
+    "faiss-gpu": ["faiss"],
+    "discord.py": ["discord"],
+    "py-cpuinfo": ["cpuinfo"],
+    "pygobject": ["gi"],
+    "pycairo": ["cairo"],
+    "pyqt5": ["PyQt5"],
+    "pyqt6": ["PyQt6"],
+    "pyside6": ["PySide6"],
+    "python-ldap": ["ldap"],
+    "pyusb": ["usb"],
+    "msgpack-python": ["msgpack"],
+    "markdown-it-py": ["markdown_it"],
+    "typing-extensions": ["typing_extensions"],
+    "google-cloud-storage": ["google.cloud.storage"],
+    "google-cloud-bigquery": ["google.cloud.bigquery"],
+    "google-cloud-pubsub": ["google.cloud.pubsub", "google.cloud.pubsub_v1"],
+    "apache-airflow": ["airflow"],
+    "pywin32": ["win32api", "win32con", "win32com", "pythoncom", "pywintypes"],
+};
+const VENV_DIRS = [".venv", "venv", "env", ".env", "virtualenv"];
+/** site-packages directories of virtualenvs at the project root (POSIX and Windows layouts). */
+function sitePackagesDirs(root) {
+    const out = [];
+    for (const v of VENV_DIRS) {
+        const venv = path.join(root, v);
+        const win = path.join(venv, "Lib", "site-packages");
+        if (fs.existsSync(win))
+            out.push(win);
+        const lib = path.join(venv, "lib");
+        let entries = [];
+        try {
+            entries = fs.readdirSync(lib);
+        }
+        catch {
+            continue;
+        }
+        for (const py of entries) {
+            const sp = path.join(lib, py, "site-packages");
+            if (/^python\d/.test(py) && fs.existsSync(sp))
+                out.push(sp);
+        }
+    }
+    return out;
+}
+/** Top-level importable names a RECORD lists: `pkg/__init__.py` -> pkg, `mod.py` -> mod. */
+function namesFromRecord(record) {
+    const names = new Set();
+    for (const line of record.split(/\r?\n/)) {
+        const file = line.split(",")[0]?.trim();
+        if (!file || file.startsWith("..") || file.startsWith("/"))
+            continue;
+        const first = file.split("/")[0];
+        if (/\.(?:dist-info|egg-info|data)$/.test(first) || first === "__pycache__" || /\.pth$/.test(first))
+            continue;
+        if (file.includes("/")) {
+            if (/^[A-Za-z_]\w*$/.test(first))
+                names.add(first);
+        }
+        else {
+            const mod = /^([A-Za-z_]\w*)(?:\.[\w-]+)?\.(?:py|pyd|so)$/.exec(first)?.[1];
+            if (mod)
+                names.add(mod);
+        }
+    }
+    return [...names];
+}
+function readInstalledNames(root, dist) {
+    const want = normalizePypiName(dist);
+    for (const sp of sitePackagesDirs(root)) {
+        let entries;
+        try {
+            entries = fs.readdirSync(sp);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const m = /^(.+?)-[^-]+\.(?:dist-info|egg-info)$/.exec(entry);
+            if (!m || normalizePypiName(m[1]) !== want)
+                continue;
+            const meta = path.join(sp, entry);
+            const rel = path.relative(root, meta).split(path.sep).join("/");
+            for (const [file, read] of [
+                ["top_level.txt", (t) => t.split(/\r?\n/).map((l) => l.trim()).filter((l) => /^[A-Za-z_][\w.]*$/.test(l))],
+                ["RECORD", namesFromRecord],
+            ]) {
+                try {
+                    const names = read(fs.readFileSync(path.join(meta, file), "utf8"));
+                    if (names.length > 0)
+                        return { names: [...new Set(names)].sort(), source: "installed-metadata", evidence: `${rel}/${file}` };
+                }
+                catch {
+                    // no such file: try the next
+                }
+            }
+        }
+    }
+    return null;
+}
+/** The module name(s) a distribution is imported as, and how that was established. */
+export function pythonImportNames(root, dist) {
+    const installed = root ? readInstalledNames(root, dist) : null;
+    if (installed)
+        return installed;
+    const known = KNOWN_IMPORT_NAMES[normalizePypiName(dist)];
+    if (known)
+        return { names: known, source: "known-mapping" };
+    return { names: [normalizePypiName(dist).replace(/-/g, "_")], source: "assumed" };
+}
+/** True when module `mod` is `name` or inside it (`yaml.loader` for `yaml`). */
+const underModule = (mod, name) => mod === name || mod.startsWith(`${name}.`);
+/**
+ * Count imports of any of `names` in one Python file and collect the names it
+ * reaches: `from x import A, B` gives A and B; `import x` / `import x as y`
+ * gives the attributes used as `x.attr` / `y.attr`.
+ */
+export function scanPythonSource(source, names, symbols) {
+    let matches = 0;
+    const text = source.replace(/\\\r?\n/g, " ");
+    const bindings = [];
+    // `from x import (a, b,\n c)` and `from x import a, b as c`
+    const fromRe = /^[ \t]*from[ \t]+([\w.]+)[ \t]+import[ \t]+(\([^)]*\)|[^\n#]+)/gm;
+    for (const m of text.matchAll(fromRe)) {
+        if (!names.some((n) => underModule(m[1], n)))
+            continue;
+        matches++;
+        for (const part of m[2].replace(/[()]/g, "").split(",")) {
+            const name = part.trim().split(/\s+as\s+/)[0].trim();
+            if (/^[A-Za-z_]\w*$/.test(name))
+                symbols.add(name);
+        }
+    }
+    const importRe = /^[ \t]*import[ \t]+([^\n#]+)/gm;
+    for (const m of text.matchAll(importRe)) {
+        for (const part of m[1].split(",")) {
+            const [mod, alias] = part.trim().split(/\s+as\s+/).map((s) => s.trim());
+            if (!mod || !names.some((n) => underModule(mod, n)))
+                continue;
+            matches++;
+            bindings.push(alias ?? mod);
+        }
+    }
+    // Attribute uses outside the import statements themselves (`from yaml.loader import` names a module, not an attribute).
+    const body = text.replace(fromRe, "").replace(importRe, "");
+    for (const binding of bindings) {
+        const re = new RegExp(String.raw `(?<![\w.])${binding.replace(/\./g, "\\.")}\.([A-Za-z_]\w*)`, "g");
+        for (const m of body.matchAll(re))
+            symbols.add(m[1]);
+    }
+    return matches;
+}
+// ---------------------------------------------------------------- Go
+/** True when import path `imp` is module `mod` or a package inside it, not a different major (`mod/v2`). */
+export function goImportInModule(imp, mod) {
+    if (imp === mod)
+        return true;
+    if (!imp.startsWith(`${mod}/`))
+        return false;
+    const next = imp.slice(mod.length + 1).split("/")[0];
+    return !/^v\d+$/.test(next) || goPathMajor(mod) !== null;
+}
+/** The package name an import path is used through: its last element, skipping a `/vN` suffix and gopkg.in's `.vN`. */
+export function goPackageName(imp) {
+    const parts = goBasePath(imp).split("/");
+    const last = parts[parts.length - 1] ?? imp;
+    return last.replace(/\.v\d+$/, "").replace(/^go-/, "").replace(/[-.]/g, "_");
+}
+/**
+ * Count imports of a Go module (or packages inside it) in one file and collect
+ * the exported identifiers reached through each import's package name.
+ */
+export function scanGoSource(source, mod, symbols) {
+    const specs = [];
+    const spec = /^\s*(?:([A-Za-z_]\w*|\.|_)\s+)?"([^"]+)"/;
+    for (const m of source.matchAll(/^\s*import\s*\(([\s\S]*?)\)/gm)) {
+        for (const line of m[1].split("\n")) {
+            const s = spec.exec(line.replace(/\/\/.*$/, ""));
+            if (s)
+                specs.push({ alias: s[1] ?? null, path: s[2] });
+        }
+    }
+    for (const m of source.matchAll(/^\s*import\s+(?:([A-Za-z_]\w*|\.|_)\s+)?"([^"]+)"/gm)) {
+        specs.push({ alias: m[1] ?? null, path: m[2] });
+    }
+    let matches = 0;
+    for (const s of specs) {
+        if (!goImportInModule(s.path, mod))
+            continue;
+        matches++;
+        const local = s.alias ?? goPackageName(s.path);
+        if (local === "_" || local === ".")
+            continue;
+        for (const m of source.matchAll(new RegExp(String.raw `(?<![\w.])${local}\.([A-Z]\w*)`, "g")))
+            symbols.add(m[1]);
+    }
+    return matches;
+}