devlensio 0.2.0

package/dist/summarizer/prompts.js

@@ -0,0 +1,205 @@
+// Call once before the batch loop.
+export function buildEdgeIndex(edges) {
+    const outgoing = new Map();
+    const incoming = new Map();
+    const getOrCreate = (map, nodeId, edgeType) => {
+        if (!map.has(nodeId))
+            map.set(nodeId, new Map());
+        const inner = map.get(nodeId);
+        if (!inner.has(edgeType))
+            inner.set(edgeType, []);
+        return inner.get(edgeType);
+    };
+    for (const edge of edges) {
+        getOrCreate(outgoing, edge.from, edge.type).push(edge.to);
+        getOrCreate(incoming, edge.to, edge.type).push(edge.from);
+    }
+    return { outgoing, incoming };
+}
+// Call once before the batch loop.
+export function buildRouteIndex(routes) {
+    const byFilePath = new Map();
+    for (const route of routes) {
+        byFilePath.set(route.filePath, route);
+    }
+    return { byFilePath };
+}
+// ─── System Prompt ────────────────────────────────────────────────────────────
+//
+// Built once per summarization run — same for every node.
+// Fingerprint gives the LLM project-level context for better business summaries.
+const BASE_SYSTEM_PROMPT = `You are a senior software engineer analyzing a codebase.
+Your job is to summarize a single code node based on its source code and context.
+
+Respond ONLY in this exact XML format — no preamble, no explanation outside the tags:
+
+<technical>
+HTML content describing what this code does: its inputs, outputs, side effects, and key logic.
+</technical>
+<business>
+HTML content describing what problem this solves in the product and what feature or domain it belongs to.
+</business>
+<security_severity>none|low|medium|high</security_severity>
+<security_summary>
+HTML content describing the vulnerability (if severity is not none): what data is at risk and how it could be exploited.
+Leave empty if severity is none.
+</security_summary>
+
+## Formatting rules for content inside the XML tags
+Use HTML markup — the output is rendered in a browser tooltip, sidebar panel, and detail panel. Follow these conventions:
+
+- Inline code, function names, variable names, parameter names, file paths:
+    <code>functionName()</code>  or  <code>someVariable</code>
+- Multi-line code blocks (more than one line of code):
+    <pre><code>const x = 1;\nreturn x;</code></pre>
+- Key points / bullet lists (preferred for 3+ items):
+    <ul><li>First point.</li><li>Second point.</li></ul>
+- Numbered steps (only when order matters):
+    <ol><li>Step one.</li><li>Step two.</li></ol>
+- Bold for important terms or labels: <strong>important</strong>
+- No <h1>/<h2> headings — use <strong> inline labels instead.
+- No inline styles. No <div> wrappers. No Markdown (no **, no backticks, no #).
+- Write in plain prose sentences; use lists only when there are three or more distinct items.
+- Keep paragraphs short — summaries are displayed in compact UI containers (200-300px wide).
+- Avoid long paragraphs; break complex ideas into <ul> lists for scanability.
+
+## Security summary guidelines
+The security_summary is displayed in a compact sidebar and a detail panel. Follow these rules:
+- Lead with the specific vulnerability type (e.g. "SQL injection", "XSS", "exposed secret").
+- Use <ul> lists when describing multiple risks or attack vectors.
+- Mention the affected data or resource (e.g. "user credentials", "database contents").
+- Keep it under 3 sentences for scanability.
+- Example: <ul><li><strong>SQL injection</strong>: User input in <code>query</code> is passed directly to <code>db.execute()</code> without parameterization.</li><li>Attackers can extract or modify database contents.</li></ul>
+
+## Severity guide
+  none   — no security concerns
+  low    — minor issue, limited impact (e.g. verbose error messages)
+  medium — potential vulnerability, needs attention (e.g. missing input validation)
+  high   — serious vulnerability, could be exploited (e.g. SQL injection, exposed secrets, missing auth)`;
+export function buildSystemPrompt(fingerprint) {
+    const lines = [];
+    lines.push(`Framework:     ${fingerprint.framework}`);
+    lines.push(`Language:      ${fingerprint.language}`);
+    lines.push(`Project type:  ${fingerprint.projectType}`);
+    if (fingerprint.stateManagement.length > 0)
+        lines.push(`State:         ${fingerprint.stateManagement.join(", ")}`);
+    if (fingerprint.databases.length > 0)
+        lines.push(`Databases:     ${fingerprint.databases.join(", ")}`);
+    if (fingerprint.dataFetching.length > 0)
+        lines.push(`Data fetching: ${fingerprint.dataFetching.join(", ")}`);
+    return `${BASE_SYSTEM_PROMPT}\n\n## Project Context\n${lines.join("\n")}`;
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+export const EDGE_LABELS = {
+    CALLS: "Calls",
+    READS_FROM: "Reads from",
+    WRITES_TO: "Writes to",
+    IMPORTS: "Imports",
+    PROP_PASS: "Passes props to",
+    EMITS: "Emits event",
+    LISTENS: "Listens to",
+    WRAPPED_BY: "Wrapped by",
+    GUARDS: "Guards",
+    HANDLES: "Handles",
+    TESTS: "Tests",
+    USES: "Uses"
+};
+// Renders a dep summary line — uses technicalSummary if available, else just the name.
+function depLine(depNode) {
+    const summary = depNode.technicalSummary
+        ? ` — ${depNode.technicalSummary.slice(0, 120)}`
+        : "";
+    return `  ${depNode.name} [${depNode.type}]${summary}`;
+}
+// ─── User Prompt Builder ──────────────────────────────────────────────────────
+function buildUserPrompt(ctx) {
+    const { node, allNodes, edgeIndex, routeIndex } = ctx;
+    const parts = [];
+    // ── Source code ───────────────────────────────────────────────
+    parts.push(`## Node: ${node.name} [${node.type}]`);
+    parts.push(`File: ${node.filePath}`);
+    parts.push("");
+    parts.push("### Source Code");
+    parts.push("```");
+    parts.push(node.rawCode ?? "(source not available)");
+    parts.push("```");
+    // ── Dependencies (outgoing edges) — O(1) lookup ───────────────
+    const outgoing = edgeIndex.outgoing.get(node.id);
+    if (outgoing && outgoing.size > 0) {
+        const depLines = [];
+        for (const [edgeType, targetIds] of outgoing) {
+            const label = EDGE_LABELS[edgeType] ?? edgeType;
+            for (const targetId of targetIds) {
+                const depNode = allNodes.get(targetId);
+                if (depNode)
+                    depLines.push(`${label}:\n${depLine(depNode)}`);
+            }
+        }
+        if (depLines.length > 0) {
+            parts.push("");
+            parts.push("### Dependencies");
+            parts.push(depLines.join("\n"));
+        }
+    }
+    // ── Used by (incoming edges) — O(1) lookup ────────────────────
+    const incoming = edgeIndex.incoming.get(node.id);
+    if (incoming && incoming.size > 0) {
+        const usedByLines = [];
+        for (const [edgeType, sourceIds] of incoming) {
+            const label = EDGE_LABELS[edgeType] ?? edgeType;
+            for (const sourceId of sourceIds) {
+                const sourceNode = allNodes.get(sourceId);
+                if (sourceNode)
+                    usedByLines.push(`${label} by: ${sourceNode.name} [${sourceNode.type}]`);
+            }
+        }
+        if (usedByLines.length > 0) {
+            parts.push("");
+            parts.push("### Used By");
+            parts.push(usedByLines.join("\n"));
+        }
+    }
+    // ── Route context — O(1) lookup ───────────────────────────────
+    const route = routeIndex.byFilePath.get(node.filePath);
+    if (route) {
+        parts.push("");
+        parts.push("### Route Context");
+        if ("httpMethod" in route) {
+            parts.push(`HTTP ${route.httpMethod} ${route.urlPath}`);
+            if (route.params && route.params.length > 0)
+                parts.push(`Dynamic params: ${route.params.join(", ")}`);
+        }
+        else {
+            parts.push(`${route.type} — ${route.urlPath}`);
+            if (route.isDynamic && route.params && route.params.length > 0)
+                parts.push(`Dynamic params: ${route.params.join(", ")}`);
+            if (route.httpMethods && route.httpMethods.length > 0)
+                parts.push(`HTTP methods: ${route.httpMethods.join(", ")}`);
+        }
+    }
+    return parts.join("\n");
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+// Builds the full message array for a single node — O(degree) not O(n).
+export function buildPrompt(ctx) {
+    return [
+        { role: "system", content: ctx.systemPrompt },
+        { role: "user", content: buildUserPrompt(ctx) },
+    ];
+}
+// Builds a grouped prompt for a cycle group.
+// Used when cycleGroup.size <= MAX_GROUP_SUMMARY_SIZE.
+export function buildCycleGroupPrompt(nodeIds, ctx) {
+    const nodes = nodeIds.map(id => ctx.allNodes.get(id)).filter(Boolean);
+    const userContent = nodes
+        .map(node => buildUserPrompt({ ...ctx, node }))
+        .join("\n\n---\n\n");
+    const systemWithNote = ctx.systemPrompt + "\n\n" +
+        `Note: The nodes above form a circular dependency group. ` +
+        `Summarize each one, keeping their mutual relationship in mind. ` +
+        `Repeat the XML block once per node, preceded by: <!-- node: {name} -->`;
+    return [
+        { role: "system", content: systemWithNote },
+        { role: "user", content: userContent },
+    ];
+}

package/dist/summarizer/providers/anthropic.d.ts

@@ -0,0 +1,9 @@
+import type { LLMClient, LLMRequest, NodeSummaryOutput } from "./types.js";
+export declare class AnthropicClient implements LLMClient {
+    readonly provider: "anthropic";
+    readonly model: string;
+    private client;
+    constructor(apiKey: string, model: string);
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}

package/dist/summarizer/providers/anthropic.js

@@ -0,0 +1,78 @@
+import Anthropic from "@anthropic-ai/sdk";
+// ─── Response Parser ──────────────────────────────────────────────────────────
+//
+// LLM is prompted to return strict XML — simple and reliable to parse.
+// Falls back gracefully if a tag is missing rather than throwing.
+//
+// Expected format:
+//   <technical>...</technical>
+//   <business>...</business>
+//   <security_severity>none|low|medium|high</security_severity>
+//   <security_summary>...</security_summary>
+const VALID_SEVERITIES = new Set(["none", "low", "medium", "high"]);
+function parseXmlTag(text, tag) {
+    const match = text.match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`));
+    return match ? match[1].trim() : "";
+}
+function parseResponse(raw) {
+    const technicalSummary = parseXmlTag(raw, "technical");
+    const businessSummary = parseXmlTag(raw, "business");
+    const severityRaw = parseXmlTag(raw, "security_severity").toLowerCase();
+    const securitySummary = parseXmlTag(raw, "security_summary");
+    const severity = VALID_SEVERITIES.has(severityRaw)
+        ? severityRaw
+        : "none";
+    return {
+        technicalSummary: technicalSummary || raw.trim(), // fallback: use raw if parse fails
+        businessSummary: businessSummary || "",
+        security: {
+            severity,
+            summary: severity === "none" ? "" : securitySummary,
+        },
+        tokensUsed: 0, // populated after API call
+    };
+}
+export class AnthropicClient {
+    constructor(apiKey, model) {
+        this.provider = "anthropic";
+        this.model = model;
+        this.client = new Anthropic({ apiKey });
+    }
+    async summarize(request) {
+        const systemMessage = request.messages.find(m => m.role === "system");
+        const userMessages = request.messages.filter(m => m.role !== "system");
+        const response = await this.client.messages.create({
+            model: this.model,
+            max_tokens: request.maxTokens ?? 2048,
+            temperature: request.temperature ?? 0,
+            system: systemMessage?.content,
+            messages: userMessages.map(m => ({ role: m.role, content: m.content })),
+        });
+        const raw = response.content[0].type === "text" ? response.content[0].text : "";
+        const result = parseResponse(raw);
+        result.tokensUsed = (response.usage.input_tokens ?? 0) + (response.usage.output_tokens ?? 0);
+        return result;
+    }
+    async validateConnection() {
+        try {
+            // Minimal call — 1 token in, 1 token out, just to verify key + model are valid
+            await this.client.messages.create({
+                model: this.model,
+                max_tokens: 10,
+                messages: [{ role: "user", content: "hi" }],
+            });
+        }
+        catch (err) {
+            const status = err?.status ?? err?.statusCode;
+            if (status === 401)
+                throw new Error(`Anthropic API key is invalid or missing. Check your key in config.`);
+            if (status === 403)
+                throw new Error(`Anthropic API key does not have permission to use model "${this.model}".`);
+            if (status === 404)
+                throw new Error(`Anthropic model "${this.model}" not found. Check model name in config.`);
+            if (status === 429)
+                throw new Error(`Anthropic rate limit hit during connection check. Try again shortly.`);
+            throw new Error(`Anthropic connection failed: ${err?.message ?? "unknown error"}`);
+        }
+    }
+}

package/dist/summarizer/providers/gemini.d.ts

@@ -0,0 +1,9 @@
+import type { LLMClient, LLMRequest, NodeSummaryOutput } from "./types.js";
+export declare class GeminiClient implements LLMClient {
+    readonly provider: "gemini";
+    readonly model: string;
+    private ai;
+    constructor(apiKey: string, model: string);
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}

package/dist/summarizer/providers/gemini.js

@@ -0,0 +1,79 @@
+import { GoogleGenAI } from "@google/genai";
+// ─── Response Parser ──────────────────────────────────────────────────────────
+//
+// Same XML format as all other providers — consistent across the board.
+const VALID_SEVERITIES = new Set(["none", "low", "medium", "high"]);
+function parseXmlTag(text, tag) {
+    const match = text.match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`));
+    return match ? match[1].trim() : "";
+}
+function parseResponse(raw) {
+    const technicalSummary = parseXmlTag(raw, "technical");
+    const businessSummary = parseXmlTag(raw, "business");
+    const severityRaw = parseXmlTag(raw, "security_severity").toLowerCase();
+    const securitySummary = parseXmlTag(raw, "security_summary");
+    const severity = VALID_SEVERITIES.has(severityRaw)
+        ? severityRaw
+        : "none";
+    return {
+        technicalSummary: technicalSummary || raw.trim(),
+        businessSummary: businessSummary || "",
+        security: {
+            severity,
+            summary: severity === "none" ? "" : securitySummary,
+        },
+        tokensUsed: 0,
+    };
+}
+export class GeminiClient {
+    constructor(apiKey, model) {
+        this.provider = "gemini";
+        this.model = model;
+        this.ai = new GoogleGenAI({ apiKey });
+    }
+    async summarize(request) {
+        const systemMessage = request.messages.find(m => m.role === "system");
+        const userMessages = request.messages.filter(m => m.role !== "system");
+        const contents = userMessages.map(m => ({
+            role: "user",
+            parts: [{ text: m.content }],
+        }));
+        const response = await this.ai.models.generateContent({
+            model: this.model,
+            contents,
+            config: {
+                systemInstruction: systemMessage?.content,
+                temperature: request.temperature ?? 0,
+                maxOutputTokens: request.maxTokens ?? 2048,
+            },
+        });
+        const raw = response.text ?? "";
+        const result = parseResponse(raw);
+        result.tokensUsed =
+            (response.usageMetadata?.promptTokenCount ?? 0) +
+                (response.usageMetadata?.candidatesTokenCount ?? 0);
+        return result;
+    }
+    async validateConnection() {
+        try {
+            await this.ai.models.generateContent({
+                model: this.model,
+                contents: [{ role: "user", parts: [{ text: "hi" }] }],
+                config: { maxOutputTokens: 10 },
+            });
+        }
+        catch (err) {
+            const status = err?.status ?? err?.statusCode ?? err?.code;
+            const message = err?.message ?? "";
+            if (status === 400 || message.includes("API_KEY_INVALID") || message.includes("invalid api key"))
+                throw new Error(`Gemini API key is invalid or missing. Check your key in config.`);
+            if (status === 403 || message.includes("PERMISSION_DENIED"))
+                throw new Error(`Gemini API key does not have permission to use model "${this.model}".`);
+            if (status === 404 || message.includes("models/") || message.includes("not found"))
+                throw new Error(`Gemini model "${this.model}" not found. Check model name in config.`);
+            if (status === 429 || message.includes("RESOURCE_EXHAUSTED"))
+                throw new Error(`Gemini rate limit hit during connection check. Try again shortly.`);
+            throw new Error(`Gemini connection failed: ${message || "unknown error"}`);
+        }
+    }
+}

