@wangjunjian/dsh-github-trending 0.1.0 → 0.2.0

package/lib/summaries.js

@@ -0,0 +1,352 @@
+/**
+ * README-backed repository overviews generated through the harness LLM service.
+ *
+ * When enabled, every successful cache refresh enqueues the entry with the
+ * {@link OverviewGenerator}, which produces a short localized overview per
+ * repository, in rank order, current panel window first. Generation runs in
+ * the background and never blocks or fails the refresh.
+ *
+ * @module @wangjunjian/dsh-github-trending/summaries
+ */
+import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { USER_AGENT } from './tool.js';
+/** README filenames tried in order under the repository's default branch. */
+const README_CANDIDATES = ['README.md', 'readme.md', 'README.rst', 'README'];
+/** README input is truncated to this many characters before summarization. */
+const README_MAX_CHARS = 8000;
+/**
+ * Fetch a repository's README from its default branch.
+ *
+ * @param fullName - `owner/name` repository path.
+ * @param signal - optional cancellation signal.
+ * @returns the truncated README text, or `undefined` when unavailable.
+ */
+export async function fetchReadmeText(fullName, signal) {
+    for (const candidate of README_CANDIDATES) {
+        let response;
+        try {
+            response = await fetch(`https://raw.githubusercontent.com/${fullName}/HEAD/${candidate}`, {
+                headers: { 'User-Agent': USER_AGENT },
+                signal,
+            });
+        }
+        catch {
+            return undefined;
+        }
+        if (response.status === 404)
+            continue;
+        if (!response.ok)
+            return undefined;
+        const text = await response.text();
+        return text.slice(0, README_MAX_CHARS);
+    }
+    return undefined;
+}
+/** Abort signal that fires after `timeoutMs`, with its timer handle. */
+function deadline(timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort();
+    }, timeoutMs);
+    return { signal: controller.signal, cancel: () => clearTimeout(timer) };
+}
+/** Display names for the languages LLM generations can be written in. */
+export const LANGUAGE_NAMES = {
+    zh: 'Chinese (中文)',
+    en: 'English',
+};
+/**
+ * Stream one auxiliary LLM call to completion and return its text.
+ *
+ * A `max-tokens` finish keeps the text already received (the assembler drops
+ * only tool-call blocks) — slightly truncated prose beats no output for these
+ * best-effort generations. Other non-`stop` finishes throw, as does empty
+ * text; error messages name the call site and the provider/model route so a
+ * misbehaving route is diagnosable from logs.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param request - messages/system plus budget and a label for error messages.
+ * @returns the generated text.
+ */
+export async function streamGeneratedText(ctx, route, request) {
+    const call = deadline(request.timeoutMs);
+    try {
+        const assembler = new BlockAssembler();
+        for await (const chunk of ctx.llm.stream({
+            provider: route.provider,
+            model: route.model,
+            messages: request.messages,
+            system: request.system,
+            maxTokens: request.maxTokens,
+            signal: call.signal,
+        })) {
+            assembler.push(chunk);
+        }
+        const finish = assembler.finish;
+        if (finish.kind !== 'stop' && finish.kind !== 'max-tokens') {
+            const detail = 'failure' in finish ? finish.failure.message : finish.kind;
+            throw new Error(`${request.label} via ${route.provider}/${route.model} finished with ${finish.kind}: ${detail}`);
+        }
+        const text = assembler
+            .blocks()
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text)
+            .join('')
+            .trim();
+        if (text === '') {
+            throw new Error(`${request.label} via ${route.provider}/${route.model} returned empty text (finish: ${finish.kind})`);
+        }
+        return text;
+    }
+    finally {
+        call.cancel();
+    }
+}
+/**
+ * Generate a localized one-paragraph overview for a repository via the harness
+ * LLM service.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param repo - the trending repository being summarized.
+ * @param readme - truncated README text.
+ * @param options - resolved overview options.
+ * @returns the overview text.
+ */
+export async function summarizeRepository(ctx, route, repo, readme, options) {
+    const system = `You write concise overviews of GitHub repositories for a trending list. Write in ${LANGUAGE_NAMES[options.language]}. Reply with a single short paragraph (at most 80 words) explaining what the project is, what problem it solves, and why it might be gaining attention. No markdown, no preamble, no headings.`;
+    const messages = [
+        createUserMessage({
+            content: [
+                {
+                    type: 'text',
+                    text: `Repository: ${repo.fullName}\nDescription: ${repo.description ?? '(none)'}\n\nREADME (truncated):\n${readme}`,
+                },
+            ],
+            source: { kind: 'plugin', plugin: 'github-trending' },
+        }),
+    ];
+    return streamGeneratedText(ctx, route, {
+        messages,
+        system,
+        maxTokens: options.maxTokens,
+        timeoutMs: options.timeoutMs,
+        label: `overview generation for ${repo.fullName}`,
+    });
+}
+/**
+ * Enrich the top repositories of a refreshed cache entry with overviews.
+ *
+ * Runs sequentially to avoid bursting the LLM provider; a failure for one
+ * repository skips it and never fails the whole pass.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the calls.
+ * @param entry - the freshly refreshed cache entry (mutated in place).
+ * @param options - resolved overview options.
+ * @param hooks - optional per-repository progress hooks.
+ */
+export async function enrichEntryWithOverviews(ctx, route, entry, options, hooks) {
+    for (const repo of entry.repositories.slice(0, options.maxRepos)) {
+        if (hooks?.isStale?.() === true)
+            return;
+        hooks?.onRepoStart?.(repo);
+        let outcome = 'skipped';
+        let skipReason;
+        try {
+            const call = deadline(options.timeoutMs);
+            let readme;
+            try {
+                readme = await fetchReadmeText(repo.fullName, call.signal);
+            }
+            finally {
+                call.cancel();
+            }
+            if (readme === undefined) {
+                skipReason = 'no README found on the default branch';
+            }
+            else {
+                repo.overview = await summarizeRepository(ctx, route, repo, readme, options);
+                outcome = 'generated';
+            }
+        }
+        catch (error) {
+            // Skip this repository; the next refresh cycle will try again. Log the
+            // reason so a misbehaving provider/model route is diagnosable instead of
+            // silently producing no overviews.
+            skipReason = error instanceof Error ? error.message : String(error);
+            ctx.logger.warn('github-trending: overview generation skipped for %s: %s', repo.fullName, skipReason);
+        }
+        finally {
+            hooks?.onRepoDone?.(repo, outcome, skipReason);
+        }
+    }
+}
+/** Cache key format shared with the cache module: `${language}:${since}`. */
+function pendingKey(language, since) {
+    return `${language ?? ''}:${since}`;
+}
+/**
+ * Sequential overview scheduler.
+ *
+ * Refreshed cache entries are queued here instead of being enriched inline, so
+ * only one LLM call is in flight at a time and the window the user is looking
+ * at (reported via {@link setActiveSince} from the web route) is always
+ * processed first, from its first repository onward. The model route is
+ * resolved lazily at the start of every pass, so the current default-model
+ * selection always applies even if it changed after this plugin loaded.
+ * A re-request for the same
+ * key supersedes the queued entry and abandons any in-flight pass over the old
+ * entry object (refresh supersedes refresh), so the generator never spends
+ * minutes mutating an entry the cache has already replaced.
+ *
+ * Repositories whose overview could not be generated are remembered per entry
+ * ({@link failureReason}) so the web route can stop flagging them as pending
+ * instead of showing a permanent "generating" state, and can surface the
+ * reason; the next refresh creates a fresh entry object and retries them.
+ *
+ * {@link waitForChange} lets the web route long-poll: it resolves on every
+ * repo start/finish, so the panel learns about each overview the moment it
+ * lands.
+ */
+export class OverviewGenerator {
+    ctx;
+    resolveRoute;
+    options;
+    pending = new Map();
+    versions = new Map();
+    failures = new WeakMap();
+    listeners = new Set();
+    activeSince = 'daily';
+    draining = false;
+    current;
+    constructor(ctx, resolveRoute, options) {
+        this.ctx = ctx;
+        this.resolveRoute = resolveRoute;
+        this.options = options;
+    }
+    /** Tell the generator which time window the panel is currently showing. */
+    setActiveSince(since) {
+        this.activeSince = since;
+    }
+    /**
+     * Queue a freshly refreshed entry for overview generation. Fire-and-forget:
+     * generation runs in the background and never throws back to the caller.
+     *
+     * @param entry - the refreshed cache entry.
+     * @param language - optional language filter of the entry.
+     * @param since - time window of the entry.
+     */
+    request(entry, language, since) {
+        const key = pendingKey(language, since);
+        this.versions.set(key, (this.versions.get(key) ?? 0) + 1);
+        this.pending.set(key, entry);
+        void this.drain();
+    }
+    /** Number of queued windows still waiting for generation (for diagnostics). */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    /** Full name of the repository whose overview is being generated right now. */
+    get currentFullName() {
+        return this.current;
+    }
+    /**
+     * Why a previous pass over this entry failed to produce an overview for the
+     * repository, or `undefined` when it has not failed. Failures are tracked
+     * per entry object, so a refresh (which creates a new entry) resets them and
+     * the repository is retried.
+     */
+    failureReason(entry, fullName) {
+        return this.failures.get(entry)?.get(fullName);
+    }
+    /**
+     * Resolve on the next generation state change (a repository starting or
+     * finishing), or after `timeoutMs` — whichever comes first. Multiple callers
+     * may wait concurrently.
+     *
+     * @param timeoutMs - maximum time to wait.
+     */
+    waitForChange(timeoutMs) {
+        return new Promise((resolve) => {
+            const onChange = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                this.listeners.delete(onChange);
+                resolve();
+            }, timeoutMs);
+            this.listeners.add(onChange);
+        });
+    }
+    /** Wake every pending {@link waitForChange} caller. */
+    notifyChange() {
+        const listeners = [...this.listeners];
+        this.listeners.clear();
+        for (const listener of listeners)
+            listener();
+    }
+    recordFailure(entry, fullName, reason) {
+        let failed = this.failures.get(entry);
+        if (failed === undefined) {
+            failed = new Map();
+            this.failures.set(entry, failed);
+        }
+        failed.set(fullName, reason);
+    }
+    pickNext() {
+        const keys = [...this.pending.keys()];
+        const activeKey = keys.find((key) => key.endsWith(`:${this.activeSince}`));
+        const key = activeKey ?? keys[0];
+        if (key === undefined)
+            return undefined;
+        const entry = this.pending.get(key);
+        this.pending.delete(key);
+        if (entry === undefined)
+            return undefined;
+        return { key, entry, version: this.versions.get(key) ?? 0 };
+    }
+    async drain() {
+        if (this.draining)
+            return;
+        this.draining = true;
+        try {
+            for (;;) {
+                const next = this.pickNext();
+                if (next === undefined)
+                    return;
+                const { key, entry, version } = next;
+                try {
+                    // Resolve the model route per pass so a default-model change (or a
+                    // settings service that mounted after this plugin loaded) takes
+                    // effect without a host restart.
+                    const route = this.resolveRoute();
+                    await enrichEntryWithOverviews(this.ctx, route, entry, this.options, {
+                        isStale: () => this.versions.get(key) !== version,
+                        onRepoStart: (repo) => {
+                            this.current = repo.fullName;
+                            this.notifyChange();
+                        },
+                        onRepoDone: (repo, outcome, skipReason) => {
+                            this.current = undefined;
+                            if (outcome === 'skipped')
+                                this.recordFailure(entry, repo.fullName, skipReason ?? 'unknown');
+                            this.notifyChange();
+                        },
+                    });
+                }
+                catch {
+                    // A pass-level failure (e.g. the plugin context was disposed while
+                    // generation was in flight) must never reject the fire-and-forget
+                    // drain; the next refresh will re-queue the window.
+                }
+            }
+        }
+        finally {
+            this.draining = false;
+        }
+    }
+}
+//# sourceMappingURL=summaries.js.map

