@4da/mcp-server 6.0.2 → 6.2.0

package/dist/live/upgrade-sources.js

@@ -3,14 +3,16 @@
  * Network sources for `upgrade_impact`: registry version index, the target
  * version's changelog (read from its registry archive) and OSV advisories.
  *
- * Privacy rule (Decision 1, option A): the only hosts contacted are the
- * package's own registry (registry.npmjs.org; crates.io + static.crates.io)
- * and api.osv.dev. A changelog is never fetched from GitHub or a docs site,
- * even when the archive ships none — the report then hands the agent a
- * `release_notes_url` built from registry metadata, and the agent decides
- * whether to fetch it. Every request goes through `UpgradeNet`, which records
- * the host so `_meta.sources` is a fact, not a claim, and which tests replace
- * with a fake fetch.
+ * Privacy rule (Decision 1, option A): by default the only hosts contacted
+ * are the package's own registry (registry.npmjs.org; crates.io +
+ * static.crates.io; pypi.org + files.pythonhosted.org; proxy.golang.org) and
+ * api.osv.dev. A changelog is read from GitHub only when the user opts in
+ * (Decision 1, option B: FOURDA_GITHUB_CHANGELOG, github-releases.ts) and the
+ * archive has none for the range; otherwise the report hands the agent a
+ * `release_notes_url` built from registry metadata and says how to enable the
+ * fallback. Every request goes through `UpgradeNet`, which records the host
+ * so `_meta.sources` is a fact, not a claim, and which tests replace with a
+ * fake fetch.
  *
  * Request budget per call: index (1) + archive (1) + OSV for from/to (2) = 4,
  * each cached (index 6 h, parsed changelog 7 d, OSV 1 h). The npm packument
@@ -18,8 +20,40 @@
  * is cached — never the raw document.
  */
 import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
