@cdxgen/cdxgen 13.2.0 → 13.4.0

package/types/lib/inventory/fetchBatch.d.ts

@@ -10,11 +10,13 @@
  * read instead of the network.
  *
  * There is one policy layer (`fetchRate.js`, mirrored by the Rust `rate.rs`)
- * and two transports. When the `cdxrs` binary is available it is preferred,
- * because it brings an on-disk conditional cache (D26) the JS pool does not
- * have. When it is absent, disabled, or unusable, the JS pool runs every
- * request through `cdxgenAgent` so the secure-mode host allowlist, the
- * activity recorder and the test cassette interceptor all still apply.
+ * and two transports. When the `cdxrs` binary is available it is preferred for
+ * the JSON it can carry. When it is absent, disabled, or unusable, and whenever
+ * a dry run, secure mode or a host allowlist is in force, the JS pool runs
+ * every request through `cdxgenAgent` so those policies, the activity recorder
+ * and the test cassette interceptor all still apply. The JS pool keeps the same
+ * on-disk conditional cache as cdxrs (`fetchDiskCache.js`), in the same
+ * directory and layout.
  *
  * Two properties are deliberate and load-bearing:
  *
@@ -27,11 +29,43 @@
  *    JS on all three registries it covered.
  *
  * 2. **Fallback is per URL, not per run.** A URL that the batch could not
- *    resolve for a transport reason is simply absent from the map, and the
- *    caller's own `cdxgenAgent.get` runs for it exactly as before. A URL that
- *    resolved to a definite HTTP error is recorded as such, so the caller does
- *    not re-request it only to get the same 404.
+ *    resolve for a transport reason is left to the caller, whose own request
+ *    goes through {@link gatedGet} and the same per-host gate. A URL the server
+ *    answered with an error status, after the batch's retries, is recorded as
+ *    such, so the caller does not ask again only to get the same answer, and a
+ *    404 or 410 is remembered for the rest of the run.
  */
+/**
+ * Whether requests to a host are paused.
+ *
+ * @param {string|null} host Hostname.
+ * @returns {boolean}
+ */
+export declare function isHostCircuitOpen(host: string | null): boolean;
+/**
+ * Pause requests to a host, for at least {@link DEFAULT_CIRCUIT_OPEN_MS} or for
+ * as long as the server asked. Warns once per pause.
+ *
+ * @param {string} host Hostname.
+ * @param {{delayMs?: number|null, cause?: string, quiet?: boolean, minimumMs?: number}} [details]
+ *   Server-supplied delay, a short description of what happened, whether to
+ *   pause without a warning or a degradation record (for failures that are not
+ *   the host's doing, such as a dry run or an allowlist block), and the
+ *   shortest pause, which a host that says exactly when it recovers sets to 0.
+ * @returns {void}
+ */
+export declare function openHostCircuit(host: string, { delayMs, cause, quiet, minimumMs }?: {
+    delayMs?: number | null;
+    cause?: string;
+    quiet?: boolean;
+    minimumMs?: number;
+}): void;
+/**
+ * Clear every paused host. Tests only.
+ *
+ * @returns {void}
+ */
+export declare function resetHostCircuits(): void;
 /**
  * @returns {Object|null} Stats from the last batch (requests, unique, ok,
  *   failures, cacheHits, elapsedMs, peakConcurrency), or null.
@@ -69,6 +103,11 @@ export type BatchEntry = {
      * other than 429) and re-requesting it in JS would be pointless.
      */
     definite?: boolean;
+    /**
+     * Response headers of a failed request, when the
+     * JS pool made it. cdxrs reports no headers.
+     */
+    headers?: Object;
 };
 /**
  * Fetch a batch of registry URLs concurrently.
@@ -132,12 +171,40 @@ export declare function recordPolicyDegradationFromError(err: Error): void;
  * The per-host semaphore and limiter are module state, so this shares one gate
  * per host for the life of the process.
  *
+ * A host paused by its circuit breaker fails at once with a 429-shaped error,
+ * and a 429 from a breaker host pauses it.
+ *
+ * With `deferGate`, `issue` receives request options carrying a
+ * `beforeNetwork` hook and must pass them to `cdxgenAgent`. The rate limiter
+ * then runs only when the request misses the response cache, so a cached
+ * answer does not wait for a slot. Without it, the limiter runs before
+ * `issue`, as before.
+ *
  * @template T
  * @param {string} url The URL about to be requested.
- * @param {() => Promise<T>} issue Issues the request and resolves its result.
+ * @param {(gate: Object) => Promise<T>} issue Issues the request and resolves its result.
+ * @param {{deferGate?: boolean}} [opts]
  * @returns {Promise<T>} Whatever `issue` resolves to.
  */
