@pi-harness/pi-harness 0.1.13 → 0.1.14

package/node_modules/@pi-harness/core/dist/plugins/dependency-checker.js

@@ -1,9 +1,46 @@
-import { readdir, readFile, stat } from "node:fs/promises";
-import { basename, dirname, join, relative } from "node:path";
+import { opendir, realpath, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
+import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
-import { resolveExistingWorkspacePath } from "../workspace-path.js";
-function conflictList(entries) {
+import { minVersion, Range, valid as validSemver, validRange } from "semver";
+import { BoundedFileSizeError, BoundedFileTypeError, readBoundedTextFile } from "../bounded-file.js";
+import { assertKnownConfigKeys } from "../config.js";
+import { isPathInside, resolveExistingWorkspacePath } from "../workspace-path.js";
+const maxManifestBytes = 1024 * 1024;
+const maxManifestPathLength = 1_024;
+const maxDependencyDeclarations = 2_000;
+const maxPythonConstraintsPerPackage = 64;
+const maxConstraintLength = 4_096;
+const maxPythonDependencyNameLength = 256;
+const maxPythonEnvironmentEntries = 4_096;
+const maxNpmConstraintAlternatives = 256;
+const maxPythonConstraintAlternatives = 256;
+export const Config = z.object({});
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function throwIfCancelled(signal) {
+    if (!signal?.aborted)
+        return;
+    throw signal.reason instanceof Error
+        ? new Error(signal.reason.message, { cause: signal.reason })
+        : new Error("Dependency check was cancelled", { cause: signal.reason });
+}
+function cloneDependencyReport(report) {
+    return {
+        ...report,
+        missing: [...report.missing],
+        optionalMissing: [...report.optionalMissing],
+        invalid: [...report.invalid],
+        conflicts: report.conflicts.map((conflict) => ({ name: conflict.name, constraints: [...conflict.constraints] })),
+        unresolved: report.unresolved.map((conflict) => ({ name: conflict.name, constraints: [...conflict.constraints] })),
+    };
+}
+function normalizePythonDistributionName(name) {
+    return name.toLowerCase().replace(/[-_.]+/gu, "-");
+}
+function constraintGroups(entries) {
     const grouped = new Map();
     for (const entry of entries) {
         const values = grouped.get(entry.name) ?? [];
@@ -11,101 +48,328 @@ function conflictList(entries) {
             values.push(entry.constraint);
         grouped.set(entry.name, values);
     }
-    return [...grouped.entries()].filter(([, constraints]) => constraintsConflict(constraints)).map(([name, constraints]) => ({ name, constraints }));
-}
-function numericVersion(value) {
-    const match = /^v?(\d+(?:\.\d+){0,3})(?:[-+].*)?$/u.exec(value.trim());
-    return match?.[1]?.split(".").map(Number);
+    return [...grouped.entries()].map(([name, constraints]) => ({ name, constraints }));
 }
-function compareVersions(left, right) {
-    for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
-        const difference = (left[index] ?? 0) - (right[index] ?? 0);
-        if (difference !== 0)
-            return Math.sign(difference);
+function npmConstraintsConflict(constraints) {
+    const ranges = constraints.flatMap((constraint) => {
+        const range = validRange(constraint);
+        return range === null ? [] : [range];
+    });
+    let intersections = [[]];
+    for (const range of ranges) {
+        const next = new Map();
+        for (const current of intersections) {
+            for (const comparatorSet of new Range(range).set) {
+                const combined = [...current, ...comparatorSet.map((comparator) => comparator.value).filter((value) => value !== "")];
+                if (minVersion(combined.join(" ")) === null)
+                    continue;
+                const key = [...combined].sort().join("\0");
+                next.set(key, combined);
+                if (next.size > maxNpmConstraintAlternatives)
+                    throw new Error(`npm constraint analysis exceeds the ${maxNpmConstraintAlternatives}-alternative limit`);
+            }
+        }
+        intersections = [...next.values()];
+        if (intersections.length === 0)
+            return true;
     }
-    return 0;
+    return false;
 }
-function constraintAllows(constraint, version) {
-    const parts = constraint
-        .split(",")
-        .map((part) => part.trim())
-        .filter(Boolean);
-    return parts.every((part) => {
-        const match = /^(===|==|=|>=|<=|>|<|\^|~)?\s*(v?\d+(?:\.\d+){0,3}(?:[-+][^\s]+)?)$/u.exec(part);
+function pythonSpecifierAlternatives(constraint) {
+    const set = constraint.trim();
+    if (set === "")
+        return ["*"];
+    let alternatives = [""];
+    for (const specifier of set.split(",").map((part) => part.trim())) {
+        const match = /^(===|==|!=|~=|>=|<=|>|<)\s*(\d+(?:\.\d+){0,2})(\.\*)?$/u.exec(specifier);
         if (match === null)
+            return undefined;
+        const operator = match[1];
+        const release = match[2].split(".").map(Number);
+        if (release.some((part) => !Number.isSafeInteger(part)))
+            return undefined;
+        const version = [...release, 0, 0].slice(0, 3).join(".");
+        if (validSemver(version) === null)
+            return undefined;
+        let options;
+        if (match[3] !== undefined) {
+            if ((operator !== "==" && operator !== "!=") || release.length > 2)
+                return undefined;
+            const upper = release.length === 1 ? `${release[0] + 1}.0.0` : `${release[0]}.${release[1] + 1}.0`;
+            if (validSemver(upper) === null)
+                return undefined;
+            options = operator === "==" ? [`>=${version} <${upper}`] : [`<${version}`, `>=${upper}`];
+        }
+        else if (operator === "!=") {
+            options = [`<${version}`, `>${version}`];
+        }
+        else if (operator === "~=") {
+            if (release.length < 2)
+                return undefined;
+            const upper = release.length === 2 ? `${release[0] + 1}.0.0` : `${release[0]}.${release[1] + 1}.0`;
+            if (validSemver(upper) === null)
+                return undefined;
+            options = [`>=${version} <${upper}`];
+        }
+        else {
+            options = [`${operator === "==" || operator === "===" ? "=" : operator}${version}`];
+        }
+        alternatives = alternatives.flatMap((current) => options.map((option) => `${current} ${option}`.trim()));
+        if (alternatives.length > 32)
+            return undefined;
+    }
+    return alternatives;
+}
+function pythonConstraintsConflict(constraints) {
+    let intersections = [""];
+    for (const constraint of constraints) {
+        const alternatives = pythonSpecifierAlternatives(constraint);
+        if (alternatives === undefined)
+            return false;
+        const next = new Map();
+        for (const current of intersections) {
+            for (const alternative of alternatives) {
+                const combined = `${current} ${alternative}`.trim();
+                if (minVersion(combined) === null)
+                    continue;
+                const key = combined.split(/\s+/u).sort().join("\0");
+                next.set(key, combined);
+                if (next.size > maxPythonConstraintAlternatives)
+                    throw new Error(`Python constraint analysis exceeds the ${maxPythonConstraintAlternatives}-alternative limit`);
+            }
+        }
+        intersections = [...next.values()];
+        if (intersections.length === 0)
             return true;
-        const candidate = numericVersion(match[2] ?? "");
-        if (candidate === undefined)
-            return true;
-        const comparison = compareVersions(version, candidate);
-        switch (match[1] ?? "=") {
-            case ">=":
-                return comparison >= 0;
-            case "<=":
-                return comparison <= 0;
-            case ">":
-                return comparison > 0;
-            case "<":
-                return comparison < 0;
-            case "^":
-                return (comparison >= 0 &&
-                    version[0] === candidate[0] &&
-                    ((candidate[0] ?? 0) > 0 || (version[1] === candidate[1] && ((candidate[1] ?? 0) > 0 || version[2] === candidate[2]))));
-            case "~":
-                return comparison >= 0 && version[0] === candidate[0] && version[1] === candidate[1];
-            default:
-                return comparison === 0;
+    }
+    return false;
+}
+function npmPackagePath(name) {
+    if (name.length === 0 || name.length > 214)
+        return undefined;
+    const segment = /^[A-Za-z0-9][A-Za-z0-9._~-]*$/u;
+    if (name.startsWith("@")) {
+        const parts = name.slice(1).split("/");
+        return parts.length === 2 && parts.every((part) => segment.test(part)) ? [`@${parts[0]}`, parts[1]] : undefined;
+    }
+    return segment.test(name) ? [name] : undefined;
+}
+function npmDependencyEntries(record) {
+    const entries = [];
+    const optionalPeers = new Set();
+    const peerMetadata = record.peerDependenciesMeta;
+    if (peerMetadata !== undefined) {
+        if (!isRecord(peerMetadata))
+            throw new Error("Manifest peerDependenciesMeta must be an object");
+        for (const [name, metadata] of Object.entries(peerMetadata)) {
+            if (!isRecord(metadata) || (metadata.optional !== undefined && typeof metadata.optional !== "boolean"))
+                throw new Error("Manifest peerDependenciesMeta entries must be objects with an optional boolean optional property");
+            if (metadata.optional === true)
+                optionalPeers.add(name);
         }
-    });
+    }
+    for (const section of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+        const value = record[section];
+        if (value === undefined)
+            continue;
+        if (!isRecord(value))
+            throw new Error(`Manifest dependency section ${section} must be an object`);
+        for (const [name, constraint] of Object.entries(value)) {
+            if (typeof constraint !== "string" || constraint.length > maxConstraintLength)
+                throw new Error(`Manifest dependency constraints must be strings of at most ${maxConstraintLength} characters`);
+            if (/[\p{Cc}\p{Cf}\p{Cs}]/u.test(constraint))
+                throw new Error("Dependency constraint cannot contain Unicode control characters");
+            entries.push({ name, constraint, optional: section === "optionalDependencies" || (section === "peerDependencies" && optionalPeers.has(name)) });
+        }
+    }
+    return entries;
 }
-function constraintsConflict(constraints) {
-    if (constraints.length < 2)
-        return false;
-    const pinned = constraints.flatMap((constraint) => {
-        const match = /^(?:===|==|=)?\s*(v?\d+(?:\.\d+){0,3}(?:[-+][^\s]+)?)$/u.exec(constraint);
-        const version = match === null ? undefined : numericVersion(match[1] ?? "");
-        return version === undefined ? [] : [version];
-    });
-    if (pinned.length === 0)
-        return false;
-    return pinned.some((version) => constraints.some((constraint) => !constraintAllows(constraint, version)));
+function truncateCodePoints(value, maximum) {
+    const codePoints = [...value];
+    return codePoints.length > maximum ? codePoints.slice(0, maximum).join("") : value;
+}
+function sanitizedRequirementDiagnostic(value) {
+    return truncateCodePoints(value.replaceAll(/[\p{Cc}\p{Cf}\p{Cs}]+/gu, " ").trim(), maxPythonDependencyNameLength).trimEnd();
+}
+function sanitizedNpmNameDiagnostic(value) {
+    const cleaned = truncateCodePoints(value.replaceAll(/[\p{Cc}\p{Cf}\p{Cs}]+/gu, " ").trim(), maxPythonDependencyNameLength).trimEnd();
+    return cleaned === "" ? "(invalid dependency name)" : cleaned;
+}
+function hasUnsafeRequirementCharacter(value) {
+    for (const character of value) {
+        if (/[\p{Cf}\p{Cs}]/u.test(character))
+            return true;
+        const codePoint = character.codePointAt(0);
+        if (codePoint !== undefined && ((codePoint <= 0x1f && codePoint !== 0x09) || (codePoint >= 0x7f && codePoint <= 0x9f)))
+            return true;
+    }
+    return false;
 }
 export function parseRequirements(source) {
     const entries = [];
+    const invalid = [];
     for (const rawLine of source.split("\n")) {
         const line = rawLine.trim();
-        if (line === "" || line.startsWith("#") || line.startsWith("-") || line.startsWith("git+") || line.startsWith("http://") || line.startsWith("https://"))
+        if (line === "" || line.startsWith("#"))
+            continue;
+        if (hasUnsafeRequirementCharacter(line)) {
+            invalid.push(sanitizedRequirementDiagnostic(line));
+            if (entries.length + invalid.length > maxDependencyDeclarations)
+                throw new Error(`Dependency manifest exceeds the ${maxDependencyDeclarations}-dependency scan limit`);
             continue;
+        }
+        if (line.startsWith("-") || line.startsWith("git+") || line.startsWith("http://") || line.startsWith("https://")) {
+            invalid.push(sanitizedRequirementDiagnostic(line));
+            if (entries.length + invalid.length > maxDependencyDeclarations)
+                throw new Error(`Dependency manifest exceeds the ${maxDependencyDeclarations}-dependency scan limit`);
+            continue;
+        }
         const match = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]+\])?\s*(.*)$/u.exec(line);
-        if (!match)
+        if (!match) {
+            invalid.push(sanitizedRequirementDiagnostic(line));
+            if (entries.length + invalid.length > maxDependencyDeclarations)
+                throw new Error(`Dependency manifest exceeds the ${maxDependencyDeclarations}-dependency scan limit`);
             continue;
-        const name = match[1].toLowerCase().replaceAll("_", "-");
-        entries.push({ name, constraint: match[2]?.trim() ?? "" });
+        }
+        if (match[1].length > maxPythonDependencyNameLength)
+            throw new Error(`Python dependency name exceeds the ${maxPythonDependencyNameLength}-character limit`);
+        const name = normalizePythonDistributionName(match[1]);
+        const constraint = match[2]?.trim() ?? "";
+        if (constraint.length > maxConstraintLength)
+            throw new Error(`Python dependency ${name} constraint exceeds the ${maxConstraintLength}-character limit`);
+        entries.push({ name, constraint });
+        if (entries.length + invalid.length > maxDependencyDeclarations)
+            throw new Error(`Dependency manifest exceeds the ${maxDependencyDeclarations}-dependency scan limit`);
+    }
+    const constraintCounts = new Map();
+    for (const entry of entries) {
+        const constraints = constraintCounts.get(entry.name) ?? new Set();
+        constraints.add(entry.constraint);
+        if (constraints.size > maxPythonConstraintsPerPackage)
+            throw new Error(`Python dependency ${entry.name} exceeds the ${maxPythonConstraintsPerPackage}-constraint analysis limit`);
+        constraintCounts.set(entry.name, constraints);
     }
     const names = [...new Set(entries.map((entry) => entry.name))];
-    return { names, constraints: conflictList(entries) };
-}
-async function installedPythonPackage(workspace, name) {
-    const normalized = name.toLowerCase().replaceAll("-", "_");
-    for (const environment of [".venv", "venv"]) {
-        const lib = join(workspace, environment, "lib");
-        const versions = await readdir(lib, { withFileTypes: true }).catch(() => []);
-        for (const version of versions) {
-            if (!version.isDirectory() || !version.name.startsWith("python"))
+    const groups = constraintGroups(entries);
+    const unresolved = groups.filter((group) => group.constraints.some((constraint) => pythonSpecifierAlternatives(constraint) === undefined));
+    const unresolvedNames = new Set(unresolved.map((group) => group.name));
+    const constraints = groups.filter((group) => !unresolvedNames.has(group.name) && pythonConstraintsConflict(group.constraints));
+    return { names, constraints, unresolved, invalid };
+}
+async function canonicalDirectoryInside(workspace, directory, signal) {
+    throwIfCancelled(signal);
+    let canonical;
+    try {
+        canonical = await realpath(directory);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+            return undefined;
+        throw new Error("Could not inspect the local Python environment", { cause: error });
+    }
+    throwIfCancelled(signal);
+    return isPathInside(workspace, canonical) ? canonical : undefined;
+}
+function pythonDistributionNamesFromEntry(entry) {
+    const lower = entry.name.toLowerCase();
+    const names = [];
+    if (entry.isDirectory())
+        names.push(normalizePythonDistributionName(lower));
+    if (entry.isFile()) {
+        for (const extension of [".py", ".so", ".pyd"]) {
+            if (lower.endsWith(extension))
+                names.push(normalizePythonDistributionName(lower.slice(0, -extension.length)));
+        }
+    }
+    const metadata = /^(.+)-(\d[^/]*)\.(?:dist|egg)-info$/iu.exec(lower);
+    if ((entry.isDirectory() || entry.isFile()) && metadata !== null)
+        names.push(normalizePythonDistributionName(metadata[1]));
+    return names;
+}
+async function readDirectoryEntries(directory, signal) {
+    throwIfCancelled(signal);
+    try {
+        return await opendir(directory);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP")
+            throw new Error("Python environment directory changed during inspection", { cause: error });
+        throw new Error("Could not inspect the local Python environment", { cause: error });
+    }
+}
+function countPythonEnvironmentEntry(scan) {
+    scan.entries += 1;
+    if (scan.entries > maxPythonEnvironmentEntries)
+        throw new Error(`Python environment exceeds the ${maxPythonEnvironmentEntries}-entry scan limit`);
+}
+async function readSitePackageEntries(sitePackages, scan, signal) {
+    if (sitePackages === undefined)
+        return [];
+    if (scan.directories.has(sitePackages))
+        return [];
+    scan.directories.add(sitePackages);
+    const entries = [];
+    for await (const entry of await readDirectoryEntries(sitePackages, signal)) {
+        countPythonEnvironmentEntry(scan);
+        throwIfCancelled(signal);
+        entries.push(entry);
+    }
+    return entries;
+}
+async function installedPythonEntries(workspace, scanRoots, signal) {
+    const installed = new Set();
+    const scan = { entries: 0, directories: new Set() };
+    for (const scanRoot of new Set(scanRoots)) {
+        for (const environment of [".venv", "venv"]) {
+            throwIfCancelled(signal);
+            const windowsSitePackages = await canonicalDirectoryInside(workspace, join(scanRoot, environment, "Lib", "site-packages"), signal);
+            for (const entry of await readSitePackageEntries(windowsSitePackages, scan, signal)) {
+                for (const name of pythonDistributionNamesFromEntry(entry))
+                    installed.add(name);
+            }
+            const lib = await canonicalDirectoryInside(workspace, join(scanRoot, environment, "lib"), signal);
+            if (lib === undefined)
                 continue;
-            const sitePackages = join(lib, version.name, "site-packages");
-            const entries = await readdir(sitePackages, { withFileTypes: true }).catch(() => []);
-            if (entries.some((entry) => entry.name === normalized || entry.name.startsWith(`${normalized}-`) || entry.name.startsWith(`${normalized}.`)))
-                return true;
+            for await (const version of await readDirectoryEntries(lib, signal)) {
+                countPythonEnvironmentEntry(scan);
+                throwIfCancelled(signal);
+                if (!version.isDirectory() || !version.name.startsWith("python"))
+                    continue;
+                const sitePackages = await canonicalDirectoryInside(workspace, join(lib, version.name, "site-packages"), signal);
+                for (const entry of await readSitePackageEntries(sitePackages, scan, signal)) {
+                    for (const name of pythonDistributionNamesFromEntry(entry))
+                        installed.add(name);
+                }
+            }
         }
     }
-    return false;
+    return installed;
+}
+function hasInstalledPythonPackage(entries, name) {
+    return entries.has(normalizePythonDistributionName(name));
+}
+async function readManifestText(target) {
+    try {
+        return await readBoundedTextFile(target, maxManifestBytes, "Dependency manifest");
+    }
+    catch (error) {
+        if (error instanceof BoundedFileSizeError)
+            throw new Error("Dependency manifest exceeds the 1 MiB limit", { cause: error });
+        if (error instanceof BoundedFileTypeError)
+            throw error;
+        throw new Error("Could not read dependency manifest", { cause: error });
+    }
 }
-async function inspectRequirements(workspace, target) {
-    const parsed = parseRequirements(await readFile(target, "utf8"));
+async function inspectRequirements(workspace, target, source, signal) {
+    const parsed = parseRequirements(source);
+    throwIfCancelled(signal);
+    const installedEntries = await installedPythonEntries(workspace, [dirname(target), workspace], signal);
     const missing = [];
     for (const name of parsed.names) {
-        if (!(await installedPythonPackage(dirname(target), name)) && !(await installedPythonPackage(workspace, name)))
+        throwIfCancelled(signal);
+        if (!hasInstalledPythonPackage(installedEntries, name))
             missing.push(name);
     }
     return {
@@ -113,36 +377,51 @@ async function inspectRequirements(workspace, target) {
         ecosystem: "python",
         declared: parsed.names.length,
         installed: parsed.names.length - missing.length,
+        scanLimit: maxDependencyDeclarations,
         missing,
-        invalid: [],
+        optionalMissing: [],
+        invalid: parsed.invalid,
         conflicts: parsed.constraints,
+        unresolved: parsed.unresolved,
     };
 }
-export async function inspectManifest(workspace, requested = "package.json") {
-    const resolved = await resolveExistingWorkspacePath(workspace, requested, "Manifest path must stay inside the current workspace");
+export async function inspectManifest(workspace, requested = "package.json", signal) {
+    throwIfCancelled(signal);
+    let resolved;
+    try {
+        resolved = await resolveExistingWorkspacePath(workspace, requested, "Manifest path must stay inside the current workspace");
+    }
+    catch (error) {
+        throw new Error("Could not resolve dependency manifest inside the current workspace", { cause: error });
+    }
+    throwIfCancelled(signal);
     const target = resolved.target;
     workspace = resolved.root;
-    const source = await readFile(target, "utf8");
-    if (basename(target).toLowerCase().startsWith("requirements") && target.toLowerCase().endsWith(".txt"))
-        return inspectRequirements(workspace, target);
+    const fileName = basename(target).toLowerCase();
+    const requirements = fileName.startsWith("requirements") && fileName.endsWith(".txt");
+    if (!requirements && fileName !== "package.json")
+        throw new Error("Dependency manifest must be package.json or requirements*.txt");
+    const source = await readManifestText(target);
+    throwIfCancelled(signal);
+    if (requirements)
+        return inspectRequirements(workspace, target, source, signal);
     let parsed;
     try {
         parsed = JSON.parse(source);
     }
     catch (error) {
-        throw new Error(`Invalid JSON manifest: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        throw new Error("Invalid JSON dependency manifest", { cause: error });
     }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
         throw new Error("Manifest root must be an object");
     const record = parsed;
-    const sections = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
-    const entries = sections.flatMap((section) => {
-        const value = record[section];
-        return value !== null && typeof value === "object" && !Array.isArray(value)
-            ? Object.entries(value).map(([name, constraint]) => ({ name, constraint: typeof constraint === "string" ? constraint : String(constraint) }))
-            : [];
-    });
+    const entries = npmDependencyEntries(record);
+    if (entries.length > maxDependencyDeclarations)
+        throw new Error(`Dependency manifest exceeds the ${maxDependencyDeclarations}-dependency scan limit`);
     const unique = [...new Set(entries.map((entry) => entry.name))];
+    const optionalNames = new Set(entries.filter((entry) => entry.optional).map((entry) => entry.name));
+    const requiredNames = new Set(entries.filter((entry) => !entry.optional).map((entry) => entry.name));
+    const validNames = new Set(unique.filter((name) => npmPackagePath(name) !== undefined));
     const moduleRoots = [];
     for (let directory = dirname(target);; directory = dirname(directory)) {
         moduleRoots.push(join(directory, "node_modules"));
@@ -150,12 +429,18 @@ export async function inspectManifest(workspace, requested = "package.json") {
             break;
     }
     const missing = [];
-    const invalid = [];
+    const optionalMissing = [];
+    const invalid = unique.filter((name) => !validNames.has(name)).map(sanitizedNpmNameDiagnostic);
     for (const name of unique) {
+        throwIfCancelled(signal);
+        const packagePath = npmPackagePath(name);
+        if (packagePath === undefined)
+            continue;
         let found = false;
         for (const moduleRoot of moduleRoots) {
             try {
-                const moduleStat = await stat(join(moduleRoot, ...name.split("/")));
+                const moduleStat = await stat(join(moduleRoot, ...packagePath));
+                throwIfCancelled(signal);
                 if (moduleStat.isDirectory()) {
                     found = true;
                     break;
@@ -164,58 +449,122 @@ export async function inspectManifest(workspace, requested = "package.json") {
                 found = true;
                 break;
             }
-            catch {
-                continue;
+            catch (error) {
+                throwIfCancelled(signal);
+                const code = error.code;
+                if (code === "ELOOP") {
+                    invalid.push(name);
+                    found = true;
+                    break;
+                }
+                if (code !== "ENOENT" && code !== "ENOTDIR")
+                    throw new Error(`Could not inspect installed npm dependency ${name}`, { cause: error });
             }
         }
-        if (!found)
-            missing.push(name);
+        if (!found) {
+            if (optionalNames.has(name) && !requiredNames.has(name))
+                optionalMissing.push(name);
+            else
+                missing.push(name);
+        }
     }
+    const constraintGroupsForReport = constraintGroups(entries.filter((entry) => validNames.has(entry.name)));
+    const unresolved = constraintGroupsForReport.filter((group) => group.constraints.length > 1 && group.constraints.some((constraint) => validRange(constraint) === null));
+    const unresolvedNames = new Set(unresolved.map((group) => group.name));
     return {
         manifest: relative(workspace, target) || ".",
         ecosystem: "npm",
         declared: unique.length,
-        installed: unique.length - missing.length - invalid.length,
+        installed: unique.length - missing.length - optionalMissing.length - invalid.length,
+        scanLimit: maxDependencyDeclarations,
         missing,
+        optionalMissing,
         invalid,
-        conflicts: conflictList(entries),
+        conflicts: constraintGroupsForReport.filter((group) => !unresolvedNames.has(group.name) && npmConstraintsConflict(group.constraints)),
+        unresolved,
     };
 }
+function validateParameters(value) {
+    if (value === null || typeof value !== "object")
+        throw new Error("Dependency check parameters must be an object containing only an optional manifest string");
+    let descriptors;
+    let prototype;
+    let array;
+    try {
+        array = Array.isArray(value);
+        descriptors = Object.getOwnPropertyDescriptors(value);
+        prototype = Object.getPrototypeOf(value);
+    }
+    catch (error) {
+        throw new Error("Dependency check parameters must be an accessible plain object", { cause: error });
+    }
+    if (array || (prototype !== Object.prototype && prototype !== null))
+        throw new Error("Dependency check parameters must be a plain object");
+    const manifest = descriptors.manifest;
+    if (Reflect.ownKeys(descriptors).some((key) => key !== "manifest") ||
+        (manifest !== undefined &&
+            (!("value" in manifest) ||
+                typeof manifest.value !== "string" ||
+                manifest.value.trim() === "" ||
+                manifest.value !== manifest.value.trim() ||
+                manifest.value.length > maxManifestPathLength ||
+                Buffer.byteLength(manifest.value, "utf8") > maxManifestPathLength ||
+                isAbsolute(manifest.value) ||
+                /^[A-Za-z]:[\\/]/u.test(manifest.value) ||
+                /[\p{Cc}\p{Cf}\p{Cs}]/u.test(manifest.value))))
+        throw new Error("Dependency check parameters must be an object containing only an optional manifest string");
+    return manifest === undefined ? {} : { manifest: manifest.value };
+}
 export default {
     name: "pi-dependency-checker",
     inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
-    apply(context) {
+    Config,
+    apply(context, config) {
+        assertKnownConfigKeys("dependency checker", config, []);
         let latest;
-        const inspect = async (manifest) => {
-            latest = await inspectManifest(context.piHarnessLaunch.cwd, manifest);
-            return latest;
+        const lifecycle = new AbortController();
+        context.effect(() => () => lifecycle.abort(new Error("Dependency checker plugin was disposed")));
+        const inspect = async (manifest, signal) => {
+            const report = await inspectManifest(context.piHarnessLaunch.cwd, manifest, signal);
+            throwIfCancelled(signal);
+            latest = cloneDependencyReport(report);
+            return cloneDependencyReport(report);
         };
         const unregisterTool = context.piTools.register(defineTool({
             name: "dependency_check",
             label: "Dependency check",
-            description: "Inspect package.json or requirements.txt and report missing dependencies plus conflicting version constraints.",
-            promptSnippet: "check local dependency installation and version conflicts",
-            parameters: Type.Object({ manifest: Type.Optional(Type.String({ description: "package.json or requirements.txt path relative to the workspace" })) }),
-            async execute(_toolCallId, params) {
-                const report = await inspect(params.manifest);
+            description: "Run a bounded, offline package.json or requirements*.txt scan for local dependency presence and conflicting declarations.",
+            promptSnippet: "check bounded local dependency presence and declaration conflicts",
+            parameters: Type.Object({
+                manifest: Type.Optional(Type.String({ minLength: 1, maxLength: maxManifestPathLength, description: "package.json or requirements.txt path relative to the workspace" })),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, rawParams, signal) {
+                const params = validateParameters(rawParams);
+                const operationSignal = signal === undefined ? lifecycle.signal : AbortSignal.any([lifecycle.signal, signal]);
+                throwIfCancelled(operationSignal);
+                const report = await inspect(params.manifest, operationSignal);
                 return {
-                    content: [{ type: "text", text: `${report.manifest}: ${report.missing.length} missing dependencies, ${report.conflicts.length} conflicts.` }],
+                    content: [
+                        {
+                            type: "text",
+                            text: `${report.manifest}: ${report.missing.length} required missing, ${report.optionalMissing.length} optional missing, ${report.invalid.length} invalid, ${report.conflicts.length} conflicts, ${report.unresolved.length} unresolved constraint groups.`,
+                        },
+                    ],
                     details: report,
                 };
             },
         }));
+        context.effect(() => unregisterTool);
         const disposePanel = context.piPluginUi.register({
             id: "dependency-checker-panel",
             pluginId: "@pi-harness/core/plugins/dependency-checker",
             title: "Dependency Checker",
-            description: "检查 package.json 或 requirements.txt 的依赖安装状态和版本冲突。",
+            description: "离线检查有界 package.json 或 requirements*.txt 的本地依赖状态和声明冲突。",
             icon: "⊙",
-            read: async () => ({ report: latest ?? (await inspect()) }),
-        });
-        context.effect(() => () => {
-            unregisterTool();
-            disposePanel();
+            read: async () => ({ report: latest === undefined ? await inspect(undefined, lifecycle.signal) : cloneDependencyReport(latest) }),
         });
+        context.effect(() => disposePanel);
     },
 };
 //# sourceMappingURL=dependency-checker.js.map