package/lib/types/cache.d.ts

@@ -16,6 +16,12 @@ export interface TrendingCacheOptions {
     intervalMs: number;
     /** Request timeout in milliseconds. */
     timeoutMs: number;
+    /**
+     * Optional hook invoked after every successful refresh (including scheduled
+     * ones). Called synchronously with the fresh entry; synchronous throws are
+     * swallowed so a hook failure can never break caching.
+     */
+    onRefreshed?: (entry: TrendingCacheEntry, language: string | undefined, since: string) => void;
 }
 /**
  * Simple in-memory cache with periodic refresh.
@@ -37,6 +43,14 @@ export declare class TrendingCache {
      * @returns the cached entry, or undefined when cold.
      */
     get(language: string | undefined, since: string): TrendingCacheEntry | undefined;
+    /**
+     * Find a repository by full name across all cached entries (any language,
+     * any window). Used to attach trending metadata to on-demand generations.
+     *
+     * @param fullName - `owner/name` repository path.
+     * @returns the repository, or undefined when not currently cached.
+     */
+    findRepository(fullName: string): TrendingRepository | undefined;
     /**
      * Fetch fresh data and store it. Reuses the configured timeout.
      *
@@ -46,6 +60,8 @@ export declare class TrendingCache {
      * @returns the freshly cached entry.
      */
     refresh(fetcher: (signal?: AbortSignal) => Promise<TrendingRepository[]>, language: string | undefined, since: string): Promise<TrendingCacheEntry>;