package/dist/summarizer/providers/index.d.ts

@@ -0,0 +1,3 @@
+import type { SummarizationConfig } from "../../config/types.js";
+import type { LLMClient } from "./types.js";
+export declare function createLLMClient(config: SummarizationConfig): LLMClient;

package/dist/summarizer/providers/index.js

@@ -0,0 +1,43 @@
+// providers/index.ts has one job — given the config, return the right LLMClient instance. It's the factory that the batch loop calls so it never has to know which provider is being used.
+import { AnthropicClient } from "./anthropic.js";
+import { GeminiClient } from "./gemini.js";
+import { OllamaClient } from "./ollama.js";
+import { OpenAIClient } from "./openai.js";
+import { OpenRouterClient } from "./openRouter.js";
+// ─── Factory ──────────────────────────────────────────────────────────────────
+//
+// Single entry point for the batch loop — returns the right LLMClient
+// based on config. Caller never imports individual provider classes.
+//
+// Throws clearly if:
+//   - provider is unknown
+//   - apiKey is missing for cloud providers (fail fast before the batch loop)
+export function createLLMClient(config) {
+    const { provider, model, apiKey, baseUrl } = config;
+    switch (provider) {
+        case "anthropic":
+            if (!apiKey)
+                throw new Error("Anthropic provider requires an API key");
+            return new AnthropicClient(apiKey, model);
+        case "openai":
+            if (!apiKey)
+                throw new Error("OpenAI provider requires an API key");
+            return new OpenAIClient(apiKey, model);
+        case "openrouter":
+            if (!apiKey)
+                throw new Error("OpenRouter provider requires an API key");
+            return new OpenRouterClient(apiKey, model);
+        case "gemini":
+            if (!apiKey)
+                throw new Error("Gemini provider requires an API key");
+            return new GeminiClient(apiKey, model);
+        case "ollama":
+            return new OllamaClient(model, baseUrl);
+        case "managed":
+            // Cloud SaaS only — platform injects the key via request headers.
+            // Should never reach here in local mode.
+            throw new Error("Managed provider is only available in cloud mode");
+        default:
+            throw new Error(`Unknown LLM provider: ${provider}`);
+    }
+}

