echelongraph-mcp 2.6.8 → 2.7.0

package/dist/tools/manifests/gomod.js

@@ -0,0 +1,168 @@
+// go.mod (#2835), read as go.dev/ref/mod#go-mod-file describes it: require, in single-line and
+// block form, `// indirect` ones included; then each requirement's replace and exclude applied, as
+// the go command applies them in the main module.
+//   - replace old [v] => new v: the module checked is new at v (a replace naming old's version
+//     applies to that version only, and wins over one that names none); replace old => ./dir (or
+//     ../dir, /dir) is a local directory: local_path, not checked.
+//   - exclude m v: a require of exactly m v is not what the build uses (the go command moves to the
+//     next higher version it can find, which this file does not say): version_unresolved.
+// A go directive below 1.17 means the file lists only the main module's direct requirements, not
+// every module the build loads (module graph pruning, go.dev/ref/mod#graph-pruning): a note says
+// so. go.sum is not read here: it lists every version the module graph mentions, not the one the
+// build selects (core-backend's go.sum holds ten golang.org/x/sys versions where its go.mod
+// selects one).
+import { emptyParsed, purlOf, specOf, usableVersion } from "./common.js";
+// One line's tokens, its comment removed (and whether that comment is `// indirect`). Strings are
+// "interpreted" or `raw`, as the grammar allows a module path or file path to be quoted.
+function tokens(line) {
+    const toks = [];
+    let i = 0;
+    let indirect = false;
+    while (i < line.length) {
+        const c = line[i];
+        if (c === " " || c === "\t" || c === "\r") {
+            i++;
+        }
+        else if (line.startsWith("//", i)) {
+            indirect = /^indirect(\s|;|$)/.test(line.slice(i + 2).trim());
+            break;
+        }
+        else if (c === '"' || c === "`") {
+            let j = i + 1;
+            let s = "";
+            while (j < line.length && line[j] !== c) {
+                if (c === '"' && line[j] === "\\" && j + 1 < line.length)
+                    j++;
+                s += line[j++];
+            }
+            toks.push({ text: s, quoted: true });
+            i = j + 1;
+        }
+        else if (c === "(" || c === ")") {
+            toks.push({ text: c, quoted: false });
+            i++;
+        }
+        else {
+            let j = i;
+            while (j < line.length && !/[\s()"`]/.test(line[j]) && !line.startsWith("//", j))
+                j++;
+            toks.push({ text: line.slice(i, j), quoted: false });
+            i = j;
+        }
+    }
+    return { toks, indirect };
+}
+const isLocal = (p) => /^(\.{1,2}[\\/]|\.{1,2}$|[\\/]|[A-Za-z]:[\\/])/.test(p);
+// Each directive line, a block's lines carrying the block's verb.
+function directives(text) {
+    const out = [];
+    let block = null;
+    text.split("\n").forEach((raw, i) => {
+        const { toks, indirect } = tokens(raw);
+        if (toks.length === 0)
+            return;
+        if (block !== null) {
+            if (toks.length === 1 && toks[0].text === ")" && !toks[0].quoted) {
+                block = null;
+                return;
+            }
+            out.push({ verb: block, args: toks, indirect, line: i + 1, raw });
+            return;
+        }
+        const verb = toks[0].text;
+        if (toks.length === 2 && toks[1].text === "(" && !toks[1].quoted) {
+            block = verb;
+            return;
+        }
+        out.push({ verb, args: toks.slice(1), indirect, line: i + 1, raw });
+    });
+    return out;
+}
+// "1.16" is below 1.17; "1.21.0" and "1.17" are not.
+function below117(v) {
+    const m = /^(\d+)\.(\d+)/.exec(v);
+    if (!m)
+        return false;
+    return Number(m[1]) < 1 || (Number(m[1]) === 1 && Number(m[2]) < 17);
+}
+export function readGoMod(text) {
+    const p = emptyParsed();
+    p.replaced = [];
+    const lines = directives(text);
+    const requires = [];
+    const excluded = new Set();
+    // replace, keyed by old path, then by old version ("" for every version).
+    const replaces = new Map();
+    let goVersion = null;
+    for (const l of lines) {
+        const a = l.args.map((t) => t.text);
+        switch (l.verb) {
+            case "go":
+                goVersion = a[0] ?? null;
+                break;
+            case "require":
+                requires.push(l);
+                break;
+            case "exclude":
+                if (a.length >= 2)
+                    excluded.add(`${a[0]}@${a[1]}`);
+                break;
+            case "replace": {
+                const arrow = a.indexOf("=>");
+                if (arrow < 1)
+                    break;
+                const [oldPath, oldVersion = ""] = a.slice(0, arrow);
+                const [newPath, newVersion] = a.slice(arrow + 1);
+                if (!newPath)
+                    break;
+                if (!replaces.has(oldPath))
+                    replaces.set(oldPath, new Map());
+                replaces.get(oldPath).set(oldVersion, { path: newPath, version: newVersion ?? null, line: l.line });
+                break;
+            }
+            case "module":
+            case "toolchain":
+            case "godebug":
+            case "retract":
+            case "tool":
+            case "ignore":
+                // No dependency version.
+                break;
+            default:
+                p.not_checked.push({ name: null, spec: specOf(l.raw), reason: "unsupported_line", line: l.line, detail: `not a go.mod directive (${l.verb})` });
+                break;
+        }
+    }
+    for (const r of requires) {
+        const [path, version] = r.args.map((t) => t.text);
+        const miss = (reason, detail) => p.not_checked.push({ name: path ?? null, spec: specOf(r.raw), reason, line: r.line, detail });
+        if (!path || !usableVersion(version) || r.args.length !== 2) {
+            miss("unsupported_line", "not a require line this reader can read (module path, then version)");
+            continue;
+        }
+        const rep = replaces.get(path)?.get(version) ?? replaces.get(path)?.get("");
+        if (rep) {
+            if (isLocal(rep.path)) {
+                miss("local_path", `replaced by the local directory ${rep.path} (replace on line ${rep.line}), which is not a published module version`);
+                continue;
+            }
+            if (!usableVersion(rep.version)) {
+                miss("unsupported_line", `replaced by ${rep.path} without a version (replace on line ${rep.line}), which this reader cannot resolve`);
+                continue;
+            }
+            p.replaced.push({ from: `${path}@${version}`, to: `${rep.path}@${rep.version}` });
+            p.pinned.push({ purl: purlOf("golang", rep.path, rep.version), line: r.line });
+            continue;
+        }
+        if (excluded.has(`${path}@${version}`)) {
+            miss("version_unresolved", "this version is excluded by an exclude directive, so the build uses another version, which go.mod does not name");
+            continue;
+        }
+        p.pinned.push({ purl: purlOf("golang", path, version), line: r.line });
+    }
+    // No go directive is read as go 1.16 (go.dev/ref/mod#go-mod-file-go).
+    if (goVersion === null || below117(goVersion)) {
+        p.notes.push(`${goVersion === null ? "It has no go directive, which the go command reads as go 1.16" : `Its go directive is ${goVersion}`}, below 1.17: such a go.mod lists the main module's own requirements, not every module the build loads, so modules required only by its dependencies are not checked.`);
+    }
+    return p;
+}

package/dist/tools/manifests/index.js

@@ -0,0 +1,80 @@
+// Which reader a file goes to (#2835): by its format when the caller names one, else by its
+// basename. A manifest that holds ranges, not resolved versions, is refused with the lockfile to
+// pass instead; formats not read yet are refused as such. Nothing here guesses a format from a
+// file's content.
+import { Unreadable } from "./common.js";
+import { readGoMod } from "./gomod.js";
+import { readCargoLock, readComposerLock, readGemfileLock, readGradleLockfile, readPoetryLock } from "./lockfiles.js";
+import { readNpmLock } from "./npmlock.js";
+import { readRequirements } from "./requirements.js";
+export { NOT_CHECKED_REASONS, Unreadable } from "./common.js";
+// The formats read, by the name the `format` argument takes, each with its purl type's ecosystem.
+export const FORMATS = {
+    "requirements.txt": { ecosystem: "PyPI", read: readRequirements },
+    "go.mod": { ecosystem: "Go", read: readGoMod },
+    "package-lock.json": { ecosystem: "npm", read: readNpmLock },
+    "Cargo.lock": { ecosystem: "crates.io", read: readCargoLock },
+    "Gemfile.lock": { ecosystem: "RubyGems", read: readGemfileLock },
+    "composer.lock": { ecosystem: "Packagist", read: readComposerLock },
+    "poetry.lock": { ecosystem: "PyPI", read: readPoetryLock },
+    "gradle.lockfile": { ecosystem: "Maven", read: readGradleLockfile },
+};
+export const FORMAT_NAMES = Object.keys(FORMATS);
+// Files that hold ranges or unselected versions, not what was installed: the file to pass instead.
+const REFUSED = {
+    "package.json": "package.json holds version ranges, not installed versions: pass package-lock.json or npm-shrinkwrap.json",
+    "pyproject.toml": "pyproject.toml holds version ranges, not installed versions: pass poetry.lock, or a requirements.txt of == pins (pip freeze)",
+    pipfile: "Pipfile holds version ranges, not installed versions: pass a requirements.txt of == pins (pipenv requirements)",
+    gemfile: "Gemfile holds version ranges, not installed versions: pass Gemfile.lock",
+    "gems.rb": "gems.rb holds version ranges, not installed versions: pass gems.locked",
+    "cargo.toml": "Cargo.toml holds version ranges, not installed versions: pass Cargo.lock",
+    "composer.json": "composer.json holds version ranges, not installed versions: pass composer.lock",
+    "build.gradle": "build.gradle declares dependencies, not the versions resolved: pass gradle.lockfile (gradle dependencies --write-locks)",
+    "build.gradle.kts": "build.gradle.kts declares dependencies, not the versions resolved: pass gradle.lockfile (gradle dependencies --write-locks)",
+    "go.sum": "go.sum is refused: it lists every module version the module graph mentions, not the version the build selects: pass go.mod",
+    "go.work": "go.work names workspace modules, not dependency versions: pass each module's go.mod",
+    // Not read yet (#2835's deferred list).
+    "pom.xml": "pom.xml is not read: its versions need the effective POM (parents, properties, dependencyManagement), which this tool does not build",
+    "yarn.lock": "yarn.lock is not read yet",
+    "pnpm-lock.yaml": "pnpm-lock.yaml is not read yet",
+    "pipfile.lock": "Pipfile.lock is not read yet: pass a requirements.txt of == pins (pipenv requirements)",
+};
+const basename = (f) => f.replace(/\\/g, "/").split("/").pop() ?? f;
+// The format a filename names, or why it names none.
+export function detect(filename) {
+    const base = basename(filename.trim());
+    const lower = base.toLowerCase();
+    if (lower === "go.mod")
+        return { format: "go.mod" };
+    if (lower === "package-lock.json" || lower === "npm-shrinkwrap.json")
+        return { format: "package-lock.json" };
+    if (lower === "cargo.lock")
+        return { format: "Cargo.lock" };
+    if (lower === "gemfile.lock" || lower === "gems.locked")
+        return { format: "Gemfile.lock" };
+    if (lower === "composer.lock")
+        return { format: "composer.lock" };
+    if (lower === "poetry.lock")
+        return { format: "poetry.lock" };
+    // gradle.lockfile, buildscript-gradle.lockfile, and the older per-configuration
+    // gradle/dependency-locks/<configuration>.lockfile.
+    if (lower.endsWith(".lockfile"))
+        return { format: "gradle.lockfile" };
+    if (lower.endsWith(".txt") && /requirements|constraints/.test(lower))
+        return { format: "requirements.txt" };
+    if (REFUSED[lower])
+        return { refused: REFUSED[lower] };
+    return { refused: `${base || "(no filename)"} is not a file name this tool reads; the formats read are ${FORMAT_NAMES.join(", ")} (and npm-shrinkwrap.json, gems.locked): name the file so, or set its format` };
+}
+// One file read, or why it could not be.
+export function readFile(format, content) {
+    try {
+        // A byte-order mark, which some Windows editors write, is not part of the file's text.
+        return FORMATS[format].read(content.replace(/^\uFEFF/, ""));
+    }
+    catch (e) {
+        if (e instanceof Unreadable)
+            return { unreadable: `it ${e.message}` };
+        throw e;
+    }
+}

package/dist/tools/manifests/lockfiles.js

@@ -0,0 +1,176 @@
+// The resolved-version lockfiles of Rust, Python (Poetry), Ruby, PHP and Gradle (#2835). Each
+// entry is one package at one version as the tool that wrote the file resolved it; entries from a
+// local path or a VCS checkout are listed, not checked.
+//
+//   Cargo.lock (v1 to v4)  [[package]] tables read as TOML, never by pairing a name line with the
+//                          next version line (docs/SBOM_COVERAGE_PROGRAM.md row 46): a source of
+//                          the crates.io index (registry+https://github.com/rust-lang/crates.io-index
+//                          or sparse+https://index.crates.io/) is checked; no source is a workspace
+//                          member or path crate (local_path); git+ is vcs_source; another registry
+//                          unsupported_line.
+//   poetry.lock            [[package]] tables read as TOML; a [package.source] of type git is
+//                          vcs_source, directory or file local_path, url unsupported_line; a legacy
+//                          (private index) source is checked as PyPI.
+//   Gemfile.lock           Bundler's sections read by indentation: each spec line (four spaces,
+//                          name (version)) of a GEM section is checked, its platform suffix
+//                          stripped (nokogiri (1.15.4-x86_64-linux) is nokogiri 1.15.4); a PATH
+//                          section's specs are local_path and a GIT section's vcs_source.
+//   composer.lock          packages and packages-dev, each version's leading v stripped
+//                          (v6.4.1 is 6.4.1); a branch version (dev-main, 2.x-dev) is
+//                          version_unresolved; a dist of type path local_path.
+//   gradle.lockfile        group:artifact:version=configurations lines (and the older
+//                          per-configuration lockfiles' group:artifact:version); empty= lists the
+//                          configurations with no dependency, and is skipped.
+import { Unreadable, emptyParsed, isObj, pep503, purlOf, seg, specOf, usableVersion } from "./common.js";
+import { readToml } from "./toml.js";
+// [[package]] tables of a TOML lockfile, each with its header's line.
+function packagesOf(text) {
+    const { root, lines } = readToml(text);
+    const pkgs = root.package;
+    if (pkgs === undefined)
+        return [];
+    if (!Array.isArray(pkgs))
+        throw new Unreadable("has a package key that is not an array of [[package]] tables");
+    return pkgs.filter(isObj).map((t) => ({ t: t, line: lines.get(t) ?? null }));
+}
+const CRATES_IO = new Set(["registry+https://github.com/rust-lang/crates.io-index", "sparse+https://index.crates.io/"]);
+export function readCargoLock(text) {
+    const p = emptyParsed();
+    for (const { t, line } of packagesOf(text)) {
+        const name = typeof t.name === "string" ? t.name : null;
+        const version = typeof t.version === "string" ? t.version : undefined;
+        const src = typeof t.source === "string" ? t.source : undefined;
+        const miss = (reason, detail) => p.not_checked.push({ name, spec: specOf(`${name ?? "?"} ${version ?? ""}${src ? ` (${src})` : ""}`), reason, line, detail });
+        if (!name || !usableVersion(version))
+            miss("version_unresolved", "the [[package]] table names no package and version");
+        else if (src === undefined)
+            miss("local_path", "no source: a workspace member or path dependency, not a crates.io release");
+        else if (src.startsWith("git+"))
+            miss("vcs_source", "a git dependency, whose code need not match the crates.io release of the same version");
+        else if (!CRATES_IO.has(src))
+            miss("unsupported_line", "from a registry other than crates.io, whose crates need not be the crates.io crates of the same name");
+        else
+            p.pinned.push({ purl: purlOf("cargo", name, version), line });
+    }
+    return p;
+}
+export function readPoetryLock(text) {
+    const p = emptyParsed();
+    for (const { t, line } of packagesOf(text)) {
+        const name = typeof t.name === "string" ? t.name : null;
+        const version = typeof t.version === "string" ? t.version : undefined;
+        const source = isObj(t.source) ? t.source : null;
+        const type = source && typeof source.type === "string" ? source.type : null;
+        const miss = (reason, detail) => p.not_checked.push({ name, spec: specOf(`${name ?? "?"} ${version ?? ""}${type ? ` (source ${type})` : ""}`), reason, line, detail });
+        if (!name || !usableVersion(version))
+            miss("version_unresolved", "the [[package]] table names no package and version");
+        else if (type === "git")
+            miss("vcs_source", "a git dependency, whose code need not match the PyPI release of the same version");
+        else if (type === "directory" || type === "file")
+            miss("local_path", `a local ${type}, not a PyPI release`);
+        else if (type === "url")
+            miss("unsupported_line", "installed from a URL, not a PyPI release");
+        else
+            p.pinned.push({ purl: purlOf("pypi", pep503(name), version), line });
+    }
+    return p;
+}
+export function readGemfileLock(text) {
+    const p = emptyParsed();
+    let section = null;
+    let inSpecs = false;
+    text.split(/\r?\n/).forEach((raw, i) => {
+        const line = i + 1;
+        if (raw.trim() === "")
+            return;
+        if (!/^\s/.test(raw)) {
+            section = raw.trim();
+            inSpecs = false;
+            return;
+        }
+        if (/^ {2}specs:\s*$/.test(raw)) {
+            inSpecs = true;
+            return;
+        }
+        if (/^ {2}\S/.test(raw)) {
+            inSpecs = false;
+            return;
+        }
+        // A spec: four spaces, then name (version). Six spaces is one of its own requirements.
+        if (!inSpecs || !/^ {4}\S/.test(raw))
+            return;
+        const m = /^ {4}([^\s(]+) \(([^)]+)\)\s*$/.exec(raw);
+        const miss = (name, reason, detail) => p.not_checked.push({ name, spec: specOf(raw), reason, line, detail });
+        if (!m)
+            return miss(null, "unsupported_line", "a spec line this reader cannot read (name (version))");
+        const [, name, full] = m;
+        // RubyGems versions carry no '-': what follows the first one is the platform.
+        const version = full.split("-")[0];
+        if (section === "PATH")
+            return miss(name, "local_path", "a gem from a local path (PATH section), not a RubyGems release");
+        if (section === "GIT")
+            return miss(name, "vcs_source", "a gem from a git repository (GIT section), whose code need not match the RubyGems release of the same version");
+        if (section !== "GEM")
+            return miss(name, "unsupported_line", `a gem from a ${section ?? "unnamed"} section, not a RubyGems source`);
+        if (!usableVersion(version))
+            return miss(name, "version_unresolved", "the spec carries no version");
+        p.pinned.push({ purl: purlOf("gem", name, version), line });
+    });
+    return p;
+}
+export function readComposerLock(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        throw new Unreadable("is not JSON");
+    }
+    if (!isObj(doc))
+        throw new Unreadable("is not a JSON object");
+    if (!Array.isArray(doc.packages) && !Array.isArray(doc["packages-dev"]))
+        throw new Unreadable("has neither a packages nor a packages-dev list");
+    const p = emptyParsed();
+    for (const list of ["packages", "packages-dev"]) {
+        const pkgs = doc[list];
+        if (!Array.isArray(pkgs))
+            continue;
+        for (const e of pkgs) {
+            if (!isObj(e))
+                continue;
+            const name = typeof e.name === "string" ? e.name : null;
+            const raw = typeof e.version === "string" ? e.version : undefined;
+            const miss = (reason, detail) => p.not_checked.push({ name, spec: specOf(`${list}: ${name ?? "?"} ${raw ?? ""}`), reason, line: null, detail });
+            const dist = isObj(e.dist) ? e.dist : null;
+            if (!name || !usableVersion(raw))
+                miss("version_unresolved", "the entry names no package and version");
+            else if (dist && dist.type === "path")
+                miss("local_path", "installed from a local path, not a Packagist release");
+            else if (/^dev-|-dev$/.test(raw))
+                miss("version_unresolved", "a branch, not a released version");
+            else
+                p.pinned.push({ purl: purlOf("composer", name, raw.replace(/^v(?=\d)/, "")), line: null });
+        }
+    }
+    return p;
+}
+export function readGradleLockfile(text) {
+    const p = emptyParsed();
+    text.split(/\r?\n/).forEach((raw, i) => {
+        const l = raw.trim();
+        if (l === "" || l.startsWith("#"))
+            return;
+        if (/^empty=/.test(l))
+            return;
+        const coords = l.split("=")[0];
+        const m = /^([^:\s]+):([^:\s]+):([^:\s]+)$/.exec(coords);
+        if (!m) {
+            p.not_checked.push({ name: null, spec: specOf(raw), reason: "unsupported_line", line: i + 1, detail: "not a group:artifact:version line" });
+            return;
+        }
+        const [, group, artifact, version] = m;
+        // purl-spec maven: the group is the namespace, the artifact the name.
+        p.pinned.push({ purl: `pkg:maven/${seg(group)}/${seg(artifact)}@${seg(version)}`, line: i + 1 });
+    });
+    return p;
+}

package/dist/tools/manifests/npmlock.js

@@ -0,0 +1,107 @@
+// package-lock.json and npm-shrinkwrap.json (#2835), lockfileVersion 1, 2 and 3, read as JSON
+// (docs.npmjs.com/cli/v10/configuring-npm/package-lock-json).
+//
+// Version 2 and 3 files hold `packages`, keyed by install path: the package's name is what follows
+// the last "node_modules/" in the key, or the entry's own name where it has one (an alias,
+// "lodash-latest": "npm:lodash@4.17.21", installs lodash under another folder name). The root
+// entry ("") is the project itself and is skipped and counted; a key outside node_modules is a
+// workspace member, and a `link: true` entry a symlink to one: local_path. Version 1 files hold
+// only `dependencies`, a tree keyed by name; version 2 files hold both, and `packages` is read.
+// The same installed tree gives the same purls in all three.
+//
+// An entry installed from git (resolved git+…, or a v1 version that is a git URL) is vcs_source;
+// from a directory or file (file:…) local_path; from a tarball URL unsupported_line; an entry
+// without a version version_unresolved. Each is listed, never sent.
+import { Unreadable, emptyParsed, isObj, purlOf, specOf, usableVersion } from "./common.js";
+const NM = "node_modules/";
+const GIT = /^(git(\+[a-z]+)?:|github:|gitlab:|bitbucket:|gist:)/i;
+// Where an entry was installed from, when not the registry.
+function source(s) {
+    if (!s)
+        return null;
+    if (GIT.test(s) || /^[\w.-]+\/[\w.-]+(#.*)?$/.test(s))
+        return { reason: "vcs_source", detail: "installed from a git repository, whose code need not match the npm release of the same version" };
+    if (/^(file:|link:|\.{1,2}\/|\/)/.test(s))
+        return { reason: "local_path", detail: "installed from a local directory or file, not an npm release" };
+    if (/^https?:\/\//i.test(s) && !/\/-\/[^/]+\.tgz$/.test(s))
+        return { reason: "unsupported_line", detail: "installed from a tarball URL that is not a registry release" };
+    return null;
+}
+export function readNpmLock(text) {
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    }
+    catch {
+        throw new Unreadable("is not JSON");
+    }
+    if (!isObj(doc))
+        throw new Unreadable("is not a JSON object");
+    const p = emptyParsed();
+    const lv = doc.lockfileVersion;
+    if (isObj(doc.packages)) {
+        for (const [key, e] of Object.entries(doc.packages)) {
+            if (key === "") {
+                p.skipped++;
+                continue;
+            }
+            const at = key.lastIndexOf(NM);
+            const folder = at >= 0 ? key.slice(at + NM.length) : null;
+            const entry = isObj(e) ? e : {};
+            const name = typeof entry.name === "string" && entry.name ? entry.name : (folder ?? key);
+            const version = typeof entry.version === "string" ? entry.version : undefined;
+            const miss = (reason, detail) => p.not_checked.push({ name, spec: specOf(`${key}${version ? ` ${version}` : ""}`), reason, line: null, detail });
+            if (folder === null) {
+                miss("local_path", "a workspace member of this project, not an npm release");
+                continue;
+            }
+            if (entry.link === true) {
+                miss("local_path", `a link to ${typeof entry.resolved === "string" ? entry.resolved : "a local directory"}, not an npm release`);
+                continue;
+            }
+            const src = source(typeof entry.resolved === "string" ? entry.resolved : undefined);
+            if (src) {
+                miss(src.reason, src.detail);
+                continue;
+            }
+            if (!usableVersion(version) || !name) {
+                miss("version_unresolved", "the entry carries no version");
+                continue;
+            }
+            p.pinned.push({ purl: purlOf("npm", name, version), line: null });
+        }
+        return p;
+    }
+    if (lv !== undefined && lv !== 1)
+        throw new Unreadable(`has lockfileVersion ${JSON.stringify(lv)} and no packages object`);
+    // Version 1: the dependencies tree, each node's own dependencies nested below it.
+    const walk = (deps, at, depth) => {
+        if (!isObj(deps))
+            return;
+        if (depth > 64)
+            throw new Unreadable("nests its dependencies deeper than 64 levels");
+        for (const [key, e] of Object.entries(deps)) {
+            const entry = isObj(e) ? e : {};
+            const path = `${at}${NM}${key}`;
+            let name = key;
+            let version = typeof entry.version === "string" ? entry.version : undefined;
+            // An alias: "npm:real-name@1.2.3".
+            const alias = version ? /^npm:((?:@[^/@]+\/)?[^@]+)@(.+)$/.exec(version) : null;
+            if (alias)
+                [, name, version] = alias;
+            const miss = (reason, detail) => p.not_checked.push({ name, spec: specOf(`${path}${version ? ` ${version}` : ""}`), reason, line: null, detail });
+            const src = source(version) ?? source(typeof entry.resolved === "string" ? entry.resolved : undefined);
+            if (src)
+                miss(src.reason, src.detail);
+            else if (!usableVersion(version))
+                miss("version_unresolved", "the entry carries no version");
+            else
+                p.pinned.push({ purl: purlOf("npm", name, version), line: null });
+            walk(entry.dependencies, `${path}/`, depth + 1);
+        }
+    };
+    if (!isObj(doc.dependencies))
+        throw new Unreadable("has neither a packages nor a dependencies object");
+    walk(doc.dependencies, "", 0);
+    return p;
+}

package/dist/tools/manifests/requirements.js

@@ -0,0 +1,125 @@
+// requirements.txt (#2835): pip's requirements file format
+// (pip.pypa.io/en/stable/reference/requirements-file-format/), each requirement a PEP 508
+// specifier (packaging.python.org/en/latest/specifications/dependency-specifiers/).
+//
+// Only a requirement pinned to one version by a single == or === clause gives a version
+// (django==4.2.7). A range (django>=4, ~=4.2, a == with a wildcard such as ==1.4.*, or several
+// clauses) is version_unpinned and its bound is never sent as a version: pkg:pypi/django@4 would
+// be checked as if 4 were installed. Extras ([bcrypt]) and environment markers (; python_version
+// < "3.8") are stripped; per-requirement options (--hash) are ignored. -r and -c name another
+// file, which is not read here (unsupported_line: pass it as its own file); -e, a direct URL
+// (name @ https://…) and a bare path or URL are vcs_source, local_path or unsupported_line. Global
+// options (--index-url and the rest) are not dependencies and are not counted.
+import { emptyParsed, pep503, purlOf, specOf, usableVersion } from "./common.js";
+// The logical lines: comments removed (a line starting with #, or whitespace then #), a trailing
+// backslash joining the next line, each with the 1-based number of its first physical line.
+function logicalLines(text) {
+    const out = [];
+    let buf = "";
+    let start = 0;
+    text.split(/\r?\n/).forEach((raw, i) => {
+        if (buf === "")
+            start = i + 1;
+        let l = raw;
+        if (/^\s*#/.test(l))
+            l = "";
+        else
+            l = l.replace(/\s#.*$/, "");
+        if (/\\$/.test(l)) {
+            buf += l.slice(0, -1) + " ";
+            return;
+        }
+        buf += l;
+        if (buf.trim())
+            out.push({ text: buf.trim(), line: start });
+        buf = "";
+    });
+    if (buf.trim())
+        out.push({ text: buf.trim(), line: start });
+    return out;
+}
+const VCS = /^(git|hg|svn|bzr)\+/i;
+const URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+// A local archive or path: pip installs it from the file, not from the index.
+const LOCAL = /^(\.{1,2}([\\/]|$)|[\\/]|~|[A-Za-z]:[\\/]|file:)|\.(whl|tar\.gz|tgz|zip|tar\.bz2)$/i;
+// Where a non-registry source points: VCS, a local path, or another URL.
+function sourceReason(target) {
+    if (VCS.test(target))
+        return { reason: "vcs_source", detail: "a VCS checkout, whose code need not match the PyPI release of the same version" };
+    if (/^file:/i.test(target) || !URL.test(target))
+        return { reason: "local_path", detail: "a local path or archive, not a PyPI release" };
+    return { reason: "unsupported_line", detail: "a direct URL, not a PyPI release" };
+}
+const NAME = /^([A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?)\s*(\[[^\]]*\])?\s*(.*)$/s;
+const CLAUSE = /^(===|==|!=|~=|<=|>=|<|>)\s*(\S+)$/;
+// Per-requirement options pip takes after a specifier: not part of it.
+const PER_REQUIREMENT = /\s--?(hash|global-option|install-option|config-settings)\b.*$/s;
+export function readRequirements(text) {
+    const p = emptyParsed();
+    for (const { text: l, line } of logicalLines(text)) {
+        const miss = (name, reason, detail) => p.not_checked.push({ name, spec: specOf(l), reason, line, detail });
+        if (l.startsWith("-")) {
+            const m = /^(-[a-zA-Z]|--[a-z-]+)(?:\s*=\s*|\s+)?(.*)$/s.exec(l);
+            const opt = m?.[1] ?? l;
+            const value = (m?.[2] ?? "").trim();
+            if (["-r", "--requirement", "-c", "--constraint"].includes(opt)) {
+                miss(null, "unsupported_line", `names another file (${opt}), which this tool does not read from here: pass that file's text as its own entry in files`);
+            }
+            else if (["-e", "--editable"].includes(opt)) {
+                const s = sourceReason(value);
+                miss(/[#&]egg=([A-Za-z0-9._-]+)/.exec(value)?.[1] ?? null, s.reason, `an editable install: ${s.detail}`);
+            }
+            // Any other option (--index-url, --hash on a line of its own, …) names no dependency.
+            continue;
+        }
+        const spec = l.replace(PER_REQUIREMENT, "").trim();
+        // A bare path, archive or URL; "name @ url" is a named requirement, read below.
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*\s*(\[[^\]]*\])?\s*@/.test(spec) && (VCS.test(spec) || URL.test(spec) || LOCAL.test(spec))) {
+            const s = sourceReason(spec);
+            miss(/[#&]egg=([A-Za-z0-9._-]+)/.exec(spec)?.[1] ?? null, s.reason, s.detail);
+            continue;
+        }
+        // A marker follows ';'; it does not change which version is pinned.
+        const req = spec.split(";")[0].trim();
+        const m = NAME.exec(req);
+        if (!m) {
+            miss(null, "unsupported_line", "not a requirement specifier this reader takes (PEP 508 name, then a version specifier)");
+            continue;
+        }
+        const name = m[1];
+        let rest = m[3].trim();
+        if (rest.startsWith("@")) {
+            const s = sourceReason(rest.slice(1).trim());
+            miss(name, s.reason, s.detail);
+            continue;
+        }
+        if (rest.startsWith("(") && rest.endsWith(")"))
+            rest = rest.slice(1, -1).trim();
+        if (rest === "") {
+            miss(name, "version_unpinned", "no version is given, so any release may be installed");
+            continue;
+        }
+        const clauses = rest.split(",").map((c) => c.trim()).filter(Boolean);
+        const parsed = clauses.map((c) => CLAUSE.exec(c));
+        if (parsed.some((c) => c === null)) {
+            miss(name, "unsupported_line", "a version specifier this reader cannot read");
+            continue;
+        }
+        const only = parsed.length === 1 ? parsed[0] : null;
+        const pinned = only && (only[1] === "==" || only[1] === "===") ? only[2] : null;
+        if (pinned === null || pinned.includes("*")) {
+            miss(name, "version_unpinned", "a range, not one version: pip may install any release it allows, so none is checked");
+            continue;
+        }
+        if (pinned.includes("$")) {
+            miss(name, "version_unresolved", "the version is an environment variable, which this tool does not expand");
+            continue;
+        }
+        if (!usableVersion(pinned)) {
+            miss(name, "unsupported_line", "the pinned version cannot be read");
+            continue;
+        }
+        p.pinned.push({ purl: purlOf("pypi", pep503(name), pinned), line });
+    }
+    return p;
+}