-export declare function withHostRateLimit<T>(url: string, issue: () => Promise<T>): Promise<T>;
+export declare function withHostRateLimit<T>(url: string, issue: (gate: Object) => Promise<T>, { deferGate }?: {
+    deferGate?: boolean;
+}): Promise<T>;
+/**
+ * Request a URL the batch did not answer, the way the pool would have: behind
+ * the per-host gate, failing at once for a document that already answered 404
+ * or 410 this run, and remembering such an answer for the next pass.
+ *
+ * This is the fallback every metadata function uses after a prefetch. Without
+ * it, a URL the batch left open went straight to the network with no rate gate,
+ * and the same miss was asked again on every pass.
+ *
+ * @param {string} url URL to request.
+ * @param {Object} [options] `cdxgenAgent.get` options.
+ * @returns {Promise<Object>} The response.
+ * @throws {Error} The request's own error, or a 404-shaped error for a
+ *   remembered miss, so the caller's `catch` runs as it would for the network.
+ */
+export declare function gatedGet(url: string, options?: Object): Promise<Object>;
 /**
  * Read a prefetched response, or signal that the caller should fetch it itself.
  *
@@ -145,9 +212,11 @@ export declare function withHostRateLimit<T>(url: string, issue: () => Promise<T
  * @param {string} url The URL the caller is about to request.
  * @returns {{body: *}|undefined} A response-shaped object when the body is
  *   available, or `undefined` when the caller should issue its own request.
- * @throws {Error} When the batch established a definite HTTP error for this
- *   URL, so that the caller's existing `catch` treats it exactly as it treats a
- *   failed `cdxgenAgent.get`.
+ * @throws {Error} When the server answered with an error status, so that the
+ *   caller's existing `catch` treats it exactly as it treats a failed
+ *   `cdxgenAgent.get`. A 5xx or a 429 is the answer after the batch's own
+ *   retries, and asking once more at once would only add to the load. Only a
+ *   transport failure, with no status, is left to the caller to retry.
  */
 export declare function prefetchedResponse(prefetched: Map<string, BatchEntry>, url: string): {
     body: any;

package/types/lib/inventory/fetchBatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetchBatch.d.ts","sourceRoot":"","sources":["../../../lib/inventory/fetchBatch.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA8EH;;;GAGG;AACH,wBAAgB,cAAc,IAHjB,MAAM,GAAC,IAAI,CAKvB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,IAFtB,OAAO,CASnB;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,SAO1C;AAKE,YAAkB,UAAU,GAC5B;;;;IAAoB,EAAE,EAAX,OAAO,CAClB;;;;IAAe,IAAI,AAAnB,CACA,EADW,GAAC,CACZ;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;;IAAqB,QAAQ,AAA7B,CAEF,EAFa,OAAO,CAEpB;CAAA,CAAA;AAoCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EARhC,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,CAAC,MAAM,GAAC,MAAM,GAAC,QAAQ,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAC,CAQnF,EAAE,OAAO,AANjD,CAEA,EADA;IAAyB,SAAS,AAAlC,CACA,EADQ,MAAM,CACd;CAIsD,GAJ5C,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAgC5C;AAoCD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAHtB,MAAM,GAAC,IAGe,GAFpB,OAAO,CAQnB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAH1B,MAAM,GAAC,IAGmB,GAFxB,OAAO,CAOnB;AAqTD;;;;;;;GAOG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAHzC,KAGyC,GAFvC,IAAI,CAuBhB;AAqGD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CAL1B,CAAC,EAK0B,GAAG,EAJhC,MAIgC,EAAE,KAAK,EAHvC,MAAM,OAAO,CAAC,CAAC,CAGwB,GAFrC,OAAO,CAAC,CAAC,CAAC,CAiBtB;AAyFD;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EARlC,GAAG,CAAC,MAAM,EAAE,UAAU,CAQY,EAAE,GAAG,EAPvC,MAOuC,GANrC;IAAC,IAAI,EAAE,GAAC,CAAA;CAAC,GAAC,SAAS,CAoB/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,IAFlB,OAAO,CAOnB"}
+{"version":3,"file":"fetchBatch.d.ts","sourceRoot":"","sources":["../../../lib/inventory/fetchBatch.js"],"names":[],"mappings":"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"}

package/types/lib/inventory/fetchDiskCache.d.ts

@@ -0,0 +1,169 @@
+/**
+ * The on-disk response cache of the JS batch pool.
+ *
+ * cdxrs keeps registry JSON on disk between runs. The requests it cannot carry
+ * run on the JS pool instead: crates.io and package.elm-lang.org, which have
+ * one rate gate in JS; the GitHub API, whose quota headers cdxrs does not
+ * report; HTML pages such as pkg.go.dev and podspecs; and POMs. Without a disk
+ * cache of their own, the most tightly limited hosts were asked again on every
+ * run. All of them are kept here, in the cdxrs layout and under the same rules:
+ *
+ * - `<cacheDir>/cdxrs-fetch/<host>/<hash>.json`, written atomically, mode 0600,
+ *   with the URL redacted;
+ * - keyed by URL, method, `Accept` and the auth realm, hashed as cdxrs hashes
+ *   them, so a JSON entry either side writes serves the other. A text body adds
+ *   its type to the key, so cdxrs never reads it as JSON;
+ * - fresh for `CDXGEN_CACHE_TTL` seconds (24 hours by default, 0 for never);
+ *   a stale entry with an ETag or Last-Modified is revalidated, and is served
+ *   when the server fails;
+ * - loopback hosts are not cached unless `CDXGEN_CACHE_LOOPBACK=1`;
+ * - least recently used entries are removed past 256 MB.
+ *
+ * Two rules are the JS pool's own. A release POM never changes once published,
+ * so it does not expire. A 404 or 410 is kept for the same TTL, or for 24
+ * hours when the TTL is 0, under a key of its own that cdxrs never reads.
+ *
+ * Requests that carry their own headers, such as a registry token, are never
+ * cached here, and nothing is read or written during a dry run, for a host
+ * outside `CDXGEN_ALLOWED_HOSTS`, or over plain HTTP in secure mode, so the
+ * cache never answers a request the policy would have refused. The directory
+ * is cdxgen's own, and its files are written as cdxrs writes them, without an
+ * activity record per entry.
+ */
+export type DiskCacheKey = {
+    /**
+     * Request URL.
+     */
+    url: string;
+    /**
+     * `Accept` header.
+     */
+    accept?: string;
+    /**
+     * Identity of the credential, never itself.
+     */
+    authRealm?: string;
+    /**
+     * `json`, `text` or `buffer`.
+     */
+    responseType?: string;
+};
+export type DiskCacheEntry = {
+    /**
+     * Schema version.
+     */
+    v: number;
+    /**
+     * Redacted URL.
+     */
+    url: string;
+    /**
+     * Always `GET`.
+     */
+    method: string;
+    /**
+     * HTTP status.
+     */
+    status: number;
+    /**
+     * ETag validator.
+     */
+    etag: string | null;
+    /**
+     * Last-Modified validator.
+     */
+    last_modified: string | null;
+    /**
+     * Unix seconds when fetched or revalidated.
+     */
+    fetched_at: number;
+    /**
+     * Response body.
+     */
+    body: any;
+    /**
+     * Never expires.
+     */
+    immutable?: boolean;
+};
+/**
+ * Hash of a cache key, as cdxrs computes it for a JSON response.
+ *
+ * @param {DiskCacheKey} key Cache key.
+ * @param {{miss?: boolean}} [opts] Whether this is the key of a recorded miss.
+ * @returns {string}
+ */
+export declare function diskCacheKeyHash(key: DiskCacheKey, { miss }?: {
+    miss?: boolean;
+}): string;
+/**
+ * Whether the disk cache may serve or store a request.
+ *
+ * @param {{url: string, headers?: Object, responseType?: string}} request
+ * @returns {boolean}
+ */
+export declare function diskCacheable(request: {
+    url: string;
+    headers?: Object;
+    responseType?: string;
+}): boolean;
+export type DiskCacheLookup = {
+    /**
+     * `fresh` and `miss` are
+     * answers; `stale` needs revalidation; `none` means nothing is stored.
+     */
+    state: "fresh" | "stale" | "miss" | "none";
+    /**
+     * The stored entry.
+     */
+    entry?: DiskCacheEntry;
+};
+/**
+ * @typedef {Object} DiskCacheLookup
+ * @property {"fresh"|"stale"|"miss"|"none"} state `fresh` and `miss` are
+ *   answers; `stale` needs revalidation; `none` means nothing is stored.
+ * @property {DiskCacheEntry} [entry] The stored entry.
+ */
+/**
+ * Look a request up.
+ *
+ * @param {DiskCacheKey} key Cache key.
+ * @returns {DiskCacheLookup}
+ */
+export declare function diskCacheGet(key: DiskCacheKey): DiskCacheLookup;
+/**
+ * Store a successful response.
+ *
+ * @param {DiskCacheKey} key Cache key.
+ * @param {{statusCode: number, headers?: Object, body: *}} response Response.
+ * @returns {void}
+ */
+export declare function diskCachePut(key: DiskCacheKey, response: {
+    statusCode: number;
+    headers?: Object;
+    body: any;
+}): void;
+/**
+ * Record that a request answered 404 or 410, and forget any body stored for it.
+ *
+ * @param {DiskCacheKey} key Cache key.
+ * @param {number} status HTTP status.
+ * @returns {void}
+ */
+export declare function diskCachePutMiss(key: DiskCacheKey, status: number): void;
+/**
+ * Mark a stale entry fresh again after a 304.
+ *
+ * @param {DiskCacheKey} key Cache key.
+ * @param {DiskCacheEntry} entry The stale entry.
+ * @param {Object} [headers] Headers of the 304, which may carry new validators.
+ * @returns {void}
+ */
+export declare function diskCacheRefresh(key: DiskCacheKey, entry: DiskCacheEntry, headers?: Object): void;
+/**
+ * Forget which host directories were swept. Tests only.
+ *
+ * @returns {void}
+ */
+export declare function resetDiskCacheState(): void;
+//# sourceMappingURL=fetchDiskCache.d.ts.map

package/types/lib/inventory/fetchDiskCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchDiskCache.d.ts","sourceRoot":"","sources":["../../../lib/inventory/fetchDiskCache.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAgDA,YAAkB,YAAY,GAC9B;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAoB,MAAM,AAA1B,CACA,EADW,MAAM,CACjB;;;;IAAoB,SAAS,AAA7B,CACA,EADW,MAAM,CACjB;;;;IAAoB,YAAY,AAAhC,CACF,EADa,MAAM,CACnB;CAAA,CAAA;AAGE,YAAkB,cAAc,GAChC;;;;IAAmB,CAAC,EAAT,MAAM,CACjB;;;;IAAmB,GAAG,EAAX,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAmB,MAAM,EAAd,MAAM,CACjB;;;;IAAwB,IAAI,EAAjB,MAAM,GAAC,IAAI,CACtB;;;;IAAwB,aAAa,EAA1B,MAAM,GAAC,IAAI,CACtB;;;;IAAmB,UAAU,EAAlB,MAAM,CACjB;;;;IAAc,IAAI,EAAP,GAAC,CACZ;;;;IAAqB,SAAS,AAA9B,CACF,EADa,OAAO,CACpB;CAAA,CAAA;AAgED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAJzB,YAIyB,EAAE,EAAE,IAAY,EAAE,AAHnD,CACA,EADQ;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAGiC,GAF9C,MAAM,CAYlB;AAmDD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAH1B;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAG3B,GAFxB,OAAO,CA6BnB;AA2EE,YAAkB,eAAe,GACjC;;;;;IAA0C,KAAK,EAApC,OAAO,GAAC,OAAO,GAAC,MAAM,GAAC,MAAM,CAExC;;;;IAA4B,KAAK,AAAjC,CACF,EADa,cAAc,CAC3B;CAAA,CAAA;AALD;;;;;GAKG;AAEH;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAHrB,YAGqB,GAFnB,eAAe,CAwB3B;AAkCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAJrB,YAIqB,EAAE,QAAQ,EAH/B;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,GAAC,CAAA;CAGf,GAF7B,IAAI,CAwBhB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAJzB,YAIyB,EAAE,MAAM,EAHjC,MAGiC,GAF/B,IAAI,CAqBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EALzB,YAKyB,EAAE,KAAK,EAJhC,cAIgC,EAAE,OAAO,AAHjD,CACA,EADQ,MAG8C,GAF5C,IAAI,CAahB;AAyGD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAFtB,IAAI,CAKhB"}

package/types/lib/inventory/forgeEnricher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forgeEnricher.d.ts","sourceRoot":"","sources":["../../../lib/inventory/forgeEnricher.js"],"names":[],"mappings":"AAkDA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAHvB,MAGuB,GAFrB;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAa9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAHvB,MAGuB,GAFrB,MAAM,GAAC,IAAI,CAWvB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAL9B,MAK8B,EAAE,SAAS,EAJzC,KAAK,CAAC,MAAM,CAI6B,EAAE,OAAO,GAHlD,MAGuD,GAFrD,OAAO,CAAC,MAAM,CAAC,CA4M3B"}
+{"version":3,"file":"forgeEnricher.d.ts","sourceRoot":"","sources":["../../../lib/inventory/forgeEnricher.js"],"names":[],"mappings":"AA2DA;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAHvB,MAGuB,GAFrB;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAC,IAAI,CAa9C;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAHvB,MAGuB,GAFrB,MAAM,GAAC,IAAI,CAWvB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAL9B,MAK8B,EAAE,SAAS,EAJzC,KAAK,CAAC,MAAM,CAI6B,EAAE,OAAO,GAHlD,MAGuD,GAFrD,OAAO,CAAC,MAAM,CAAC,CA4M3B"}

package/types/lib/inventory/jvmLocalRepos.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Forget every memoised lookup. A long-lived process (server mode) calls this
+ * per scan so that artifacts a build downloaded in the meantime are found, and
+ * tests call it after changing the cache environment variables.
+ *
+ * @returns {void}
+ */
+export declare function resetJvmLocalRepoCaches(): void;
+/**
+ * Read `<localRepository>` from a Maven settings file.
+ *
+ * @param {string} settingsFile Path to settings.xml.
+ * @returns {string|undefined} Absolute local repository path.
+ */
+export declare function localRepositoryFromSettings(settingsFile: string): string | undefined;
+/**
+ * Pull the values cdxgen needs out of a Maven argument list: the
+ * `maven.repo.local` system property and the user settings file.
+ *
+ * @param {string[]} args Parsed arguments.
+ * @param {string} [baseDir] Directory relative paths resolve against.
+ * @returns {{repoLocal?: string, settingsFile?: string}}
+ */
+export declare function mavenRepoArgs(args: string[], baseDir?: string): {
+    repoLocal?: string;
+    settingsFile?: string;
+};
+/**
+ * The arguments that hand a scanned project's own `settings.xml` to Maven.
+ *
+ * The file is passed as global settings (`-gs`), so the user's
+ * `~/.m2/settings.xml` still applies and wins on mirrors, servers and proxies.
+ * Nothing is added, and `skipped` says why, in secure mode, where a scanned
+ * repository must not choose Maven's repositories, proxies or credentials, or
+ * when MVN_ARGS or MAVEN_ARGS already names a settings file.
+ *
+ * @param {string} projectDir Directory holding the project's pom.xml.
+ * @param {{secureMode?: boolean}} [opts]
+ * @returns {{settingsFile?: string, args: string[], skipped?: "secure-mode"|"user-settings"}}
+ */
+export declare function projectSettingsArgs(projectDir: string, { secureMode }?: {
+    secureMode?: boolean;
+}): {
+    settingsFile?: string;
+    args: string[];
+    skipped?: "secure-mode" | "user-settings";
+};
+/**
+ * Every Maven local repository this run may have populated, most specific
+ * first: MAVEN_CACHE_DIR, then an explicit `-Dmaven.repo.local` (from
+ * MVN_ARGS, MAVEN_ARGS, MAVEN_OPTS or the project's `.mvn/maven.config`), then
+ * `<localRepository>` from the settings Maven would read, then
+ * `~/.m2/repository`.
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.projectDir] Project directory, for `.mvn/maven.config`.
+ * @returns {string[]} Absolute paths. Not filtered for existence.
+ */
+export declare function mavenLocalRepositories({ projectDir }?: {
+    projectDir?: string;
+}): string[];
+/**
+ * Gradle module cache directories (`.../modules-2/files-2.1`): the one under
+ * GRADLE_USER_HOME, the cdxgen-specific GRADLE_CACHE_DIR, the default
+ * `~/.gradle` when neither is set, and the read-only shared cache named by
+ * GRADLE_RO_DEP_CACHE.
+ *
+ * @returns {string[]} Absolute paths. Not filtered for existence.
+ */
+export declare function gradleCacheRoots(): string[];
+/**
+ * The Coursier cache directory used by sbt, Mill and scala-cli: COURSIER_CACHE
+ * when set, otherwise the platform default (XDG_CACHE_HOME is honoured on
+ * Linux).
+ *
+ * @returns {string|undefined} Absolute path. Not checked for existence.
+ */
+export declare function coursierCacheDir(): string | undefined;
+/**
+ * Convert a Coursier repository prefix into the repository URL it caches.
+ *
+ * @param {string[]} parts Prefix segments relative to the cache root.
+ * @returns {string|null} Repository URL.
+ */
+export declare function coursierPrefixToUrl(parts: string[]): string | null;
+/**
+ * Locate a Maven coordinate's directory in the Coursier cache.
+ *
+ * @param {string} group Maven groupId.
+ * @param {string} name Maven artifactId, including any Scala suffix.
+ * @param {string} version Version.
+ * @returns {{repoUrl: string, dir: string}|null} Repository URL and directory.
+ */
+export declare function locateInCoursierCache(group: string, name: string, version: string): {
+    repoUrl: string;
+    dir: string;
+} | null;
+/**
+ * Locate a Maven artifact and its POM in the local caches.
+ *
+ * Only the exact file names Maven, Gradle and Coursier use are accepted, so a
+ * classifier jar (`-sources`, `-javadoc`, `-linux-x86_64`) is never mistaken
+ * for the main artifact. Results, including misses, are memoised until
+ * {@link resetJvmLocalRepoCaches}.
+ *
+ * @param {string} group Maven groupId.
+ * @param {string} name Maven artifactId.
+ * @param {string} version Version.
+ * @param {Object} [opts]
+ * @param {string} [opts.classifier] Classifier of the wanted jar.
+ * @param {string} [opts.extension] Artifact extension. Defaults to jar.
+ * @param {string} [opts.projectDir] Project directory, for `.mvn/maven.config`.
+ * @returns {{jarPath?: string, pomPath?: string, sha1?: string, repoUrl?: string}|null}
+ */
+export declare function findLocalMavenArtifact(group: string, name: string, version: string, opts?: {
+    classifier?: string;
+    extension?: string;
+    projectDir?: string;
+}): {
+    jarPath?: string;
+    pomPath?: string;
+    sha1?: string;
+    repoUrl?: string;
+} | null;
+/**
+ * Split an artifact file name into its classifier and extension, given the
+ * artifactId and version it belongs to.
+ *
+ * @param {string} fileName File name, for example `netty-4.1.1-linux.jar`.
+ * @param {string} name artifactId.
+ * @param {string} version Version.
+ * @returns {{classifier: string, extension: string}|undefined} Undefined when
+ *   the name does not belong to the coordinate.
+ */
+export declare function splitArtifactFileName(fileName: string, name: string, version: string): {
+    classifier: string;
+    extension: string;
+} | undefined;
+/**
+ * Infer Maven coordinates from where an artifact sits on disk.
+ *
+ * Paths inside a configured Maven repository or Gradle cache are read by
+ * their layout. Paths elsewhere are recognised by the conventional
+ * `.m2/repository` and `files-2.1` segments, so a copied cache still works. A
+ * Coursier path is resolved through its sibling POM, because the repository
+ * prefix and the group path cannot be told apart from the path alone.
+ *
+ * @param {string} filePath Absolute path of a jar or other artifact.
+ * @returns {{group: string, name: string, version: string, classifier: string, extension: string, sha1?: string}|undefined}
+ */
+export declare function inferMavenCoordinatesFromPath(filePath: string): {
+    group: string;
+    name: string;
+    version: string;
+    classifier: string;
+    extension: string;
+    sha1?: string;
+} | undefined;
+/**
+ * Look up the Maven coordinates of a jar by its SHA-1 in the local caches.
+ *
+ * The index is built once, on first use, from the Gradle module cache (whose
+ * directory names are SHA-1s) and from the `*.jar.sha1` files Maven writes
+ * next to every downloaded jar. It answers the question cdxgen would otherwise
+ * send to the Maven Central search API.
+ *
+ * @param {string} sha1 Hex SHA-1 of the jar.
+ * @returns {{group: string, name: string, version: string, classifier: string, extension: string, path: string}|undefined}
+ */
+export declare function findMavenCoordinatesBySha1(sha1: string): {
+    group: string;
+    name: string;
+    version: string;
+    classifier: string;
+    extension: string;
+    path: string;
+} | undefined;
+//# sourceMappingURL=jvmLocalRepos.d.ts.map

package/types/lib/inventory/jvmLocalRepos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jvmLocalRepos.d.ts","sourceRoot":"","sources":["../../../lib/inventory/jvmLocalRepos.js"],"names":[],"mappings":"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"}

package/types/lib/inventory/mcpConfigParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcpConfigParser.d.ts","sourceRoot":"","sources":["../../../lib/inventory/mcpConfigParser.js"],"names":[],"mappings":"AAoxBA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAFlB;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAC,CAAA;CAiD9H,CAAC"}
+{"version":3,"file":"mcpConfigParser.d.ts","sourceRoot":"","sources":["../../../lib/inventory/mcpConfigParser.js"],"names":[],"mappings":"AAmxBA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,EAFlB;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG;QAAC,UAAU,EAAE,MAAM,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;KAAC,CAAA;CAiD9H,CAAC"}

package/types/lib/inventory/parentSelection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which detected project becomes the parent (`metadata.component`) when one
+ * scan covers several ecosystems and no parent was given.
+ *
+ * Each ecosystem detects its own project from its own manifest. The project
+ * whose manifest sits at the scan root describes the repository; one found
+ * deeper is a part of it (a web client in `tools/ui/`, a helper script's
+ * `pyproject.toml`). So candidates are ordered by how deep their ecosystem's
+ * manifests sit, the scan root first, and ties keep the ecosystem order the
+ * scan ran in.
+ */
+/**
+ * How deep the shallowest manifest of an ecosystem sits under a scan root:
+ * 0 for one at the root itself, `Infinity` when there is none (or the
+ * ecosystem is not one this module knows).
+ *
+ * @param {string} root Scan root
+ * @param {string} purlType Purl type of the ecosystem
+ * @param {Object} options CLI options (exclusions)
+ * @returns {number}
+ */
+export declare function manifestDepth(root: string, purlType: string, options?: Object): number;
+/**
+ * Order parent candidates by the depth of their ecosystem's manifests under
+ * the scan roots (the shallowest first). The sort is stable, so candidates of
+ * equal depth keep the order the ecosystems were scanned in.
+ *
+ * @param {Object[]} candidates Detected parent components, in scan order
+ * @param {string[]} roots Scan roots
+ * @param {Object} options CLI options
+ * @returns {Object[]} The candidates, reordered
+ */
+export declare function orderParentCandidates(candidates: Object[], roots: string[], options?: Object): Object[];
+//# sourceMappingURL=parentSelection.d.ts.map

package/types/lib/inventory/parentSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parentSelection.d.ts","sourceRoot":"","sources":["../../../lib/inventory/parentSelection.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AA8DH;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EALvB,MAKuB,EAAE,QAAQ,EAJjC,MAIiC,EAAE,OAAO,GAH1C,MAG+C,GAF7C,MAAM,CA2BlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EALrC,MAAM,EAK+B,EAAE,KAAK,EAJ5C,MAAM,EAIsC,EAAE,OAAO,GAHrD,MAG0D,GAFxD,MAAM,EAAE,CA4BpB"}

package/types/lib/inventory/plugins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../lib/inventory/plugins.js"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,wBAAgB,mBAAmB,IAFtB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAC,CAgCpF;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAXvB;IACR,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,GAAC,SAAS,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,GAAC,SAAS,CAAC;IACrC,aAAa,EAAE,MAAM,GAAC,SAAS,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB,CAqMH;AAYD;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAF1B,UAAU,CAAC,OAAO,oBAAoB,CAAC,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,AAH5C,CACA,EADQ,UAAU,CAAC,OAAO,oBAAoB,CAGU,GAF9C,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAWnD;AAwDD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAJjC,MAIiC,EAAE,aAAa,AAHxD,CACA,EADQ,UAAU,CAAC,OAAO,oBAAoB,CAGsB,GAF1D,MAAM,GAAC,SAAS,CAS5B"}
+{"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../../lib/inventory/plugins.js"],"names":[],"mappings":"AAiDA;;;;GAIG;AACH,wBAAgB,mBAAmB,IAFtB;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAC,CAgCpF;AA8DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAXvB;IACR,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,GAAC,SAAS,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,GAAC,SAAS,CAAC;IACrC,aAAa,EAAE,MAAM,GAAC,SAAS,CAAC;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB,CAqMH;AAYD;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAF1B,UAAU,CAAC,OAAO,oBAAoB,CAAC,CASnD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,AAH5C,CACA,EADQ,UAAU,CAAC,OAAO,oBAAoB,CAGU,GAF9C,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAWnD;AAyDD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAJjC,MAIiC,EAAE,aAAa,AAHxD,CACA,EADQ,UAAU,CAAC,OAAO,oBAAoB,CAGsB,GAF1D,MAAM,GAAC,SAAS,CAS5B"}

