@npm-safe/core-dsh 1.0.5

package/dist/llm/provider.js

@@ -0,0 +1,206 @@
+/**
+ * Multi-provider LLM scan core.
+ *
+ * This module hosts the unified {@link LlmProviderOptions} interface, the
+ * {@link LlmProviderType} enum, and the {@link createLlmProvider} factory
+ * that dispatches to a concrete provider implementation. The OpenAI-
+ * compatible provider ({@link OpenAICompatibleLlmProvider}) lives here as
+ * the reference implementation; Gemini and Anthropic providers live in
+ * sibling modules and are wired up through the factory.
+ *
+ * Shared parsing/validation helpers and the {@link LlmProviderError} class
+ * are imported from {@link ./parse.js} so every provider reuses the same
+ * logic instead of duplicating it.
+ */
+import { LlmProviderError, SYSTEM_PROMPT, buildReport, parseJsonObject, } from "./parse.js";
+import { GeminiLlmProvider } from "./gemini.js";
+import { AnthropicLlmProvider } from "./anthropic.js";
+// Re-export LlmProviderError for backward compatibility: index.ts and the
+// existing test suite import it from this module.
+export { LlmProviderError } from "./parse.js";
+// Re-export the concrete provider classes so tests and consumers can import
+// them from this barrel module alongside the factory and shared types.
+export { GeminiLlmProvider } from "./gemini.js";
+export { AnthropicLlmProvider } from "./anthropic.js";
+/**
+ * Supported LLM provider backends.
+ */
+export var LlmProviderType;
+(function (LlmProviderType) {
+    LlmProviderType["OpenAi"] = "openai";
+    LlmProviderType["Gemini"] = "gemini";
+    LlmProviderType["Anthropic"] = "anthropic";
+})(LlmProviderType || (LlmProviderType = {}));
+const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+const DEFAULT_MODEL = "gpt-4o-mini";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_INPUT_CHARS = 12_000;
+const DEFAULT_MAX_TOKENS = 4096;
+/**
+ * Construct an {@link LlmScanProvider} for the backend selected via
+ * {@link LlmProviderOptions.provider}. Defaults to the OpenAI-compatible
+ * provider.
+ *
+ * @param options - Provider configuration. When omitted, an OpenAI-
+ * compatible provider is constructed with environment-derived defaults.
+ * @returns A concrete {@link LlmScanProvider} instance.
+ */
+export function createLlmProvider(options) {
+    switch (options?.provider ?? LlmProviderType.OpenAi) {
+        case LlmProviderType.Gemini:
+            return new GeminiLlmProvider(options);
+        case LlmProviderType.Anthropic:
+            return new AnthropicLlmProvider(options);
+        default:
+            return new OpenAICompatibleLlmProvider(options);
+    }
+}
+/**
+ * OpenAI-compatible chat completions LLM scan provider.
+ *
+ * Talks to any endpoint that implements the `/chat/completions` surface
+ * (OpenAI, Azure OpenAI, local LM Studio / Ollama OpenAI shims, etc.).
+ */
+export class OpenAICompatibleLlmProvider {
+    apiKey;
+    baseUrl;
+    model;
+    timeoutMs;
+    maxInputChars;
+    maxTokens;
+    /**
+     * @param options - Provider configuration. Env-var fallbacks:
+     *   `apiKey` defaults to `process.env.OPENAI_API_KEY`.
+     */
+    constructor(options = {}) {
+        this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.model = options.model ?? DEFAULT_MODEL;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxInputChars = options.maxInputChars ?? DEFAULT_MAX_INPUT_CHARS;
+        this.maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    }
+    /** @inheritdoc */
+    async scan(input) {
+        if (!this.apiKey) {
+            return {
+                enabled: false,
+                reason: "LLM provider is not configured.",
+            };
+        }
+        const packageJsonBudget = Math.floor(this.maxInputChars / 3);
+        const packageJsonStr = input.packageJson
+            ? JSON.stringify(input.packageJson).slice(0, packageJsonBudget)
+            : undefined;
+        const content = JSON.stringify({
+            packageName: input.packageName,
+            version: input.version,
+            description: input.description,
+            readme: input.readme.slice(0, this.maxInputChars),
+            packageJson: packageJsonStr,
+        });
+        const payload = await this.request({
+            model: this.model,
+            temperature: 0,
+            max_tokens: this.maxTokens,
+            response_format: { type: "json_object" },
+            messages: [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content },
+            ],
+        }, input.signal);
+        const parsed = parseJsonObject(payload);
+        return buildReport(parsed, new Date().toISOString());
+    }
+    /** @inheritdoc */
+    async testConnection() {
+        if (!this.apiKey)
+            return false;
+        await this.request({
+            model: this.model,
+            messages: [{ role: "user", content: "Reply with OK." }],
+            max_tokens: this.maxTokens,
+        });
+        return true;
+    }
+    /**
+     * Issue a POST to `/chat/completions` with timeout and error normalization.
+     *
+     * @param body - The JSON request body.
+     * @param signal - Optional external abort signal combined with the owned
+     *   timeout controller via `AbortSignal.any`. An external abort propagates
+     *   as `DOMException('The operation was aborted.', 'AbortError')`.
+     * @returns The `choices[0].message.content` string from the response.
+     * @throws {LlmProviderError} On network, timeout, HTTP, or shape errors.
+     * @throws {DOMException} With name `AbortError` when `signal` is aborted.
+     */
+    async request(body, signal) {
+        if (!this.apiKey) {
+            throw new LlmProviderError("LLM provider is not configured.");
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // Combine the owned timeout controller with the external abort signal
+        // so either one aborts the fetch. When no external signal is supplied
+        // the owned controller is used directly.
+        const combinedSignal = signal
+            ? AbortSignal.any([controller.signal, signal])
+            : controller.signal;
+        try {
+            const response = await fetch(`${this.baseUrl}/chat/completions`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${this.apiKey}`,
+                },
+                body: JSON.stringify(body),
+                signal: combinedSignal,
+            });
+            if (!response.ok) {
+                throw new LlmProviderError(`LLM request failed with HTTP ${response.status}.`, response.status);
+            }
+            const json = (await response.json());
+            const content = readResponseContent(json);
+            if (!content)
+                throw new LlmProviderError("LLM response contained no content.");
+            return content;
+        }
+        catch (error) {
+            if (error instanceof LlmProviderError)
+                throw error;
+            if (error instanceof DOMException && error.name === "AbortError") {
+                // An external abort must propagate as AbortError (cooperative
+                // cancellation); the owned timeout is wrapped as LlmProviderError.
+                if (signal?.aborted) {
+                    throw new DOMException("The operation was aborted.", "AbortError");
+                }
+                throw new LlmProviderError("LLM request timed out.");
+            }
+            throw new LlmProviderError(`LLM request failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+/**
+ * Extract the `choices[0].message.content` string from an OpenAI-shaped
+ * chat completion response. Returns `undefined` when the shape does not
+ * match.
+ *
+ * @param value - The parsed JSON response body.
+ * @returns The content string, or `undefined`.
+ */
+function readResponseContent(value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const choices = value.choices;
+    if (!Array.isArray(choices) || choices.length === 0)
+        return undefined;
+    const message = choices[0];
+    if (!message || typeof message !== "object")
+        return undefined;
+    const content = message.message?.content;
+    return typeof content === "string" ? content : undefined;
+}
+//# sourceMappingURL=provider.js.map

package/dist/llm/provider.js.map

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

package/dist/registry/client.d.ts

@@ -0,0 +1,164 @@
+/**
+ * HTTP client for the npm registry API v2.
+ *
+ * This module provides {@link NpmRegistryClient}, a thin wrapper around the
+ * global `fetch` (available in Node 18+) that adds:
+ *
+ * - **Timeout**: each request is aborted after 10 seconds via an
+ *   `AbortController`.
+ * - **Retry with exponential backoff**: failed requests (network errors or
+ *   non-2xx responses) are retried up to 3 times with delays of 1s, 2s, and
+ *   4s between attempts.
+ * - **Compression**: the `Accept-Encoding` header advertises gzip and
+ *   deflate support.
+ * - **User-Agent**: a customisable UA header is sent on every request.
+ * - **Typed errors**: non-success responses and unrecoverable failures are
+ *   surfaced as {@link NpmRegistryError} carrying the HTTP status code and
+ *   status text.
+ *
+ * The client intentionally contains **no caching** and **no rate limiting**
+ * — those concerns are delegated to dedicated modules layered on top.
+ *
+ * @module registry/client
+ */
+import type { AbbreviatedVersion, PackageMetadata, SearchResult } from './types.js';
+/**
+ * HTTP client for the npm registry.
+ *
+ * Construct an instance once and reuse it across calls — the client holds no
+ * per-request mutable state beyond the configured base URL and User-Agent.
+ * All public methods are async and return parsed, typed JSON payloads.
+ *
+ * @example
+ * ```ts
+ * const client = new NpmRegistryClient();
+ * const meta = await client.getPackageMetadata('lodash');
+ * const manifest = await client.getVersionManifest('lodash', '4.17.21');
+ * const hits = await client.searchPackages('security', 10);
+ * ```
+ */
+export declare class NpmRegistryClient {
+    /** Base URL (no trailing slash) prepended to every request path. */
+    private readonly baseUrl;
+    /** User-Agent header value sent on every request. */
+    private readonly userAgent;
+    /** Explicit proxy URL from constructor options (highest priority). */
+    private readonly proxyUrl?;
+    /** Proxy dispatchers keyed by proxy URL, lazily created. */
+    private readonly proxyAgents;
+    /** Hosts that must bypass the proxy. */
+    private readonly noProxyHosts;
+    /**
+     * @param options - Optional configuration overriding the defaults.
+     * @param options.baseUrl - Registry base URL. Defaults to
+     *   `https://registry.npmjs.org`. A trailing slash is stripped.
+     * @param options.userAgent - User-Agent header value. Defaults to a
+     *   string identifying `@npm-safe/core`.
+     * @param options.proxy - Proxy URL (e.g. `http://127.0.0.1:7897`). When
+     *   omitted, the conventional environment variables are consulted.
+     */
+    constructor(options?: {
+        readonly baseUrl?: string;
+        readonly userAgent?: string;
+        readonly proxy?: string;
+    });
+    /**
+     * Resolve the fetch `dispatcher` to use for a request URL.
+     *
+     * Returns `undefined` when no proxy is configured or the hostname is in
+     * the `NO_PROXY` list; otherwise returns a lazily created
+     * {@link Dispatcher} for the active proxy.
+     *
+     * @param url - Fully-qualified request URL.
+     * @returns A proxy dispatcher, or `undefined` to use the default fetch.
+     */
+    private getDispatcher;
+    /**
+     * Fetch the full packument (metadata) for a package.
+     *
+     * Issues `GET {baseUrl}/{name}` and returns the parsed
+     * {@link PackageMetadata} document, which includes all published versions,
+     * dist-tags, and the readme.
+     *
+     * @param name - Package name (scoped names include the leading `@`).
+     * @param options - Optional request options. `options.signal` is forwarded
+     *   to the underlying fetch as part of a combined abort signal; an external
+     *   abort settles the promise promptly with an `AbortError` `DOMException`
+     *   (no retry).
+     * @returns The full package metadata document.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    getPackageMetadata(name: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<PackageMetadata>;
+    /**
+     * Fetch the abbreviated packument for a single published version.
+     *
+     * Issues `GET {baseUrl}/{name}/{version}` and returns the parsed
+     * {@link AbbreviatedVersion} manifest.
+     *
+     * @param name - Package name (scoped names include the leading `@`).
+     * @param version - Semver version string (e.g. `4.17.21`).
+     * @returns The abbreviated version manifest.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     */
+    getVersionManifest(name: string, version: string): Promise<AbbreviatedVersion>;
+    /**
+     * Search the registry for packages matching a text query.
+     *
+     * Issues `GET {baseUrl}/-/v1/search?text={query}&size={size}` and returns
+     * the array of {@link SearchResult} hits. The `size` parameter caps the
+     * number of results (the registry imposes its own upper bound).
+     *
+     * @param query - Free-text search query.
+     * @param options - Optional search options. `options.size` caps the number
+     *   of results (defaults to 20); `options.signal` is forwarded to the
+     *   underlying fetch as part of a combined abort signal.
+     * @returns An array of search-result hits, ordered by relevance.
+     * @throws {NpmRegistryError} When the request fails after all retries or
+     *   the registry returns a non-2xx status.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    searchPackages(query: string, options?: {
+        readonly size?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<SearchResult[]>;
+    /**
+     * Perform a single HTTP GET against `url` with timeout and retry.
+     *
+     * The request is retried up to {@link MAX_ATTEMPTS} times with exponential
+     * backoff (1s, 2s, 4s). A retry is attempted when:
+     *
+     * - The fetch rejects (network error, DNS failure, abort due to the owned
+     *   timeout controller).
+     * - The response status is not in the 2xx range.
+     *
+     * On the final attempt the underlying error (or a new
+     * {@link NpmRegistryError} for non-2xx responses) is rethrown.
+     *
+     * **Cooperative cancellation**: when `options.signal` is supplied it is
+     * combined with the per-request timeout controller via `AbortSignal.any`.
+     * An external abort (`options.signal` aborted) breaks the retry loop
+     * immediately and rethrows `DOMException('The operation was aborted.',
+     * 'AbortError')` with NO retry — the abort is never swallowed as a
+     * retryable timeout. Only the owned timeout controller keeps the existing
+     * wrap-as-`NpmRegistryError` + retry behaviour.
+     *
+     * @typeParam T - Expected shape of the parsed JSON response.
+     * @param url - Fully-qualified URL to fetch.
+     * @param options - Optional request options. `options.signal` is an
+     *   external abort signal forwarded by callers.
+     * @returns The parsed JSON response body typed as `T`.
+     * @throws {NpmRegistryError} When all attempts are exhausted or the
+     *   registry returns a non-2xx status on the final attempt.
+     * @throws {DOMException} With name `AbortError` when `options.signal` is
+     *   aborted.
+     */
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/registry/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/registry/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,YAAY,CAAC;AA+GpB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAiB;IAC5B,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,qDAAqD;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAS;IACnC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;IAC7D,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsB;IAEnD;;;;;;;;OAQG;gBACS,OAAO,CAAC,EAAE;QACpB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;KACzB;IAUD;;;;;;;;;OASG;IACH,OAAO,CAAC,aAAa;IAmBrB;;;;;;;;;;;;;;;;;OAiBG;IACG,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC1C,OAAO,CAAC,eAAe,CAAC;IAO3B;;;;;;;;;;;OAWG;IACG,kBAAkB,CACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,kBAAkB,CAAC;IAM9B;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAClE,OAAO,CAAC,YAAY,EAAE,CAAC;IAgB1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;YACW,OAAO;CAyGtB"}