+    /** Invoke the optional onRefreshed hook, swallowing synchronous failures. */
+    private notifyRefreshed;
     /**
      * Fetch with a per-attempt timeout, retrying transient failures.
      *

package/lib/types/client/locales.d.ts

@@ -3,7 +3,7 @@
  *
  * @module @wangjunjian/dsh-github-trending/client/locales
  */
-export type GithubTrendingKey = 'action.label' | 'action.close' | 'panel.title' | 'panel.daily' | 'panel.weekly' | 'panel.monthly' | 'panel.refresh' | 'panel.loading' | 'panel.empty' | 'panel.error' | 'panel.cachedAt' | 'panel.autoRefresh' | 'panel.collapse' | 'repo.stars' | 'repo.forks' | 'repo.today';
+export type GithubTrendingKey = 'action.label' | 'action.close' | 'panel.title' | 'panel.daily' | 'panel.weekly' | 'panel.monthly' | 'panel.refresh' | 'panel.loading' | 'panel.empty' | 'panel.error' | 'panel.cachedAt' | 'panel.autoRefresh' | 'panel.collapse' | 'panel.overviewPending' | 'intro.hint' | 'intro.loading' | 'intro.error' | 'intro.retry' | 'intro.close' | 'repo.stars' | 'repo.forks' | 'repo.today';
 export declare const en: Record<GithubTrendingKey, string>;
 export declare const zh: Record<GithubTrendingKey, string>;
 //# sourceMappingURL=locales.d.ts.map

