@4da/mcp-server 6.2.3 → 6.2.5

package/dist/live/fix-paths.d.ts

@@ -26,7 +26,38 @@ import type { LiveCache } from "./cache.js";
 import type { RateLimiter } from "./rate-limiter.js";
 import { type AdvisoryRanges, type CleanTarget } from "./osv-ranges.js";
 import { type LockfileFormat } from "./lockfile-parents.js";
+import { type AdvisoryQuery, type HeldDependency } from "./held-dependencies.js";
 import type { OsvEcosystem } from "./types.js";
+/** What a registry says about one package's releases, for fix targets and parent advice. */
+export interface PackageReleaseFacts {
+    /** Published, installable versions: every release except the `withdrawn` ones. */
+    versions: string[];
+    /**
+     * Releases the registry withdrew, never a fix target (withdrawn-releases.ts, the 4DA app's
+     * rule): yanked (crates.io; PyPI: every file), and npm `deprecated` only where a later,
+     * non-deprecated stable release exists on the same caret line and `latest` is not deprecated.
+     */
+    withdrawn: string[];
+    /** Per withdrawn release, the registry's words ("4.18.0 is deprecated on npm ("Bad release...")"). */
+    withdrawnWhy: Record<string, string>;
+    /** The registry's latest release (npm `latest` tag; crates.io the highest non-yanked), or null. */
+    latest: string | null;
+    /** The package-level deprecation of the newest release (npm), or null. */
+    deprecatedLatest: string | null;
+    /**
+     * npm: releases that carry a `deprecated` message the withdrawal rule does NOT withdraw (a
+     * notice on a whole line, such as glob's "Old versions of glob are not supported"), with the
+     * message. Still candidates; a tool that offers one says it is deprecated (final release audit
+     * of 6.2.5: the plan targeted glob 10.5.0 while dependency_check said review on it).
+     */
+    lineNotices?: Record<string, string>;
+    /**
+     * npm: per release, the dependencies it holds (exact pins and narrow ranges, held-dependencies.ts):
+     * name -> spec. A release that holds none is absent. Its advisories come with the release
+     * (audit 6.2.5 D-4: express 4.20.0 exact-pins qs 6.11.0).
+     */
+    heldSpecs?: Record<string, Record<string, string>>;
+}
 export interface CrateDepReq {
     req: string;
     optional: boolean;
@@ -34,12 +65,20 @@ export interface CrateDepReq {
 export interface CratesSparse {
     /** Versions not yanked. */
     versions: string[];
+    /** Yanked versions. */
+    yanked?: string[];
     /** version -> dependency crate name -> requirements (one per target/kind entry; dev-dependencies left out). */
     reqs: Record<string, Record<string, CrateDepReq[]>>;
 }
+/** Per published release of a parent: its requirements on one package, and whether it declares it only as a peer. */
+export type RequirementHistory = Record<string, {
+    reqs: string[];
+    peer: boolean;
+}>;
 export declare class FixPathSources {
     private cache;
     private rateLimiter;
+    private npmDocs;
     constructor(cache: LiveCache, rateLimiter: RateLimiter);
     /** Every non-withdrawn OSV advisory for a package, as ranges; null when OSV could not be read. */
     packageAdvisories(ecosystem: OsvEcosystem, name: string): Promise<AdvisoryRanges[] | null>;
@@ -51,15 +90,138 @@ export declare class FixPathSources {
      * records none). Null when unknown; [] when the parent declares none.
      */
     parentRequirements(ecosystem: OsvEcosystem, parent: string, parentVersion: string, dep: string): Promise<string[] | null>;
-    private npmVersions;
+    /**
+     * What every published release of `parent` requires of `dep`, from the
+     * registry: version -> requirements (`reqs: []` when that release does not
+     * depend on it). npm reads dependencies and optionalDependencies of the
+     * abbreviated document (as `parentRequirements`), and, when neither holds
+     * it, peerDependencies, flagged `peer`: npm 7+ installs a missing peer, so
+     * moving a package into peerDependencies is not dropping it (readiness
+     * review 2026-10-17, finding 10). crates.io: the sparse index. Null when
+     * unknown or unsupported. Used to find the smallest parent release that
+     * admits a clean version (audit H1).
+     */
+    requirementHistory(ecosystem: OsvEcosystem, parent: string, dep: string): Promise<RequirementHistory | null>;
+    /**
+     * One npm abbreviated document per package, shared by the release facts and the requirement
+     * history of a plan (a parent's document was downloaded twice: NodeGoat's mongodb, ~600
+     * releases). Kept in memory for a short while, at most a few at a time; a failure is not kept.
+     */
+    private npmDocument;
+    /**
+     * Release facts for a parent or a fix target: what is installable, what is
+     * deprecated or yanked, and the latest release. Null when the registry
+     * could not be read or is not supported.
+     */
+    releaseFacts(ecosystem: OsvEcosystem, name: string): Promise<PackageReleaseFacts | null>;
+    /**
+     * npm's abbreviated document: versions without READMEs, with each
+     * version's `deprecated` message. A withdrawn release is never offered as a
+     * fix target: lodash 4.18.0 ("Bad release. Please use lodash@4.17.21
+     * instead.") was recommended by vulnerability_scan (audit B-8, 2026-10-12).
+     * Withdrawn means the app's rule (withdrawn-releases.ts): a deprecated
+     * release with a later clean one on its caret line. A whole-major notice
+     * (glob, tar 6.x) withdraws nothing, or glob 10.4.5 is sent to 12.0.0.
+     */
+    private npmFacts;
     /** A crate's sparse-index record: versions and per-version dependency requirements. */
     cratesSparse(name: string): Promise<CratesSparse | null>;
-    private pypiVersions;
+    /**
+     * PyPI's JSON API: every release with files; one whose every file is yanked is withdrawn
+     * (PEP 592, the app's `parse_pypi`). A release with no files cannot be installed and is not listed.
+     */
+    private pypiFacts;
     private goVersions;
 }
-export type FixTargetResult = CleanTarget;
-/** The minimal clean target for one installed copy, or null when the advisories could not be read. */
-export declare function cleanFixTarget(sources: FixPathSources, ecosystem: OsvEcosystem, name: string, perAdvisoryFixes: string[]): Promise<FixTargetResult | null>;
+export type FixTargetResult = CleanTarget & {
+    /** No target and a malicious landing: "<pkg> is flagged malicious (<id>): remove or replace <pkg>" (#994 review). */
+    landingNote?: string;
+    /**
+     * True when the package's advisories could not be read (OSV /v1/query
+     * failed) but the registry could: `target` is then only the smallest
+     * installable release at or above the highest per-advisory fix, which is
+     * deprecated, yanked or unpublished (`floorWithdrawn` says which). It is
+     * NOT checked against the package's other advisories; callers report the
+     * fix as checked against the installed version's advisories only.
+     */
+    advisoriesUnread?: boolean;
+    /**
+     * True when the package's registry could not be read: withdrawn (yanked, deprecated) releases
+     * were not checked, and the target comes from the advisory data alone, as before FX-H5.
+     */
+    registryUnread?: boolean;
+    /** The registry's words for each `withheld` release and each withdrawn line fix. */
+    withheldWhy?: Record<string, string>;
+    /**
+     * Per-advisory fixes the registry withdrew, keyed by that fix: the release to take instead
+     * (`fix: null` when none past it is known) and the withdrawn ones passed (installableFix).
+     */
+    lineFixes?: Record<string, {
+        fix: string | null;
+        withheld: string[];
+    }>;
+    /**
+     * npm: the target carries a deprecation notice the withdrawal rule keeps (one on its whole line,
+     * no later release on the line free of it: glob 10.5.0, "Old versions of glob are not
+     * supported"). It stays the target, the smallest fix without a major upgrade, and every tool
+     * says it is deprecated, as dependency_check does with `review` (final release audit 7f).
+     */
+    targetNotice?: string;
+    /** The package's malware advisories (#981 rule a): a release one affects is never the target. */
+    malware?: string[];
+    /**
+     * npm (audit 6.2.5 D-4): the release the package's own advisories pointed at, passed because a
+     * dependency it holds (an exact pin, or a narrow range whose newest release is affected) brings
+     * an advisory in; `heldPast` names each release passed and why. `target` is then the smallest
+     * later release on that line whose own advisories AND held dependencies are clean.
+     */
+    heldFrom?: string;
+    heldPast?: Array<{
+        version: string;
+        affected: HeldDependency[];
+    }>;
+    /** The target holds an affected dependency and no later release searched (`searched`) clears it: not a clean fix. */
+    heldBlocked?: {
+        affected: HeldDependency[];
+        searched: string[];
+    };
+    /** Whether the target's held dependencies are affected could not be checked, and why: not a clean fix either. */
+    heldUnchecked?: string;
+};
+/**
+ * Whether a checked target may be reported as checked against every advisory (fix_checked
+ * `all_advisories`): its own advisories were read, and, for npm, what it installs at a fixed
+ * version was judged clean (audit 6.2.5 D-4).
+ */
+export declare function targetCheckedAll(clean: FixTargetResult): boolean;
+/** The words for a target's held dependencies (FixTargetResult.heldFrom / heldBlocked / heldUnchecked), or null when there is nothing to say. */
+export declare function heldNote(clean: FixTargetResult): string | null;
+/**
+ * The minimal clean target for one installed copy, or null when neither the
+ * advisories nor anything that changes the answer could be read.
+ *
+ * Advisories unreadable, registry readable (audit H5: OSV /v1/query down):
+ * a deprecated or yanked release is still never the target. lodash 4.17.20
+ * went to 4.18.0 ("Bad release") because the whole check was skipped; the
+ * registry facts alone move it to 4.18.1, flagged `advisoriesUnread`.
+ *
+ * With no per-advisory fix at all (advisories that give only `last_affected`,
+ * audit A6), and the installed version known, the registry is asked for the
+ * first published release above the installed one that no known advisory
+ * affects: a fix candidate the advisories never named, flagged
+ * `noAdvisoryFix`, instead of "no fix".
+ */
+export declare function cleanFixTarget(sources: FixPathSources, ecosystem: OsvEcosystem, name: string, perAdvisoryFixes: string[], installed?: string | null): Promise<FixTargetResult | null>;
+/** #981 (b): an advisory whose ranges cannot be read leaves the release unknown, never skipped silently. */
+export declare function unreadableText(ids: string[]): string;
+/** The 4DA lead's rule (2026-10-18): no release is offered that brings in an advisory the installed version does not have. */
+export declare function introducesText(ids: string[]): string;
+/** #981 round 3: an installed copy a malicious advisory affects names no release; the advice is to remove or replace it. */
+export declare function malwareText(name: string, ids: string[]): string;
+/** The words for a target that carries a line-wide deprecation notice (FixTargetResult.targetNotice). */
+export declare function lineNoticeText(version: string, message: string): string;
+/** `withheldNote` for a checked target: the withdrawn releases passed, in plain words; null when none. */
+export declare function withheldText(clean: FixTargetResult, ecosystem: string): string | null;
 /**
  * Verified targets for many installed copies at once, within a time budget:
  * the copies that could not be checked in time (or offline) are simply
@@ -70,31 +232,141 @@ export declare function verifyFixTargets(sources: FixPathSources | null, items:
     ecosystem: OsvEcosystem;
     name: string;
     fixes: string[];
-}>, budgetMs: number, concurrency?: number): Promise<Map<string, CleanTarget>>;
-/** One clause for a target that is not the highest per-advisory fix, or null when it is. */
-export declare function targetNote(clean: CleanTarget): string | null;
+    installed?: string;
+}>, budgetMs: number, concurrency?: number, options?: {
+    heldQuery?: AdvisoryQuery;
+}): Promise<Map<string, FixTargetResult>>;
+/** Said whenever the registry could not be read: withdrawn releases are then not ruled out, never silently. */
+export declare const REGISTRY_UNREAD_NOTE = "the registry could not be read, so whether it yanked or deprecated this release was not checked";
+/**
+ * One clause for a target that is not the highest per-advisory fix, or null when it is.
+ * Withdrawn releases passed on the way are named in the registry's own words (FX-H5).
+ */
+export declare function targetNote(clean: FixTargetResult, ecosystem?: string): string | null;
+/**
+ * A finding's own fix as the registry still offers it (the app's `installable_fix`): the
+ * advisory's fixed version, or, when the registry withdrew it, the release to take instead
+ * (null: none past it is known), with the withdrawn ones and the plain-words note.
+ */
+export declare function rowFix(fixed: string | null, clean: FixTargetResult | undefined, ecosystem: string): {
+    fixed: string | null;
+    withheld: string[];
+    note: string | null;
+};
 export interface RefreshVerdict {
-    /** True when every parent's requirement already admits a clean version. */
+    /** True when a lockfile refresh reaches a clean version (read, or inferred: see `inferred`). */
     refreshFixes: boolean;
+    /**
+     * True when no parent's requirement could be read (or not every one) and none
+     * excludes the target, so the verdict comes from semver compatibility
+     * (4DA AD-055 ¶1): a refresh when the target is caret-compatible with the
+     * installed version, the parent otherwise.
+     */
+    inferred: boolean;
     format: LockfileFormat;
-    /** The command, run in the lockfile's directory. */
+    /** The command, run in the lockfile's directory; for yarn 1 and bun, the manual steps (no command moves one copy in place). */
     command: string;
-    /** Parent requirements that do NOT admit a clean version (why it is waiting on upstream). */
+    /**
+     * Parent requirements that do NOT admit a clean version (why it is waiting on upstream).
+     * `bundled`: the copy ships inside that parent's tarball, so neither a refresh nor an override reaches it (audit E8).
+     */
     blocking: Array<{
         parent: string;
         parentVersion: string | null;
         requirement: string;
+        bundled?: boolean;
     }>;
     /** The version a refresh resolves to, when the registry's version list was read. */
     resolvesTo: string | null;
 }