-import { ArchiveError, defaultFetch, fetchArchiveRootFiles } from "./package-archive.js";
-import { findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
+import { ArchiveError, defaultFetch, fetchArchiveBytes, readRootTextFiles } from "./package-archive.js";
+import { CHANGELOG_PARSER_VERSION, findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
+import { compareVersions, isComparable } from "./version-compare.js";
+import { isPrereleaseVersion } from "./osv-ranges.js";
+import { looksLikeZip, readZipRootTextFiles } from "./zip-archive.js";
+import { loadPypiIndex, normalizePypiName, PYPI_NAME } from "./upgrade-pypi.js";
+import { GO_MODULE, goZipUrl, loadGoIndex } from "./upgrade-go.js";
+export const UPGRADE_ECOSYSTEMS = ["npm", "crates.io", "PyPI", "Go"];
+/** Version order for an ecosystem: semver precedence (npm, crates.io, Go without its `v`), PEP 440 (PyPI). Null = unreadable. */
+export function versionOrder(ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return compareVersionPrecedence;
+    return (a, b) => (isComparable(a, ecosystem) && isComparable(b, ecosystem) ? compareVersions(a, b, ecosystem) : null);
+}
+/** Readable as a version in this ecosystem. */
+export function isReadableVersion(version, ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return parseSemverPrecedence(version) !== null;
+    return version !== "0" && isComparable(version, ecosystem);
+}
+/** A prerelease in this ecosystem's own terms (PEP 440 `a`/`b`/`rc`/`.dev`; semver `-x`; a Go pseudo-version). */
+export function isPrerelease(version, ecosystem) {
+    if (ecosystem === "npm" || ecosystem === "crates.io")
+        return (parseSemverPrecedence(version)?.prerelease.length ?? 0) > 0;
+    return isPrereleaseVersion(version, ecosystem);
+}
+/** Package-name identity: crates.io folds `-`/`_`, PyPI normalises per PEP 503, npm and Go are exact. */
+export function sameUpgradeName(a, b, ecosystem) {
+    if (ecosystem === "crates.io")
+        return a.replace(/-/g, "_") === b.replace(/-/g, "_");
+    if (ecosystem === "PyPI")
+        return normalizePypiName(a) === normalizePypiName(b);
+    return a === b;
+}
 /** crates.io refuses API requests without a descriptive User-Agent. */
 export const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
 const INDEX_TTL = 6 * 3600;
@@ -42,7 +76,16 @@ export function createUpgradeNet(cache, fetchFn = defaultFetch) {
 const NPM_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
 const CRATE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 export function isValidPackageName(name, ecosystem) {
-    return ecosystem === "npm" ? NPM_NAME.test(name) && name.length <= 214 : CRATE_NAME.test(name);
+    switch (ecosystem) {
+        case "npm":
+            return NPM_NAME.test(name) && name.length <= 214;
+        case "crates.io":
+            return CRATE_NAME.test(name);
+        case "PyPI":
+            return PYPI_NAME.test(name);
+        case "Go":
+            return GO_MODULE.test(name) && name.length <= 300 && !name.split("/").some((p) => p === "." || p === "..");
+    }
 }
 async function cached(net, key, ttl, load) {
     const hit = net.cache?.get(key);
@@ -99,21 +142,36 @@ async function loadCratesIndex(net, name) {
 }
 /** Registry index with versions in ascending precedence order (unreadable versions dropped). Null = unknown package. */
 export async function getRegistryIndex(net, ecosystem, name) {
-    const key = `upgrade-impact:index:${ecosystem}:${ecosystem === "crates.io" ? name.replace(/-/g, "_") : name}`;
-    const index = await cached(net, key, INDEX_TTL, () => ecosystem === "npm" ? loadNpmIndex(net, name) : loadCratesIndex(net, name));
+    const keyName = ecosystem === "crates.io" ? name.replace(/-/g, "_") : ecosystem === "PyPI" ? normalizePypiName(name) : name;
+    const key = `upgrade-impact:index:${ecosystem}:${keyName}`;
+    const index = await cached(net, key, INDEX_TTL, () => {
+        switch (ecosystem) {
+            case "npm":
+                return loadNpmIndex(net, name);
+            case "crates.io":
+                return loadCratesIndex(net, name);
+            case "PyPI":
+                return loadPypiIndex(net, name);
+            case "Go":
+                return loadGoIndex(net, name);
+        }
+    });
     if (!index)
         return null;
+    const order = versionOrder(ecosystem);
     const versions = index.versions
-        .filter((v) => parseSemverPrecedence(v.version) !== null)
-        .sort((a, b) => compareVersionPrecedence(a.version, b.version) ?? 0);
+        .filter((v) => isReadableVersion(v.version, ecosystem))
+        .sort((a, b) => order(a.version, b.version) ?? 0);
     return { ...index, versions };
 }
-const ARCHIVE_HOSTS = new Set(["registry.npmjs.org", "static.crates.io"]);
+const ARCHIVE_HOSTS = new Set(["registry.npmjs.org", "static.crates.io", "files.pythonhosted.org", "proxy.golang.org"]);
 /** The registry archive URL for one version, or null when it is not on the package's own registry. */
 export function archiveUrl(index, version) {
     const url = index.ecosystem === "crates.io"
         ? `https://static.crates.io/crates/${index.name}/${index.name}-${version.version}.crate`
-        : version.tarball;
+        : index.ecosystem === "Go"
+            ? goZipUrl(index.name, version.version)
+            : version.tarball;
     if (!url)
         return null;
     try {
@@ -124,20 +182,34 @@ export function archiveUrl(index, version) {
         return null;
     }
 }
+/** Cache key of one version's parsed changelog; it carries CHANGELOG_PARSER_VERSION. */
+export function changelogCacheKey(ecosystem, name, version) {
+    return `upgrade-impact:changelog:p${CHANGELOG_PARSER_VERSION}:${ecosystem}:${name}:${version}`;
+}
 /** Parsed changelog shipped inside one version's archive (cached 7 days per version). */
 export async function getChangelog(net, index, version) {
     const url = archiveUrl(index, version);
     if (!url) {
-        return { found: false, reason: "the version's archive is not hosted on the package's own registry" };
+        return {
+            found: false,
+            reason: index.ecosystem === "PyPI" && !version.tarball
+                ? `${version.version} has no source distribution on PyPI (wheels only), so there is no archive changelog to read`
+                : "the version's archive is not hosted on the package's own registry",
+        };
     }
-    const key = `upgrade-impact:changelog:${index.ecosystem}:${index.name}:${version.version}`;
+    // The parser version is in the key: a parser fix must not wait out the 7-day TTL.
+    const key = changelogCacheKey(index.ecosystem, index.name, version.version);
     const hit = net.cache?.get(key);
     if (hit)
         return hit;
     const headers = index.ecosystem === "crates.io" ? { "User-Agent": CRATES_USER_AGENT } : {};
     let files;
     try {
-        files = await fetchArchiveRootFiles(url, isChangelogName, net.fetch, headers);
+        const bytes = await fetchArchiveBytes(url, net.fetch, headers);
+        // A Go module zip holds its files under `<module>@<version>/`; a zip sdist and every tar one directory deep.
+        files = looksLikeZip(bytes)
+            ? readZipRootTextFiles(bytes, isChangelogName, index.ecosystem === "Go" ? `${index.name}@${version.version}/` : null)
+            : readRootTextFiles(bytes, isChangelogName);
     }
     catch (err) {
         const result = { found: false, reason: `could not read the ${version.version} archive: ${err.message}` };
@@ -153,7 +225,7 @@ export async function getChangelog(net, index, version) {
         ? { found: false, reason: `the ${version.version} archive ships no changelog file` }
         : sections.length === 0
             ? { found: false, file, reason: `${file} has no version headings this parser recognises` }
-            : { found: true, file, sections };
+            : { found: true, file, sections, source: "archive" };
     net.cache?.set(key, result, CACHE_SOURCE, CHANGELOG_TTL);
     return result;
 }

package/dist/live/zip-archive.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Zip archive reader for `upgrade_impact`, Node built-ins only.
+ *
+ * Go module zips (proxy.golang.org `/@v/<version>.zip`) and the occasional
+ * PyPI `.zip` sdist are zip files, not gzip tars. The job is the same as
+ * package-archive.ts's: pull a few root-level text files (the changelog) out
+ * of a third-party archive without trusting it. Only the central directory
+ * is read, so a file's declared sizes come from one place; stored (0) and
+ * deflate (8) entries are read, everything else (zip64, encryption, other
+ * methods) is skipped rather than guessed at. Each inflate is capped at
+ * MAX_FILE_BYTES, so a zip bomb stops at the cap.
+ */
+/** True when the buffer starts like a zip archive (a local file header). */
+export declare function looksLikeZip(buf: Buffer): boolean;
+/**
+ * Text files directly under `root` (a path prefix such as
+ * `github.com/foo/bar@v1.2.3/`; "" for every top-level file of a one-directory
+ * archive) whose basename `accept` approves. When `root` is null, files one
+ * directory deep are read, as the tar reader does. Oversized, binary and
+ * unreadable entries are skipped.
+ */
+export declare function readZipRootTextFiles(buf: Buffer, accept: (basename: string) => boolean, root?: string | null): Map<string, string>;

package/dist/live/zip-archive.js

@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Zip archive reader for `upgrade_impact`, Node built-ins only.
+ *
+ * Go module zips (proxy.golang.org `/@v/<version>.zip`) and the occasional
+ * PyPI `.zip` sdist are zip files, not gzip tars. The job is the same as
+ * package-archive.ts's: pull a few root-level text files (the changelog) out
+ * of a third-party archive without trusting it. Only the central directory
+ * is read, so a file's declared sizes come from one place; stored (0) and
+ * deflate (8) entries are read, everything else (zip64, encryption, other
+ * methods) is skipped rather than guessed at. Each inflate is capped at
+ * MAX_FILE_BYTES, so a zip bomb stops at the cap.
+ */
+import { inflateRawSync } from "node:zlib";
+import { ArchiveError, MAX_COMPRESSED_BYTES, MAX_FILE_BYTES } from "./package-archive.js";
+const EOCD_SIG = 0x06054b50;
+const CDH_SIG = 0x02014b50;
+const LFH_SIG = 0x04034b50;
+/** The end-of-central-directory record is 22 bytes plus a comment of at most 65,535. */
+const EOCD_SEARCH = 22 + 0xffff;
+const MAX_ENTRIES = 200_000;
+/** True when the buffer starts like a zip archive (a local file header). */
+export function looksLikeZip(buf) {
+    return buf.length >= 4 && buf.readUInt32LE(0) === LFH_SIG;
+}
+function findEocd(buf) {
+    const stop = Math.max(0, buf.length - EOCD_SEARCH);
+    for (let i = buf.length - 22; i >= stop; i--) {
+        if (buf.readUInt32LE(i) === EOCD_SIG)
+            return i;
+    }
+    throw new ArchiveError("not a zip archive (no end-of-central-directory record)");
+}
+/**
+ * Text files directly under `root` (a path prefix such as
+ * `github.com/foo/bar@v1.2.3/`; "" for every top-level file of a one-directory
+ * archive) whose basename `accept` approves. When `root` is null, files one
+ * directory deep are read, as the tar reader does. Oversized, binary and
+ * unreadable entries are skipped.
+ */
+export function readZipRootTextFiles(buf, accept, root = null) {
+    if (buf.length > MAX_COMPRESSED_BYTES) {
+        throw new ArchiveError(`archive is ${buf.length} bytes compressed (cap ${MAX_COMPRESSED_BYTES})`);
+    }
+    if (buf.length < 22)
+        throw new ArchiveError("not a zip archive (too short)");
+    const eocd = findEocd(buf);
+    const count = buf.readUInt16LE(eocd + 10);
+    const cdSize = buf.readUInt32LE(eocd + 12);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    if (cdOffset === 0xffffffff || count === 0xffff)
+        throw new ArchiveError("zip64 archives are not read");
+    if (cdOffset + cdSize > buf.length || count > MAX_ENTRIES)
+        throw new ArchiveError("corrupt zip central directory");
+    const files = new Map();
+    let p = cdOffset;
+    for (let n = 0; n < count; n++) {
+        if (p + 46 > buf.length || buf.readUInt32LE(p) !== CDH_SIG)
+            throw new ArchiveError("corrupt zip central directory entry");
+        const flags = buf.readUInt16LE(p + 8);
+        const method = buf.readUInt16LE(p + 10);
+        const compressed = buf.readUInt32LE(p + 20);
+        const size = buf.readUInt32LE(p + 24);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const local = buf.readUInt32LE(p + 42);
+        const name = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");
+        p += 46 + nameLen + extraLen + commentLen;
+        if (name.endsWith("/") || !isRootFile(name, root) || !accept(name.split("/").pop() ?? ""))
+            continue;
+        if (flags & 0x1 || (method !== 0 && method !== 8) || size > MAX_FILE_BYTES)
+            continue;
+        if (local + 30 > buf.length || buf.readUInt32LE(local) !== LFH_SIG)
+            continue;
+        const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+        if (start + compressed > buf.length)
+            continue;
+        const raw = buf.subarray(start, start + compressed);
+        let data;
+        try {
+            data = method === 0 ? Buffer.from(raw) : inflateRawSync(raw, { maxOutputLength: MAX_FILE_BYTES });
+        }
+        catch {
+            continue;
+        }
+        if (data.includes(0))
+            continue;
+        files.set(name, data.toString("utf8"));
+    }
+    return files;
+}
+function isRootFile(name, root) {
+    if (root !== null)
+        return name.startsWith(root) && !name.slice(root.length).includes("/") && name.length > root.length;
+    const parts = name.split("/").filter(Boolean);
+    return parts.length > 0 && parts.length <= 2;
+}

package/dist/memory-store.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Where a decision, agent memory or feedback record is written.
+ *
+ * Reads go through the database's main connection (read-only for the desktop
+ * app's database). A write into one of the app-owned tables the tools exist to
+ * write goes through FourDADatabase.writerFor: the app's own table via a
+ * separate write connection, or, when the app's schema lacks the table or a
+ * column, the server's store with a note. A stand-in object without writerFor
+ * (some tests hand tools a minimal double) writes to its own connection.
+ */
+import type { AppWritableTable, FourDADatabase, WriteTarget } from "./db.js";
+export declare function writerOf(db: FourDADatabase, table: AppWritableTable, columns: readonly string[]): WriteTarget;
+/** `_meta` for a tool result when the record could not go where it normally goes. */
+export declare function writeMeta(target: WriteTarget): {
+    _meta?: {
+        written_to: string;
+        note: string;
+    };
+};

package/dist/memory-store.js

@@ -0,0 +1,8 @@
+export function writerOf(db, table, columns) {
+    const writerFor = db.writerFor;
+    return typeof writerFor === "function" ? writerFor.call(db, table, columns) : { raw: db.getRawDb(), target: "database" };
+}
+/** `_meta` for a tool result when the record could not go where it normally goes. */
+export function writeMeta(target) {
+    return target.note ? { _meta: { written_to: target.target, note: target.note } } : {};
+}

package/dist/native-bindings.d.ts

@@ -8,12 +8,17 @@
  * (local or -g) left no better_sqlite3.node, `--doctor` still reported the
  * bindings as loaded, and every tool failed with "Could not locate the
  * bindings file" and no hint why. `npx @4da/mcp-server` was unaffected.
+ *
+ * Since 6.1.0 the server uses Node's built-in node:sqlite when the runtime
+ * has it (sqlite-driver.ts), so this matters only on Node 22.0-22.12, where
+ * better-sqlite3 is the one driver.
  */
-import type BetterSqlite3 from "better-sqlite3";
 export declare const NATIVE_BINDING_FIX: string;
 /** Errors that mean the compiled module is absent or built for another Node/platform. */
 export declare function isNativeBindingError(err: unknown): boolean;
 /** The first line of a native-binding error, with the fix appended. */
 export declare function nativeBindingMessage(err: unknown): string;
 /** Null when an in-memory database opens; otherwise why not, with the fix. */
-export declare function checkNativeBindings(Database: typeof BetterSqlite3): string | null;
+export declare function checkNativeBindings(Database: new (file: string) => {
+    close(): unknown;
+}): string | null;

package/dist/native-bindings.js

@@ -9,6 +9,10 @@
  * (local or -g) left no better_sqlite3.node, `--doctor` still reported the
  * bindings as loaded, and every tool failed with "Could not locate the
  * bindings file" and no hint why. `npx @4da/mcp-server` was unaffected.
+ *
+ * Since 6.1.0 the server uses Node's built-in node:sqlite when the runtime
+ * has it (sqlite-driver.ts), so this matters only on Node 22.0-22.12, where
+ * better-sqlite3 is the one driver.
  */
 // Each remedy measured on npm 12.2.0 (node:24-bookworm-slim), 2026-10-03.
 export const NATIVE_BINDING_FIX = "npm 12+ blocks dependency install scripts unless allowed. With npx: allow it once with " +

package/dist/project-tree.d.ts

@@ -9,23 +9,65 @@
  * app does not have this problem — it records each dependency's own manifest
  * directory — so this is the standalone counterpart of that inventory.
  *
- * A directory joins when it holds a lockfile (or go.mod / requirements.txt,
- * which carry exact versions themselves). Workspace members that share their
- * root's lockfile are covered by the root. Bounded: depth 2 below the root,
- * at most 64 projects, and directories that hold installed code, build
- * output, test fixtures or tool worktrees are skipped.
+ * A directory joins when it holds a lockfile (or go.mod / a requirements
+ * file, which carry exact versions themselves). Workspace members that share
+ * their root's lockfile are covered by the root. Directories that hold
+ * installed code, build output, test fixtures or tool worktrees are skipped.
+ *
+ * Bounded (MAX_DEPTH levels below the root, MAX_PROJECTS projects), and the
+ * bound is never silent. langchain keeps 108 lockfiles up to three levels
+ * down; the old bounds (depth 2, 64 projects) read 64 and dropped 44 with no
+ * trace in any answer (2026-10-10). Past a bound the walk keeps going without
+ * scanning, up to MAX_WALK_DIRS directories, so `discovery` can name every
+ * lockfile that was left out and say why.
  */
 import { type ProjectScanResult } from "./project-scanner.js";
+/**
+ * Measured on langchain (108 lockfiles, up to 3 levels down; 2026-10-10):
+ * the walk plus every project scan takes about 2 s. Depth 4 covers it with a
+ * level to spare; 256 projects is 2.4x its count.
+ */
+export declare const MAX_DEPTH = 4;
+export declare const MAX_PROJECTS = 256;
 export interface ProjectTreeEntry {
     dir: string;
     scan: ProjectScanResult;
 }
+/** What the walk left out, so an answer can say it is partial. */
+export interface TreeDiscovery {
+    /** Projects scanned (the root included). */
+    projects: number;
+    maxDepth: number;
+    maxProjects: number;
+    /** Lockfiles found but not scanned, relative to the root (the first MAX_LISTED_SKIPS). */
+    skipped: Array<{
+        path: string;
+        reason: "depth" | "project_limit";
+    }>;
+    /** Every lockfile found but not scanned (`skipped` may list fewer). */
+    skippedCount: number;
+    /** True when the walk itself stopped at MAX_WALK_DIRS: lockfiles beyond it were not even counted. */
+    walkTruncated: boolean;
+}
+/** Python requirement files: requirements.txt, requirements-dev.txt, dev_requirements.txt, _test_minimum_requirements.txt. */
+export declare function isRequirementsFileName(name: string): boolean;
+/** The lockfiles (and exact-pin files) that make a directory a project, by name. */
+export declare function lockfilesIn(dir: string, listing?: string[]): string[];
 /**
  * The root (always) and every locked project below it, each with its own
- * scan. Directories and lockfiles the repository's .gitignore excludes are not
- * part of the project and are skipped (gitignore.ts).
+ * scan, plus what the bounds left out. Directories and lockfiles the
+ * repository's .gitignore excludes are not part of the project and are
+ * skipped (gitignore.ts); they are not reported as left out either.
  */
-export declare function scanProjectTree(root: string): ProjectTreeEntry[];
+export declare function scanProjectTree(root: string, limits?: {
+    maxDepth: number;
+    maxProjects: number;
+}): {
+    entries: ProjectTreeEntry[];
+    discovery: TreeDiscovery;
+};
+/** One sentence for an answer, or null when nothing was left out. */
+export declare function discoveryNote(discovery: TreeDiscovery | null): string | null;
 /**
  * Resolution groups for the live layer: one per (project directory, ecosystem).
  * A lockfile whose manifest declared nothing the scanner could read still gets

package/dist/project-tree.js

@@ -10,11 +10,17 @@
  * app does not have this problem — it records each dependency's own manifest
  * directory — so this is the standalone counterpart of that inventory.
  *
- * A directory joins when it holds a lockfile (or go.mod / requirements.txt,
- * which carry exact versions themselves). Workspace members that share their
- * root's lockfile are covered by the root. Bounded: depth 2 below the root,
- * at most 64 projects, and directories that hold installed code, build
- * output, test fixtures or tool worktrees are skipped.
+ * A directory joins when it holds a lockfile (or go.mod / a requirements
+ * file, which carry exact versions themselves). Workspace members that share
+ * their root's lockfile are covered by the root. Directories that hold
+ * installed code, build output, test fixtures or tool worktrees are skipped.
+ *
+ * Bounded (MAX_DEPTH levels below the root, MAX_PROJECTS projects), and the
+ * bound is never silent. langchain keeps 108 lockfiles up to three levels
+ * down; the old bounds (depth 2, 64 projects) read 64 and dropped 44 with no
+ * trace in any answer (2026-10-10). Past a bound the walk keeps going without
+ * scanning, up to MAX_WALK_DIRS directories, so `discovery` can name every
+ * lockfile that was left out and say why.
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
@@ -29,60 +35,143 @@ const LOCK_MARKERS = [
     "Cargo.lock",
     "poetry.lock",
     "uv.lock",
+    "pdm.lock",
     "Pipfile.lock",
     "go.mod",
-    "requirements.txt",
 ];
 const SKIP_DIRS = new Set([
     "node_modules", "target", ".git", "dist", "build", "out", "vendor", ".venv", "venv",
     "__pycache__", ".next", ".nuxt", "coverage", ".claude", ".codex", ".cursor", "fixtures",
     "__fixtures__", "testdata", "test-fixtures", "__tests__", ".turbo", ".cache", ".pnpm-store",
 ]);
-const MAX_DEPTH = 2;
-const MAX_PROJECTS = 64;
+/**
+ * Measured on langchain (108 lockfiles, up to 3 levels down; 2026-10-10):
+ * the walk plus every project scan takes about 2 s. Depth 4 covers it with a
+ * level to spare; 256 projects is 2.4x its count.
+ */
+export const MAX_DEPTH = 4;
+export const MAX_PROJECTS = 256;
+/** Directories visited in total, scanned or not: the hard cap on the walk itself. */
+const MAX_WALK_DIRS = 20_000;
+/** Lockfile paths listed in `discovery.skipped`; the count covers the rest. */
+const MAX_LISTED_SKIPS = 50;
+/** Python requirement files: requirements.txt, requirements-dev.txt, dev_requirements.txt, _test_minimum_requirements.txt. */
+export function isRequirementsFileName(name) {
+    return /requirements[\w.-]*\.txt$/i.test(name);
+}
+/** The lockfiles (and exact-pin files) that make a directory a project, by name. */
+export function lockfilesIn(dir, listing) {
+    let names;
+    try {
+        names = listing ?? fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const found = names.filter((n) => LOCK_MARKERS.includes(n) || isRequirementsFileName(n));
+    // pip-compile-multi and similar keep the pins in a requirements/ folder (superset: requirements/base.txt).
+    if (names.includes("requirements")) {
+        try {
+            for (const n of fs.readdirSync(path.join(dir, "requirements")))
+                if (/\.txt$/i.test(n))
+                    found.push(`requirements/${n}`);
+        }
+        catch {
+            // a file named "requirements"
+        }
+    }
+    return found;
+}
 /**
  * The root (always) and every locked project below it, each with its own
- * scan. Directories and lockfiles the repository's .gitignore excludes are not
- * part of the project and are skipped (gitignore.ts).
+ * scan, plus what the bounds left out. Directories and lockfiles the
+ * repository's .gitignore excludes are not part of the project and are
+ * skipped (gitignore.ts); they are not reported as left out either.
  */
-export function scanProjectTree(root) {
+export function scanProjectTree(root, limits = { maxDepth: MAX_DEPTH, maxProjects: MAX_PROJECTS }) {
     const entries = [{ dir: root, scan: scanCurrentProject(root) }];
     const ignore = new IgnoreRules(root);
-    const walk = (dir, rel, depth) => {
-        if (depth > MAX_DEPTH || entries.length >= MAX_PROJECTS)
-            return;
-        ignore.load(rel);
-        let children;
+    const skipped = [];
+    let skippedCount = 0;
+    let visited = 0;
+    let walkTruncated = false;
+    // One directory listing per directory: it decides both whether the
+    // directory is a project and which children to descend into.
+    const listing = (dir) => {
         try {
-            children = fs.readdirSync(dir, { withFileTypes: true });
+            return fs.readdirSync(dir, { withFileTypes: true });
         }
         catch {
-            return;
+            return null;
         }
+    };
+    const walk = (dir, rel, depth, children) => {
         for (const child of children) {
-            if (entries.length >= MAX_PROJECTS)
-                return;
             if (!child.isDirectory() || SKIP_DIRS.has(child.name) || child.name.startsWith("."))
                 continue;
+            if (++visited > MAX_WALK_DIRS) {
+                walkTruncated = true;
+                return;
+            }
             const childRel = rel ? `${rel}/${child.name}` : child.name;
             if (ignore.ignores(childRel, true))
                 continue;
             const sub = path.join(dir, child.name);
-            ignore.load(childRel);
-            const locked = LOCK_MARKERS.some((marker) => fs.existsSync(path.join(sub, marker)) && !ignore.ignores(`${childRel}/${marker}`, false));
-            if (locked)
-                entries.push({ dir: sub, scan: scanCurrentProject(sub) });
-            walk(sub, childRel, depth + 1);
+            const grandchildren = listing(sub);
+            if (!grandchildren)
+                continue;
+            // A .gitignore is only read where one exists.
+            if (grandchildren.some((g) => g.name === ".gitignore"))
+                ignore.load(childRel);
+            const names = grandchildren.map((g) => g.name);
+            const locks = lockfilesIn(sub, names).filter((name) => !ignore.ignores(`${childRel}/${name}`, false));
+            if (locks.length > 0) {
+                const reason = depth > limits.maxDepth ? "depth" : entries.length >= limits.maxProjects ? "project_limit" : null;
+                if (reason === null) {
+                    entries.push({ dir: sub, scan: scanCurrentProject(sub) });
+                }
+                else {
+                    skippedCount += locks.length;
+                    for (const name of locks)
+                        if (skipped.length < MAX_LISTED_SKIPS)
+                            skipped.push({ path: `${childRel}/${name}`, reason });
+                }
+            }
+            walk(sub, childRel, depth + 1, grandchildren);
+            if (walkTruncated)
+                return;
         }
     };
-    walk(root, "", 1);
-    return entries;
+    walk(root, "", 1, listing(root) ?? []);
+    return {
+        entries,
+        discovery: { projects: entries.length, maxDepth: limits.maxDepth, maxProjects: limits.maxProjects, skipped, skippedCount, walkTruncated },
+    };
+}
+/** One sentence for an answer, or null when nothing was left out. */
+export function discoveryNote(discovery) {
+    if (!discovery || (discovery.skippedCount === 0 && !discovery.walkTruncated))
+        return null;
+    const parts = [];
+    if (discovery.skippedCount > 0) {
+        const depth = discovery.skipped.some((s) => s.reason === "depth");
+        const limit = discovery.skipped.some((s) => s.reason === "project_limit");
+        const why = [
+            depth ? `deeper than ${discovery.maxDepth} levels` : null,
+            limit ? `past the ${discovery.maxProjects}-project limit` : null,
+        ].filter(Boolean).join(" or ");
+        const listed = discovery.skipped.slice(0, 5).map((s) => s.path).join(", ");
+        parts.push(`${discovery.skippedCount} lockfile${discovery.skippedCount === 1 ? " was" : "s were"} found but NOT scanned (${why}): ${listed}${discovery.skippedCount > 5 ? ", ..." : ""}; pass project_path to scan one of them`);
+    }
+    if (discovery.walkTruncated)
+        parts.push(`the directory walk stopped after ${MAX_WALK_DIRS} directories, so lockfiles beyond that were not counted`);
+    return `Partial scan: ${parts.join("; ")}.`;
 }
 /** Lockfiles that make an ecosystem scannable in a directory even when no direct dependency was parsed. */
 const LOCKS_BY_LANGUAGE = {
     npm: ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"],
     rust: ["Cargo.lock"],
-    python: ["poetry.lock", "uv.lock", "Pipfile.lock", "requirements.txt"],
+    python: ["poetry.lock", "uv.lock", "pdm.lock", "Pipfile.lock"],
     go: ["go.mod"],
 };
 /**
@@ -94,8 +183,11 @@ const LOCKS_BY_LANGUAGE = {
 export function treeResolutionGroups(entries) {
     return entries.flatMap(({ dir, scan }) => {
         const byLanguage = { ...scan.depsByEcosystem };
+        const present = lockfilesIn(dir);
+        const pins = present.some((n) => isRequirementsFileName(n) || n.startsWith("requirements/"));
         for (const [language, locks] of Object.entries(LOCKS_BY_LANGUAGE)) {
-            if (!byLanguage[language] && locks.some((lock) => fs.existsSync(path.join(dir, lock)))) {
+            const pinned = language === "python" && pins;
+            if (!byLanguage[language] && (pinned || locks.some((lock) => present.includes(lock)))) {
                 byLanguage[language] = { deps: [], devDeps: [] };
             }
         }