package/lib/types/index.d.ts

@@ -24,6 +24,28 @@ export interface Config {
     maxResults?: number;
     /** Background refresh interval (ms) for the UI cache. Defaults to 14400000 (4 hours). */
     refreshIntervalMs?: number;
+    /** Whether to generate LLM README overviews after each refresh. Defaults to false. */
+    overviewsEnabled?: boolean;
+    /** Language the overviews are written in: "zh" or "en". Defaults to "zh". */
+    overviewsLanguage?: string;
+    /** Only the top N repositories per window receive an overview. Defaults to 10. */
+    overviewsMaxRepos?: number;
+    /** Optional provider route override for overview calls (requires overviewsModel). */
+    overviewsProvider?: string;
+    /** Optional model id override for overview calls (requires overviewsProvider). */
+    overviewsModel?: string;
+    /**
+     * Output token cap per overview call. Defaults to 2048 — reasoning models
+     * spend tokens on thinking before emitting text, so a small cap starves the
+     * actual paragraph (observed as empty text with a max-tokens finish).
+     */
+    overviewsMaxTokens?: number;
+    /** Per-call timeout budget (ms) for one README fetch or LLM call. Defaults to 60000. */
+    overviewsTimeoutMs?: number;
+    /** Output token cap per introduction call. Defaults to 4096. */
+    introsMaxTokens?: number;
+    /** Timeout budget (ms) for one introduction generation. Defaults to 120000. */
+    introsTimeoutMs?: number;
 }
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "github-trending";

package/lib/types/intros.d.ts

@@ -0,0 +1,65 @@
+/**
+ * On-demand, README-backed project introductions generated through the harness
+ * LLM service.
+ *
+ * Unlike the automatic per-refresh overviews, a full introduction is generated
+ * only when the user clicks a repository's overview area in the panel
+ * (`GET /github-trending?intro=owner/name`), then cached in memory for the
+ * lifetime of the host process. Concurrent requests for the same repository
+ * share one in-flight generation.
+ *
+ * @module @wangjunjian/dsh-github-trending/intros
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { TrendingRepository } from './parser.js';
+import { type OverviewRoute } from './summaries.js';
+/** Resolved introduction-generation options from the plugin config. */
+export interface IntrosOptions {
+    /** Language the introduction is written in. */
+    language: 'zh' | 'en';
+    /** Output token cap per LLM call (reasoning models need the headroom). */
+    maxTokens: number;
+    /** Timeout budget (ms) for the whole generation. */
+    timeoutMs: number;
+}
+/**
+ * Generate a structured Markdown introduction for a repository via the harness
+ * LLM service.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param repo - trending metadata when the repository is in the cache.
+ * @param fullName - `owner/name` repository path.
+ * @param readme - truncated README text.
+ * @param options - resolved introduction options.
+ * @returns the Markdown introduction.
+ */
+export declare function generateIntroduction(ctx: Context, route: OverviewRoute, repo: TrendingRepository | undefined, fullName: string, readme: string, options: IntrosOptions): Promise<string>;
+/**
+ * On-demand introduction generator with in-memory caching and in-flight
+ * deduplication.
+ *
+ * Results are cached per `language:fullName` for the lifetime of the host
+ * process — introductions are prose about a repository's README, which rarely
+ * changes within a session. Failures are never cached, so the next click
+ * retries.
+ */
+export declare class IntroductionGenerator {
+    private readonly ctx;
+    private readonly resolveRoute;
+    private readonly options;
+    private readonly cache;
+    private readonly inflight;
+    constructor(ctx: Context, resolveRoute: () => OverviewRoute, options: IntrosOptions);
+    /**
+     * Get the introduction for a repository, generating it on first request.
+     *
+     * @param fullName - `owner/name` repository path.
+     * @param repo - trending metadata when available in the cache.
+     * @returns the Markdown introduction.
+     * @throws when the README is unavailable or the LLM call fails.
+     */
+    get(fullName: string, repo: TrendingRepository | undefined): Promise<string>;
+    private generate;
+}
+//# sourceMappingURL=intros.d.ts.map