-/** The refresh command for one lockfile format. */
-export declare function refreshCommand(format: LockfileFormat, name: string, installed: string, target: string): string;
+/**
+ * The command that refreshes one transitive copy in place, for the tools it
+ * can be named for (4DA AD-055 ¶4); null for yarn 1 and bun, which have none
+ * (see `manualRefreshSteps`).
+ *
+ * pnpm: at a workspace root (`pnpm-workspace.yaml`), `pnpm update <pkg>`
+ * touches only the root project's tree, so a member's transitive copy stayed
+ * where it was; `-r` reaches every member (measured with pnpm 10.34.6: a
+ * member's mkdirp -> minimist 1.2.5 moved to 1.2.8 only with `-r`). `--depth
+ * Infinity` is the form the fix-path oracle applied (2026-10-10, U04/U10);
+ * pnpm 8.15 to 10.34 also moved a root project's transitive copy without it.
+ */
+export declare function refreshCommand(format: LockfileFormat, name: string, installed: string, target: string, workspaceRoot?: boolean): string | null;
+/**
+ * Whether an override (npm `overrides`, pnpm `pnpm.overrides`, yarn `resolutions`) can reach the copy
+ * these blocking parents hold: never when one of them ships it bundled (rule vectors rv-066..rv-068).
+ */
+export declare function overrideReaches(blocking: Array<{
+    bundled?: boolean;
+}>): boolean;
+/**
+ * How a DIRECT dependency moves to its fix target, worded for the tool and the manifest that
+ * declares it: a port of the 4DA app's `osv/direct_upgrade.rs` (rule vectors fc-028..fc-053),
+ * read from the declaring project's own manifest. A command is named only where it was run
+ * against the tool (2026-10-15/16: npm 10.9.2, pnpm 10.34.6, yarn 1.22.22, yarn 4.9.1, cargo
+ * 1.95, go 1.24) and moved the dependency while keeping it as declared. Plain `npm install x@v`
+ * wrote `^v` over an exact pin and over `~` (readiness review 2026-10-17, finding 4).
+ *
+ * Null, and the plan keeps its plain "bump it where it is declared", for anything this cannot
+ * read with certainty: a dependency declared in two sections; a declared spec that does not
+ * admit the installed copy; `>=`, `||`, x-range, tag, git, `workspace:` or alias specs; a git,
+ * path or alternate-registry crate; a yarn workspace member (`yarn up` is project-wide); a Go
+ * `replace`; hashed or compiled (pip-compile, uv) requirements; bun or an unknown tool.
+ */
+export type DirectFix = {
+    command: string;
+    refresh?: false;
+}
+/**
+ * The declaration ALREADY admits the target (navcal: sharp, next and vite under `^`): the minimal
+ * advice is the tool's in-range lockfile refresh, which leaves the manifest untouched, not a bump
+ * of the declaration (the 4DA app's DirectFix::Refresh). Each was run on a project declaring
+ * `ms ^2.1.1` locked at 2.1.1 (2026-10-18): it moved the lock to 2.1.3 and left package.json
+ * unchanged; plain `pnpm update ms` rewrote `^2.1.1` to `^2.1.3`, hence `--no-save`. Cargo:
+ * `itoa = "1.0.5"` locked 1.0.11 with Cargo.toml unchanged. Any readable range qualifies,
+ * `>=` and `||` included: no operator needs carrying.
+ */
+ | {
+    command: string;
+    refresh: true;
+} | {
+    instruction: string;
+};
+type NpmManager = "npm" | "pnpm" | "yarn1" | "yarn-berry";
+/** The spec `name` is declared with, when exactly one of dependencies / devDependencies / optionalDependencies holds it. */
+export declare function npmDeclared(packageJson: string, name: string): string | null;
+/** The command that moves a declared npm-family dependency, keeping its operator (quoted: `^` is cmd.exe's escape). */
+export declare function npmDirectCommand(manager: NpmManager, declared: string, name: string, target: string): string | null;
+interface CargoDecl {
+    kind: "normal" | "dev" | "build";
+    target: string | null;
+    key: string;
+    req: string | null;
+    workspace: boolean;
+    otherSource: boolean;
+}
+/** Every declaration of `crate` in a Cargo.toml (by crate name, so a renamed dependency is found through `package = ...`). */
+export declare function cargoDeclarations(manifest: string, crate: string): CargoDecl[];
+/** `go get <module>@v<target>` when go.mod requires the module directly at `installed` and no `replace` points it elsewhere. */
+export declare function goDirectCommand(goMod: string, module: string, installed: string, target: string): string | null;
+/** The edit of the requirements line that pins the package with `==` at `installed` (markers, extras kept). */
+export declare function pypiDirectInstruction(requirements: string, file: string, name: string, installed: string, target: string): string | null;
+/**
+ * The fix for `name` at `installed`, declared in the project at `projectDir`, read from its own
+ * manifest; null when it cannot be named with certainty (see DirectFix).
+ */
+export declare function directFix(projectDir: string, ecosystem: string, name: string, installed: string, target: string): DirectFix | null;
+/** For a lockfile with no in-place refresh command (yarn 1, bun): the steps that move the copy. */
+export declare function manualRefreshSteps(format: "yarn" | "bun", name: string): string;
+/** The refresh command for the project whose lockfile is `lockfile`; null when no command is named for it. */
+export declare function refreshCommandFor(lockfile: string, name: string, installed: string, target: string): string | null;
 /**
  * Whether refreshing `lockfile` moves `name@installed` to a clean version
- * without any parent changing its declared requirement. Null when the
- * lockfile or a requirement cannot be read (the caller keeps "waiting on
- * upstream", the conservative answer).
+ * without any parent changing its declared requirement: `refreshRule` over
+ * every requirement the parents declare (read from the lockfile, else the
+ * parent's registry metadata). Null when the lockfile cannot be read or no
+ * verdict is possible (the caller keeps "waiting on upstream", the
+ * conservative answer).
  */
 export declare function refreshVerdict(sources: FixPathSources, ecosystem: OsvEcosystem, lockfile: string, name: string, installed: string, target: string, advisories: AdvisoryRanges[] | null, published: string[] | null): Promise<RefreshVerdict | null>;
 /**
@@ -116,3 +388,4 @@ export declare function refreshVerdict(sources: FixPathSources, ecosystem: OsvEc
  * at its newest matching version.
  */
 export declare function cargoPrecisePrerequisites(sources: FixPathSources, lockContent: string, name: string, installed: string, target: string): Promise<string[] | null>;
+export {};