package/dist/summarizer/providers/ollama.d.ts

@@ -0,0 +1,9 @@
+import type { LLMClient, LLMRequest, NodeSummaryOutput } from "./types.js";
+export declare class OllamaClient implements LLMClient {
+    readonly provider: "ollama";
+    readonly model: string;
+    private inner;
+    constructor(model: string, baseURL?: string);
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}

package/dist/summarizer/providers/ollama.js

@@ -0,0 +1,23 @@
+import { OpenAIClient } from "./openai.js";
+const OLLAMA_DEFAULT_BASE_URL = "http://localhost:11434";
+// ─── OllamaClient ─────────────────────────────────────────────────────────────
+//
+// Ollama exposes an OpenAI-compatible API at /v1 — wraps OpenAIClient.
+// No API key needed for local usage — passes a placeholder to satisfy the SDK.
+// baseURL is configurable for users running Ollama on a non-default port or host.
+// /v1 is always appended — user-provided baseURL should not include it.
+export class OllamaClient {
+    constructor(model, baseURL) {
+        this.provider = "ollama";
+        this.model = model;
+        const base = (baseURL ?? OLLAMA_DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.inner = new OpenAIClient("ollama", // placeholder — Ollama doesn't validate the key
+        model, `${base}/v1`);
+    }
+    summarize(request) {
+        return this.inner.summarize(request);
+    }
+    validateConnection() {
+        return this.inner.validateConnection();
+    }
+}

package/dist/summarizer/providers/openRouter.d.ts

@@ -0,0 +1,9 @@
+import type { LLMClient, LLMRequest, NodeSummaryOutput } from "./types.js";
+export declare class OpenRouterClient implements LLMClient {
+    readonly provider: "openrouter";
+    readonly model: string;
+    private inner;
+    constructor(apiKey: string, model: string);
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}

package/dist/summarizer/providers/openRouter.js

@@ -0,0 +1,19 @@
+import { OpenAIClient } from "./openai.js";
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+// ─── OpenRouterClient ─────────────────────────────────────────────────────────
+//
+// OpenRouter exposes an OpenAI-compatible API — no new logic needed.
+// Just wraps OpenAIClient with the correct baseURL and overrides provider. (OpenAI actually set the industry standard for the response of the LLMs through API.Everyone follows the OpenAI standard,  Aside of course Anthropic, because its anthropic, who even go against pentagon.)
+export class OpenRouterClient {
+    constructor(apiKey, model) {
+        this.provider = "openrouter";
+        this.model = model;
+        this.inner = new OpenAIClient(apiKey, model, OPENROUTER_BASE_URL);
+    }
+    summarize(request) {
+        return this.inner.summarize(request);
+    }
+    validateConnection() {
+        return this.inner.validateConnection();
+    }
+}

package/dist/summarizer/providers/openai.d.ts

@@ -0,0 +1,9 @@
+import type { LLMClient, LLMRequest, NodeSummaryOutput } from "./types.js";
+export declare class OpenAIClient implements LLMClient {
+    readonly provider: "openai";
+    readonly model: string;
+    private client;
+    constructor(apiKey: string, model: string, baseURL?: string);
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}

package/dist/summarizer/providers/openai.js

@@ -0,0 +1,72 @@
+import OpenAI from "openai";
+// ─── Response Parser ──────────────────────────────────────────────────────────
+//
+// Same XML format as anthropic.ts — consistent across all providers.
+// Prompt in prompts.ts always requests this format regardless of provider.
+const VALID_SEVERITIES = new Set(["none", "low", "medium", "high"]);
+function parseXmlTag(text, tag) {
+    const match = text.match(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`));
+    return match ? match[1].trim() : "";
+}
+function parseResponse(raw) {
+    const technicalSummary = parseXmlTag(raw, "technical");
+    const businessSummary = parseXmlTag(raw, "business");
+    const severityRaw = parseXmlTag(raw, "security_severity").toLowerCase();
+    const securitySummary = parseXmlTag(raw, "security_summary");
+    const severity = VALID_SEVERITIES.has(severityRaw)
+        ? severityRaw
+        : "none";
+    return {
+        technicalSummary: technicalSummary || raw.trim(),
+        businessSummary: businessSummary || "",
+        security: {
+            severity,
+            summary: severity === "none" ? "" : securitySummary,
+        },
+        tokensUsed: 0,
+    };
+}
+// Also used as the base for OpenRouter and Ollama —
+// both expose OpenAI-compatible APIs, just with a different baseURL.
+export class OpenAIClient {
+    constructor(apiKey, model, baseURL) {
+        this.provider = "openai";
+        this.model = model;
+        this.client = new OpenAI({ apiKey, ...(baseURL ? { baseURL } : {}) });
+    }
+    async summarize(request) {
+        const response = await this.client.chat.completions.create({
+            model: this.model,
+            temperature: request.temperature ?? 0,
+            max_tokens: request.maxTokens ?? 2048,
+            messages: request.messages.map(m => ({ role: m.role, content: m.content })),
+        });
+        const raw = response.choices[0]?.message?.content ?? "";
+        const result = parseResponse(raw);
+        result.tokensUsed = response.usage
+            ? (response.usage.prompt_tokens + response.usage.completion_tokens)
+            : 0;
+        return result;
+    }
+    async validateConnection() {
+        try {
+            await this.client.chat.completions.create({
+                model: this.model,
+                max_tokens: 10,
+                messages: [{ role: "user", content: "hi" }],
+            });
+        }
+        catch (err) {
+            const status = err?.status ?? err?.statusCode;
+            if (status === 401)
+                throw new Error(`API key is invalid or missing. Check your key in config.`);
+            if (status === 403)
+                throw new Error(`API key does not have permission to use model "${this.model}".`);
+            if (status === 404)
+                throw new Error(`Model "${this.model}" not found. Check model name in config.`);
+            if (status === 429)
+                throw new Error(`Rate limit hit during connection check. Try again shortly.`);
+            throw new Error(`LLM connection failed: ${err?.message ?? "unknown error"}`);
+        }
+    }
+}

package/dist/summarizer/providers/types.d.ts

@@ -0,0 +1,32 @@
+import type { LLMProvider } from "../../config/types.js";
+export interface LLMMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+}
+export interface LLMRequest {
+    messages: LLMMessage[];
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface SecuritySummary {
+    severity: "none" | "low" | "medium" | "high";
+    summary: string;
+}
+export interface NodeSummaryOutput {
+    technicalSummary: string;
+    businessSummary: string;
+    security: SecuritySummary;
+    tokensUsed: number;
+}
+export interface LLMClient {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    summarize(request: LLMRequest): Promise<NodeSummaryOutput>;
+    validateConnection(): Promise<void>;
+}
+export type LLMClientFactory = (config: {
+    provider: LLMProvider;
+    model: string;
+    apiKey?: string;
+    baseUrl?: string;
+}) => LLMClient;

package/dist/summarizer/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/summarizer/retry.d.ts

@@ -0,0 +1,7 @@
+export interface RetryOptions {
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+}
+export declare const DEFAULT_RETRY_OPTIONS: RetryOptions;
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions, label?: string): Promise<T>;