package/lib/types/parser.d.ts

@@ -30,6 +30,8 @@ export interface TrendingRepository {
     forks: number;
     /** Stars gained today (or this week/month), if present. */
     starsToday: number;
+    /** LLM-generated localized overview; filled by the summaries module, never by the parser. */
+    overview?: string;
 }
 /**
  * Parse the GitHub Trending HTML and return the extracted repositories.

package/lib/types/summaries.d.ts

@@ -0,0 +1,174 @@
+/**
+ * README-backed repository overviews generated through the harness LLM service.
+ *
+ * When enabled, every successful cache refresh enqueues the entry with the
+ * {@link OverviewGenerator}, which produces a short localized overview per
+ * repository, in rank order, current panel window first. Generation runs in
+ * the background and never blocks or fails the refresh.
+ *
+ * @module @wangjunjian/dsh-github-trending/summaries
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type GenerateOptions } from '@deepseek-ai/dsh-llm';
+import type { TrendingCacheEntry } from './cache.js';
+import type { TrendingRepository } from './parser.js';
+/** Model route for the auxiliary overview calls. */
+export interface OverviewRoute {
+    /** Registered provider route. */
+    provider: string;
+    /** Provider-owned model id. */
+    model: string;
+}
+/** Resolved overview-generation options from the plugin config. */
+export interface OverviewsOptions {
+    /** Language the overview is written in. */
+    language: 'zh' | 'en';
+    /** Only the top N repositories of each window receive an overview. */
+    maxRepos: number;
+    /** Output token cap per LLM call. */
+    maxTokens: number;
+    /** Per-call timeout budget (ms) for one README fetch or LLM call. */
+    timeoutMs: number;
+}
+/**
+ * Fetch a repository's README from its default branch.
+ *
+ * @param fullName - `owner/name` repository path.
+ * @param signal - optional cancellation signal.
+ * @returns the truncated README text, or `undefined` when unavailable.
+ */
+export declare function fetchReadmeText(fullName: string, signal?: AbortSignal): Promise<string | undefined>;
+/** Display names for the languages LLM generations can be written in. */
+export declare const LANGUAGE_NAMES: Record<OverviewsOptions['language'], string>;
+/**
+ * Stream one auxiliary LLM call to completion and return its text.
+ *
+ * A `max-tokens` finish keeps the text already received (the assembler drops
+ * only tool-call blocks) — slightly truncated prose beats no output for these
+ * best-effort generations. Other non-`stop` finishes throw, as does empty
+ * text; error messages name the call site and the provider/model route so a
+ * misbehaving route is diagnosable from logs.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param request - messages/system plus budget and a label for error messages.
+ * @returns the generated text.
+ */
+export declare function streamGeneratedText(ctx: Context, route: OverviewRoute, request: {
+    messages: GenerateOptions['messages'];
+    system: string;
+    maxTokens: number;
+    timeoutMs: number;
+    label: string;
+}): Promise<string>;
+/**
+ * Generate a localized one-paragraph overview for a repository via the harness
+ * LLM service.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the call.
+ * @param repo - the trending repository being summarized.
+ * @param readme - truncated README text.
+ * @param options - resolved overview options.
+ * @returns the overview text.
+ */
+export declare function summarizeRepository(ctx: Context, route: OverviewRoute, repo: TrendingRepository, readme: string, options: OverviewsOptions): Promise<string>;
+/** Outcome of a single repository's overview attempt. */
+export type EnrichOutcome = 'generated' | 'skipped';
+/** Progress hooks for {@link enrichEntryWithOverviews}. */
+export interface EnrichHooks {
+    /** Called right before a repository's README fetch + LLM call starts. */
+    onRepoStart?: (repo: TrendingRepository) => void;
+    /**
+     * Called after a repository finishes, with its outcome and — for `skipped`
+     * outcomes — a short human-readable reason.
+     */
+    onRepoDone?: (repo: TrendingRepository, outcome: EnrichOutcome, skipReason?: string) => void;
+    /** Checked before each repository; returning true abandons the rest of the pass. */
+    isStale?: () => boolean;
+}
+/**
+ * Enrich the top repositories of a refreshed cache entry with overviews.
+ *
+ * Runs sequentially to avoid bursting the LLM provider; a failure for one
+ * repository skips it and never fails the whole pass.
+ *
+ * @param ctx - host context providing the `llm` service.
+ * @param route - provider/model route for the calls.
+ * @param entry - the freshly refreshed cache entry (mutated in place).
+ * @param options - resolved overview options.
+ * @param hooks - optional per-repository progress hooks.
+ */
+export declare function enrichEntryWithOverviews(ctx: Context, route: OverviewRoute, entry: TrendingCacheEntry, options: OverviewsOptions, hooks?: EnrichHooks): Promise<void>;
+/**
+ * Sequential overview scheduler.
+ *
+ * Refreshed cache entries are queued here instead of being enriched inline, so
+ * only one LLM call is in flight at a time and the window the user is looking
+ * at (reported via {@link setActiveSince} from the web route) is always
+ * processed first, from its first repository onward. The model route is
+ * resolved lazily at the start of every pass, so the current default-model
+ * selection always applies even if it changed after this plugin loaded.
+ * A re-request for the same
+ * key supersedes the queued entry and abandons any in-flight pass over the old
+ * entry object (refresh supersedes refresh), so the generator never spends
+ * minutes mutating an entry the cache has already replaced.
+ *
+ * Repositories whose overview could not be generated are remembered per entry
+ * ({@link failureReason}) so the web route can stop flagging them as pending
+ * instead of showing a permanent "generating" state, and can surface the
+ * reason; the next refresh creates a fresh entry object and retries them.
+ *
+ * {@link waitForChange} lets the web route long-poll: it resolves on every
+ * repo start/finish, so the panel learns about each overview the moment it
+ * lands.
+ */
+export declare class OverviewGenerator {
+    private readonly ctx;
+    private readonly resolveRoute;
+    private readonly options;
+    private readonly pending;
+    private readonly versions;
+    private readonly failures;
+    private readonly listeners;
+    private activeSince;
+    private draining;
+    private current;
+    constructor(ctx: Context, resolveRoute: () => OverviewRoute, options: OverviewsOptions);
+    /** Tell the generator which time window the panel is currently showing. */
+    setActiveSince(since: string): void;
+    /**
+     * Queue a freshly refreshed entry for overview generation. Fire-and-forget:
+     * generation runs in the background and never throws back to the caller.
+     *
+     * @param entry - the refreshed cache entry.
+     * @param language - optional language filter of the entry.
+     * @param since - time window of the entry.
+     */
+    request(entry: TrendingCacheEntry, language: string | undefined, since: string): void;
+    /** Number of queued windows still waiting for generation (for diagnostics). */
+    get pendingCount(): number;
+    /** Full name of the repository whose overview is being generated right now. */
+    get currentFullName(): string | undefined;
+    /**
+     * Why a previous pass over this entry failed to produce an overview for the
+     * repository, or `undefined` when it has not failed. Failures are tracked
+     * per entry object, so a refresh (which creates a new entry) resets them and
+     * the repository is retried.
+     */
+    failureReason(entry: TrendingCacheEntry, fullName: string): string | undefined;
+    /**
+     * Resolve on the next generation state change (a repository starting or
+     * finishing), or after `timeoutMs` — whichever comes first. Multiple callers
+     * may wait concurrently.
+     *
+     * @param timeoutMs - maximum time to wait.
+     */
+    waitForChange(timeoutMs: number): Promise<void>;
+    /** Wake every pending {@link waitForChange} caller. */
+    private notifyChange;
+    private recordFailure;
+    private pickNext;
+    private drain;
+}
+//# sourceMappingURL=summaries.d.ts.map