package/types/lib/inventory/protobom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protobom.d.ts","sourceRoot":"","sources":["../../../lib/inventory/protobom.js"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAIxD,OAAO,EAAE,cAAc,EAAE,CAAC;AAsB1B;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,gBAH7B,MAAM,GAAC,SAAS,KACd,OAGgE,CAAC;AAE9E;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,gBAHjC,MAAM,GAAC,SAAS,cAChB,MAAM,SAYhB,CAAC;AAgCF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,YAJb,MAAM,GAAG,MAAM,WACf,MAAM,gBACN,MAAM,GAAG,MAAM,SAezB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,YAJZ,MAAM,UACN,OAAO,gBACP,MAAM,GAAG,MAAM,4FAiBzB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,YAJb,MAAM,GAAG,MAAM,gBACf,MAAM,GAAG,MAAM,KACb,MAKV,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,YALvB,MAAM,GAAG,MAAM,qBACf,MAAM,GAAG,MAAM,gBACf,MAAM,GAAG,MAAM,KACb;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAahD,CAAC"}
+{"version":3,"file":"protobom.d.ts","sourceRoot":"","sources":["../../../lib/inventory/protobom.js"],"names":[],"mappings":"AAaA,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAIxD,OAAO,EAAE,cAAc,EAAE,CAAC;AAsB1B;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,gBAH7B,MAAM,GAAC,SAAS,KACd,OAGgE,CAAC;AAE9E;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,gBAHjC,MAAM,GAAC,SAAS,cAChB,MAAM,SAYhB,CAAC;AAgCF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,YAJb,MAAM,GAAG,MAAM,WACf,MAAM,gBACN,MAAM,GAAG,MAAM,SAezB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,YAJZ,MAAM,UACN,OAAO,gBACP,MAAM,GAAG,MAAM,4FAwBzB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,YAJb,MAAM,GAAG,MAAM,gBACf,MAAM,GAAG,MAAM,KACb,MAKV,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,YALvB,MAAM,GAAG,MAAM,qBACf,MAAM,GAAG,MAAM,gBACf,MAAM,GAAG,MAAM,KACb;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAahD,CAAC"}

