@bedolla/enriweb 0.1.5 → 0.1.7

package/dist/tools/WebSearchRegistryVerifier.d.ts

@@ -12,6 +12,17 @@
  * - GitHub releases (api.github.com)
  *
  * @module tools/WebSearchRegistryVerifier
+ *
+ * @remarks Size note (~1470 lines, documented exception to the <=700
+ * policy): the verifier intentionally keeps one module per concern-free
+ * boundary — URL candidate detection, the five ecosystem adapters (npm,
+ * PyPI, crates.io, NuGet, GitHub), semantic-version ranking, and the
+ * TTL/LRU caches — because the adapters share the failure-normalization
+ * and cache-key invariants that a split would otherwise duplicate. The
+ * bounded JSON transport (capped streaming, timeouts, Link pagination)
+ * was extracted to {@link WebSearchRegistryHttpReader} per the AR-9
+ * touch-extraction rule; a per-ecosystem file split remains the documented
+ * follow-up for the adapters themselves.
  */
 import type { WebSearchResultEntry } from "../client/EnriProxyClient.js";
 /**
@@ -97,14 +108,35 @@ export interface WebSearchRegistryVerifierDeps {
  * Enriches web search results with registry version verification.
  */
 export declare class WebSearchRegistryVerifier {
+    /**
+     * Capped JSON HTTP reader owning the registry transport concerns.
+     */
+    private readonly httpReader;
     /**
      * NuGet V3 service index endpoint.
      */
     private static readonly NUGET_SERVICE_INDEX_URL;
+    /**
+     * Maximum bytes read from one npm packument (full-version manifest).
+     *
+     * @remarks
+     * Popular packages legitimately exceed the shared 5 MB registry cap
+     * (thousands of versions with full metadata); parity with the EnriCode
+     * client plane's 16 MiB download budget for the same endpoint.
+     */
+    private static readonly NPM_PACKUMENT_MAX_BYTES;
     /**
      * Default concurrency for registry verification.
      */
     private static readonly DEFAULT_CONCURRENCY;
+    /**
+     * Time one cached error entity stays fresh before a retry.
+     */
+    private static readonly ERROR_CACHE_TTL_MS;
+    /**
+     * Maximum cached verification entries (LRU eviction beyond this count).
+     */
+    private static readonly MAX_CACHE_ENTRIES;
     /**
      * Dependencies.
      */
@@ -113,6 +145,16 @@ export declare class WebSearchRegistryVerifier {
      * In-memory TTL cache.
      */
     private readonly cache;
+    /**
+     * In-flight verification promises keyed by cache key.
+     *
+     * @remarks
+     * Single-flight coalescing: concurrent MCP requests verifying the same
+     * entity join one registry fetch instead of racing duplicates. Entries
+     * are removed when the verification settles (success, error or caller
+     * abort), so the map never outlives its requests.
+     */
+    private readonly inFlight;
     /**
      * Cached NuGet service index resolution.
      */
@@ -127,9 +169,10 @@ export declare class WebSearchRegistryVerifier {
      * Attempts to verify canonical versions for registry entities found in search results.
      *
      * @param results - Search results
+     * @param signal - Optional caller abort signal (stops queueing new verifications)
      * @returns Verified entities (best-effort)
      */
-    verifyFromSearchResults(results: WebSearchResultEntry[]): Promise<VerifiedRegistryEntity[]>;
+    verifyFromSearchResults(results: WebSearchResultEntry[], signal?: AbortSignal): Promise<VerifiedRegistryEntity[]>;
     /**
      * Collects registry candidates from search result URLs.
      *
@@ -137,14 +180,40 @@ export declare class WebSearchRegistryVerifier {
      * @returns Candidate list
      */
     private collectCandidates;
+    /**
+     * Maximum `releases` pages followed per GitHub verification.
+     */
+    private static readonly GITHUB_RELEASES_MAX_PAGES;
     /**
      * Verifies a single candidate, using cache when available.
      *
      * @param kind - Registry kind
      * @param name - Candidate name
+     * @param signal - Optional caller abort signal forwarded to registry fetches
      * @returns Verification result
      */
     private verifyCandidate;
+    /**
+     * Reports whether one failure is a caller cancellation.
+     *
+     * @remarks
+     * Internal subfetch timeouts are reclassified as `TimeoutError` upstream
+     * and stay cacheable like any transient error; only genuine caller aborts
+     * (or errors shaped like one, e.g. a Spanish "cancelada" message) skip
+     * the error cache.
+     *
+     * @param error - Failure from a registry fetch.
+     * @param signal - Caller abort signal threaded into the verification.
+     * @returns True for caller cancellations.
+     */
+    private static isCallerCancellation;
+    /**
+     * Maps transport failures to stable Spanish text.
+     *
+     * @param error - Failure from a registry fetch.
+     * @returns Spanish description for the cached error entity.
+     */
+    private static describeFetchError;
     /**
      * Runs tasks with a fixed concurrency limit.
      *
@@ -157,6 +226,7 @@ export declare class WebSearchRegistryVerifier {
      * Verifies npm package versions via the npm registry.
      *
      * @param packageName - npm package name (may be scoped)
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
     private verifyNpm;
@@ -164,6 +234,7 @@ export declare class WebSearchRegistryVerifier {
      * Verifies PyPI project versions via the PyPI JSON API.
      *
      * @param projectName - PyPI project name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
     private verifyPyPi;
@@ -171,6 +242,7 @@ export declare class WebSearchRegistryVerifier {
      * Verifies crates.io package versions via the crates.io API.
      *
      * @param crateName - Crate name
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
     private verifyCrates;
@@ -178,24 +250,32 @@ export declare class WebSearchRegistryVerifier {
      * Verifies NuGet package versions via NuGet V3 endpoints.
      *
      * @param packageId - NuGet package ID
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
     private verifyNuGet;
     /**
      * Verifies GitHub repository releases via GitHub REST API.
      *
+     * @remarks
+     * `latest_stable` comes from `/releases/latest` (GitHub's own newest
+     * non-prerelease, non-draft pick, immune to first-page truncation);
+     * prerelease candidates page through `/releases?per_page=100` following
+     * the `Link` header (up to {@link GITHUB_RELEASES_MAX_PAGES} pages, i.e.
+     * 300 newest releases — beyond that the first pages are what we keep).
+     *
      * @param repoSlug - Repository slug in the form "owner/repo"
+     * @param signal - Optional caller abort signal
      * @returns Verified registry entity
      */
     private verifyGitHub;
     /**
-     * Performs an HTTP GET expecting a JSON response.
+     * Parses one GitHub release entry into a version candidate.
      *
-     * @param url - Target URL
-     * @param options - Request options
-     * @returns Parsed JSON object/array
+     * @param raw - Release entry from the GitHub API
+     * @returns Candidate, or null for drafts/entries without a tag
      */
-    private fetchJson;
+    private tryParseGitHubReleaseCandidate;
     /**
      * Attempts to parse the npm package name from an npmjs.com URL.
      *
@@ -255,6 +335,10 @@ export declare class WebSearchRegistryVerifier {
     /**
      * Best-effort prerelease detection for PyPI version strings.
      *
+     * @remarks
+     * Covers PEP 440 separators and attached suffixes (`1.0b1`, `2.0beta1`)
+     * where the marker follows digits without a delimiter.
+     *
      * @param version - Version string
      * @returns True when prerelease-like
      */
@@ -275,13 +359,32 @@ export declare class WebSearchRegistryVerifier {
      * @returns Best candidate or null
      */
     private pickBestVersionCandidate;
+    /**
+     * Parses one ISO timestamp to epoch milliseconds.
+     *
+     * @param value - Timestamp string, if present.
+     * @returns Epoch milliseconds, or null when missing or unparsable.
+     */
+    private tryParseTimeMs;
     /**
      * Parses SemVer strings (best-effort).
      *
+     * @remarks
+     * Accepts two to four numeric components (`1.2` → `1.2.0`, `1.2.3.4`
+     * keeps the fourth as a build tiebreak) so partial registry versions
+     * still rank instead of dropping out.
+     *
      * @param raw - Version string
      * @returns Parsed semver or null
      */
     private tryParseSemVer;
+    /**
+     * Parses versions with attached prerelease suffixes (`2024.1b1`, `2.0rc2`).
+     *
+     * @param normalized - Version string without a leading "v".
+     * @returns Parsed semver or null.
+     */
+    private tryParseAttachedPrerelease;
     /**
      * Compares two SemVer values.
      *
@@ -307,6 +410,7 @@ export declare class WebSearchRegistryVerifier {
     /**
      * Resolves NuGet V3 endpoints from the service index, with caching.
      *
+     * @param signal - Optional caller abort signal
      * @returns Service index cache
      */
     private getNuGetServiceIndex;
@@ -316,6 +420,7 @@ export declare class WebSearchRegistryVerifier {
      * @param registrationsBaseUrl - Registrations base URL
      * @param lowerId - Lowercase package ID
      * @param version - Version string
+     * @param signal - Optional caller abort signal
      * @returns Published ISO 8601 timestamp or null
      */
     private tryFetchNuGetLeafPublishedAt;

package/dist/tools/WebSearchRegistryVerifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSearchRegistryVerifier.d.ts","sourceRoot":"","sources":["../../src/tools/WebSearchRegistryVerifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"WebSearchRegistryVerifier.d.ts","sourceRoot":"","sources":["../../src/tools/WebSearchRegistryVerifier.ts"],"names":[],"mappings":"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"}