package/types/lib/inventory/purl.d.ts

@@ -35,8 +35,17 @@ export declare function purlTypeIsRegistered(type: string): boolean;
  */
 export declare function purlTypeIsRegisteredString(purlString: string): boolean;
 /**
- * Encode a string for safe inclusion in a PackageURL, percent-encoding special characters
- * while preserving already-encoded `%40` sequences and keeping `:` and `/` unencoded.
+ * Encode a string for inclusion in a hand-written PackageURL string,
+ * percent-encoding every character the purl grammar does not allow literally,
+ * while preserving already-encoded `%40` sequences and keeping `:` and `/`
+ * unencoded.
+ *
+ * `encodeURIComponent` alone leaves `!`, `'`, `(`, `)` and `*` literal, and the
+ * purl grammar requires them escaped, so they are escaped here as well.
+ *
+ * Only for comparing against or assembling purl text. Never pass the result to
+ * `build()`, `new Purl()` or one of the helpers in this module: they escape
+ * their inputs themselves, and escaping twice turns `+` into `%252B`.
  *
  * @param {string} s String to encode
  * @returns {string} Encoded string suitable for use in a PackageURL component
@@ -195,6 +204,66 @@ export declare function genericPurl(name: string): string | null;
  * @returns {boolean} true when cdx-purl parses it
  */
 export declare function isValidPurl(candidate: string): boolean;
+/**
+ * Split a purl into its components without requiring it to be well-formed.
+ *
+ * `Purl.parse` rejects a purl whose parts are not already escaped, which is the
+ * case this exists to handle: a `bom-ref` (cdxgen writes the decoded form of the
+ * purl there), a `go mod graph` token such as `github.com/Azure/go-autorest@v14.2.0+incompatible`,
+ * or a purl from a third-party document that left a `+` or a `://` unescaped.
+ * The separators (`:`, `/`, `@`, `?`, `#`, `&`, `=`) are structural and are read
+ * positionally; everything between them is decoded and handed back raw, ready
+ * for `build` to escape correctly.
+ *
+ * The version is taken after the last `@` of the path, so a scoped npm name
+ * (`@scope/name@1.0.0`) and a composer branch version (`dev-feature/x`) both
+ * split correctly.
+ *
+ * @param {string} purl Purl to split
+ * @returns {{type: string, namespace: (string|null), name: string, version: (string|null), qualifiers: (Object|null), subpath: (string|null)}|null} Parts, or null when the purl has no type and name
+ */
+export declare function splitPurlLoose(purl: string): {
+    type: string;
+    namespace: (string | null);
+    name: string;
+    version: (string | null);
+    qualifiers: (Object | null);
+    subpath: (string | null);
+} | null;
+/**
+ * Parse a purl string that may carry unescaped reserved characters.
+ *
+ * A well-formed purl is parsed strictly, so its components come back exactly as
+ * cdx-purl reads them. Anything else is split structurally by
+ * {@link splitPurlLoose}. Use this where the input is known to be a decoded or
+ * hand-written purl (a `bom-ref`, a workspace reference, a package manager's
+ * `name@version` token), never to accept an invalid purl into a `purl` field:
+ * pass the parts to `build()` instead, which escapes them.
+ *
+ * @param {string} purlString Purl or decoded purl
+ * @returns {{type: string, namespace: (string|null), name: string, version: (string|null), qualifiers: (Object|null), subpath: (string|null)}|null} Raw components, or null when nothing purl-shaped remains
+ */
+export declare function parsePurlLoose(purlString: string): {
+    type: string;
+    namespace: (string | null);
+    name: string;
+    version: (string | null);
+    qualifiers: (Object | null);
+    subpath: (string | null);
+} | null;
+/**
+ * Turn a decoded or hand-written purl into a canonical, correctly escaped one.
+ *
+ * `bom-ref` values are the decoded form of a purl
+ * (`pkg:npm/foo@1.0.0+build`), which cdx-purl rightly rejects as a purl. This
+ * recovers the purl the ref was made from by splitting it structurally and
+ * rebuilding it with `build()`, so every reserved character is escaped exactly
+ * once.
+ *
+ * @param {string} purlString Purl or decoded purl
+ * @returns {string|null} Canonical purl string, or `null` when no valid purl can be built
+ */
+export declare function canonicalPurlFromLooseString(purlString: string): string | null;
 /**
  * Parse a purl string, returning `null` instead of throwing when it is invalid.
  *