fix: add search result caching, project health caching, and repo score TTL (#511)

- Cache GitHub search API results with 15-minute TTL to reduce rate limit
  consumption when oss-search is run multiple times in quick succession
- Cache project health check results with 4-hour TTL to avoid redundant
  API calls when the same repo appears across multiple search phases
- Enforce 30-day TTL on repo scores in getLowScoringRepos() so stale low
  scores don't permanently block repos from appearing in search results
- Extract reusable cachedTimeBased() helper in http-cache.ts for time-based
  caching without ETag/conditional requests
- Add warning log for corrupted lastEvaluatedAt dates in state

Closes #487

Author: costajohnt

packages/core/src/core/http-cache.ts

@@ -299,6 +299,32 @@ export async function cachedRequest<T>(
   }
 }
 
+/**
+ * Time-based cache wrapper (no ETag / conditional requests).
+ *
+ * If a cached result exists and is younger than `maxAgeMs`, returns it.
+ * Otherwise calls `fetcher`, caches the result, and returns it.
+ *
+ * Use this for expensive operations whose results change slowly
+ * (e.g. search queries, project health checks).
+ */
+export async function cachedTimeBased<T>(
+  cache: HttpCache,
+  key: string,
+  maxAgeMs: number,
+  fetcher: () => Promise<T>,
+): Promise<T> {
+  const cached = cache.getIfFresh(key, maxAgeMs);
+  if (cached) {
+    debug(MODULE, `Time-based cache hit for ${key}`);
+    return cached as T;
+  }
+
+  const result = await fetcher();
+  cache.set(key, '', result);
+  return result;
+}
+
 /**
  * Detect whether an error is a 304 Not Modified response.
  * Octokit throws a RequestError with status 304 for conditional requests.

packages/core/src/core/issue-discovery.test.ts

@@ -11,6 +11,29 @@ vi.mock('./github.js', () => ({
   checkRateLimit: vi.fn().mockResolvedValue({ remaining: 30, limit: 30, resetAt: new Date().toISOString() }),
 }));
 
+vi.mock('./http-cache.js', () => ({
+  getHttpCache: vi.fn().mockReturnValue({
+    getIfFresh: vi.fn().mockReturnValue(null),
+    get: vi.fn().mockReturnValue(null),
+    set: vi.fn(),
+    hasInflight: vi.fn().mockReturnValue(false),
+    getInflight: vi.fn().mockReturnValue(undefined),
+    setInflight: vi.fn().mockReturnValue(() => {}),
+  }),
+  // Pass through to the fetcher so octokit mocks are still exercised
+  cachedRequest: vi.fn().mockImplementation(async (_cache: unknown, _url: string, fetcher: (h: Record<string, string>) => Promise<{ data: unknown }>) => {
+    const response = await fetcher({});
+    return response.data;
+  }),
+  cachedTimeBased: vi.fn().mockImplementation(async (cache: any, _key: string, _maxAgeMs: number, fetcher: () => Promise<unknown>) => {
+    const cached = cache.getIfFresh(_key, _maxAgeMs);
+    if (cached) return cached;
+    const result = await fetcher();
+    cache.set(_key, '', result);
+    return result;
+  }),
+}));
+
 vi.mock('./state.js', () => ({
   getStateManager: vi.fn(() => ({
     getState: () => ({
@@ -1457,6 +1480,55 @@ describe('Phase 3: actively maintained repos (#349)', () => {
   });
 });
 
+describe('Search result caching (#487)', () => {
+  let discovery: InstanceType<typeof IssueDiscovery>;
+  let mockCache: any;
+
+  beforeEach(async () => {
+    const { getHttpCache } = await import('./http-cache.js');
+    mockCache = (getHttpCache as any)();
+    mockCache.getIfFresh.mockReturnValue(null);
+    mockCache.set.mockClear();
+
+    mockOctokitInstance = {
+      issues: { get: vi.fn(), listEventsForTimeline: vi.fn().mockResolvedValue({ data: [] }) },
+      search: { issuesAndPullRequests: vi.fn().mockResolvedValue({ data: { total_count: 0, items: [] } }) },
+      repos: {
+        get: vi.fn().mockResolvedValue({ data: { open_issues_count: 0, pushed_at: new Date().toISOString(), stargazers_count: 100, forks_count: 10 } }),
+        listCommits: vi.fn().mockResolvedValue({ data: [{ commit: { author: { date: new Date().toISOString() } } }] }),
+        getContent: vi.fn().mockRejectedValue(new Error('404 Not Found')),
+      },
+      actions: { listRepoWorkflows: vi.fn().mockResolvedValue({ data: { total_count: 0 } }) },
+      paginate: { iterator: vi.fn() },
+      activity: { listReposStarredByAuthenticatedUser: vi.fn() },
+    };
+    discovery = new IssueDiscovery('fake-token');
+  });
+
+  it('should call cache.set after a fresh search API call', async () => {
+    mockOctokitInstance.search.issuesAndPullRequests.mockResolvedValue({
+      data: { total_count: 0, items: [] },
+    });
+
+    await expect(discovery.searchIssues({ maxResults: 1 })).rejects.toThrow();
+
+    // cache.set should have been called for the Phase 2 search
+    expect(mockCache.set).toHaveBeenCalled();
+    const setCall = mockCache.set.mock.calls[0];
+    expect(setCall[0]).toMatch(/^search:/); // cache key starts with search:
+  });
+
+  it('should return cached results when getIfFresh returns data', async () => {
+    const cachedData = { total_count: 0, items: [] };
+    mockCache.getIfFresh.mockReturnValue(cachedData);
+
+    await expect(discovery.searchIssues({ maxResults: 1 })).rejects.toThrow();
+
+    // Octokit search should NOT have been called (cached results used)
+    expect(mockOctokitInstance.search.issuesAndPullRequests).not.toHaveBeenCalled();
+  });
+});
+
 describe('DOC_ONLY_LABELS', () => {
   it('should contain the expected documentation labels', () => {
     expect(DOC_ONLY_LABELS.has('documentation')).toBe(true);

packages/core/src/core/issue-discovery.ts

@@ -16,6 +16,7 @@ import { daysBetween, getDataDir } from './utils.js';
 import { DEFAULT_CONFIG, type SearchPriority, type IssueCandidate } from './types.js';
 import { ValidationError, errorMessage, getHttpStatusCode } from './errors.js';
 import { debug, info, warn } from './logger.js';
+import { getHttpCache, cachedTimeBased } from './http-cache.js';
 import { type GitHubSearchItem, isDocOnlyIssue, detectLabelFarmingRepos, applyPerRepoCap } from './issue-filtering.js';
 import { IssueVetter } from './issue-vetting.js';
 import { calculateViabilityScore as calcViabilityScore, type ViabilityScoreParams } from './issue-scoring.js';
@@ -39,6 +40,9 @@ export type { SearchPriority, IssueCandidate } from './types.js';
 
 const MODULE = 'issue-discovery';
 
+/** TTL for cached search API results (15 minutes). */
+const SEARCH_CACHE_TTL_MS = 15 * 60 * 1000;
+
 export class IssueDiscovery {
   private octokit: Octokit;
   private stateManager: ReturnType<typeof getStateManager>;
@@ -55,6 +59,29 @@ export class IssueDiscovery {
     this.vetter = new IssueVetter(this.octokit, this.stateManager);
   }
 
+  /**
+   * Wrap octokit.search.issuesAndPullRequests with time-based caching.
+   * Repeated identical queries within SEARCH_CACHE_TTL_MS return cached results
+   * without consuming GitHub API rate limit points.
+   */
+  private async cachedSearch(params: {
+    q: string;
+    sort: string;
+    order: string;
+    per_page: number;
+  }): Promise<{ total_count: number; items: GitHubSearchItem[] }> {
+    const cacheKey = `search:${params.q}:${params.sort}:${params.order}:${params.per_page}`;
+    return cachedTimeBased(
+      getHttpCache(),
+      cacheKey,
+      SEARCH_CACHE_TTL_MS,
+      async () => {
+        const { data } = await this.octokit.search.issuesAndPullRequests(params);
+        return data;
+      },
+    );
+  }
+
   /**
    * Fetch the authenticated user's starred repositories from GitHub.
    * Updates the state manager with the list and timestamp.
@@ -375,7 +402,7 @@ export class IssueDiscovery {
       info(MODULE, 'Phase 2: General issue search...');
       const remainingNeeded = maxResults - allCandidates.length;
       try {
-        const { data } = await this.octokit.search.issuesAndPullRequests({
+        const data = await this.cachedSearch({
           q: baseQuery,
           sort: 'created',
           order: 'desc',
@@ -433,7 +460,7 @@ export class IssueDiscovery {
           .trim();
 
       try {
-        const { data } = await this.octokit.search.issuesAndPullRequests({
+        const data = await this.cachedSearch({
           q: phase3Query,
           sort: 'updated',
           order: 'desc',
@@ -568,7 +595,7 @@ export class IssueDiscovery {
         const repoFilter = batch.map((r) => `repo:${r}`).join(' OR ');
         const batchQuery = `${baseQuery} (${repoFilter})`;
 
-        const { data } = await this.octokit.search.issuesAndPullRequests({
+        const data = await this.cachedSearch({
           q: batchQuery,
           sort: 'created',
           order: 'desc',

packages/core/src/core/issue-vetting.test.ts

@@ -10,8 +10,22 @@ vi.mock('./pagination.js', () => ({
 }));
 
 vi.mock('./http-cache.js', () => ({
-  getHttpCache: vi.fn().mockReturnValue({}),
+  getHttpCache: vi.fn().mockReturnValue({
+    getIfFresh: vi.fn().mockReturnValue(null),
+    get: vi.fn().mockReturnValue(null),
+    set: vi.fn(),
+    hasInflight: vi.fn().mockReturnValue(false),
+    getInflight: vi.fn().mockReturnValue(undefined),
+    setInflight: vi.fn().mockReturnValue(() => {}),
+  }),
   cachedRequest: vi.fn(),
+  cachedTimeBased: vi.fn().mockImplementation(async (cache: any, _key: string, _maxAgeMs: number, fetcher: () => Promise<unknown>) => {
+    const cached = cache.getIfFresh(_key, _maxAgeMs);
+    if (cached) return cached;
+    const result = await fetcher();
+    cache.set(_key, '', result);
+    return result;
+  }),
 }));
 
 vi.mock('./logger.js', () => ({
@@ -505,6 +519,45 @@ describe('checkProjectHealth', () => {
     expect(health.stargazersCount).toBeUndefined();
     expect(health.forksCount).toBeUndefined();
   });
+
+  it('returns cached health when getIfFresh returns data (#487)', async () => {
+    const { getHttpCache } = await import('./http-cache.js');
+    const mockCache = (getHttpCache as any)();
+    const cachedHealth = {
+      repo: 'owner/repo',
+      lastCommitAt: '2025-06-30T00:00:00Z',
+      daysSinceLastCommit: 1,
+      openIssuesCount: 10,
+      avgIssueResponseDays: 0,
+      ciStatus: 'passing',
+      isActive: true,
+      stargazersCount: 500,
+      forksCount: 50,
+    };
+    mockCache.getIfFresh.mockReturnValueOnce(cachedHealth);
+    vi.mocked(cachedRequest).mockClear();
+
+    const health = await vetter.checkProjectHealth('owner', 'repo');
+    expect(health).toEqual(cachedHealth);
+    // API should NOT have been called (cachedRequest is used for repo.get)
+    expect(cachedRequest).not.toHaveBeenCalled();
+  });
+
+  it('caches health result after fresh API call (#487)', async () => {
+    const { getHttpCache } = await import('./http-cache.js');
+    const mockCache = (getHttpCache as any)();
+    mockCache.getIfFresh.mockReturnValue(null);
+    mockCache.set.mockClear();
+
+    const health = await vetter.checkProjectHealth('owner', 'repo');
+    expect(health.isActive).toBe(true);
+    // cache.set should have been called with the health result
+    expect(mockCache.set).toHaveBeenCalledWith(
+      'health:owner/repo',
+      '',
+      expect.objectContaining({ repo: 'owner/repo', isActive: true }),
+    );
+  });
 });
 
 describe('fetchContributionGuidelines', () => {

packages/core/src/core/issue-vetting.ts

@@ -18,7 +18,7 @@ import {
 } from './types.js';
 import { ValidationError, errorMessage, getHttpStatusCode } from './errors.js';
 import { warn } from './logger.js';
-import { getHttpCache, cachedRequest } from './http-cache.js';
+import { getHttpCache, cachedRequest, cachedTimeBased } from './http-cache.js';
 import { getStateManager } from './state.js';
 import { calculateRepoQualityBonus, calculateViabilityScore } from './issue-scoring.js';
 
@@ -37,6 +37,8 @@ export interface CheckResult {
 // Cache for contribution guidelines (expires after 1 hour, max 100 entries)
 const guidelinesCache = new Map<string, { guidelines: ContributionGuidelines | undefined; fetchedAt: number }>();
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+/** TTL for cached project health results (4 hours). Health data (stars, commits, CI) changes slowly. */
+const HEALTH_CACHE_TTL_MS = 4 * 60 * 60 * 1000;
 const CACHE_MAX_SIZE = 100;
 
 function pruneCache(): void {
@@ -447,58 +449,62 @@ export class IssueVetter {
   }
 
   async checkProjectHealth(owner: string, repo: string): Promise<ProjectHealth> {
-    try {
-      // Get repo info (with ETag caching — repo metadata changes infrequently)
-      const cache = getHttpCache();
-      const url = `/repos/${owner}/${repo}`;
-      const repoData = await cachedRequest(
-        cache,
-        url,
-        (headers) =>
-          this.octokit.repos.get({ owner, repo, headers }) as Promise<{
-            data: { open_issues_count: number; pushed_at: string; stargazers_count: number; forks_count: number };
-            headers: Record<string, string>;
-          }>,
-      );
-
-      // Get recent commits
-      const { data: commits } = await this.octokit.repos.listCommits({
-        owner,
-        repo,
-        per_page: 1,
-      });
+    const cache = getHttpCache();
+    const healthCacheKey = `health:${owner}/${repo}`;
 
-      const lastCommit = commits[0];
-      const lastCommitAt = lastCommit?.commit?.author?.date || repoData.pushed_at;
-      const daysSinceLastCommit = daysBetween(new Date(lastCommitAt));
+    try {
+      return await cachedTimeBased(cache, healthCacheKey, HEALTH_CACHE_TTL_MS, async () => {
+        // Get repo info (with ETag caching — repo metadata changes infrequently)
+        const url = `/repos/${owner}/${repo}`;
+        const repoData = await cachedRequest(
+          cache,
+          url,
+          (headers) =>
+            this.octokit.repos.get({ owner, repo, headers }) as Promise<{
+              data: { open_issues_count: number; pushed_at: string; stargazers_count: number; forks_count: number };
+              headers: Record<string, string>;
+            }>,
+        );
 
-      // Check CI status (simplified - just check if workflows exist)
-      let ciStatus: 'passing' | 'failing' | 'unknown' = 'unknown';
-      try {
-        const { data: workflows } = await this.octokit.actions.listRepoWorkflows({
+        // Get recent commits
+        const { data: commits } = await this.octokit.repos.listCommits({
           owner,
           repo,
           per_page: 1,
         });
-        if (workflows.total_count > 0) {
-          ciStatus = 'passing'; // Assume passing if workflows exist
+
+        const lastCommit = commits[0];
+        const lastCommitAt = lastCommit?.commit?.author?.date || repoData.pushed_at;
+        const daysSinceLastCommit = daysBetween(new Date(lastCommitAt));
+
+        // Check CI status (simplified - just check if workflows exist)
+        let ciStatus: 'passing' | 'failing' | 'unknown' = 'unknown';
+        try {
+          const { data: workflows } = await this.octokit.actions.listRepoWorkflows({
+            owner,
+            repo,
+            per_page: 1,
+          });
+          if (workflows.total_count > 0) {
+            ciStatus = 'passing'; // Assume passing if workflows exist
+          }
+        } catch (error) {
+          const errMsg = errorMessage(error);
+          warn(MODULE, `Failed to check CI status for ${owner}/${repo}: ${errMsg}. Defaulting to unknown.`);
         }
-      } catch (error) {
-        const errMsg = errorMessage(error);
-        warn(MODULE, `Failed to check CI status for ${owner}/${repo}: ${errMsg}. Defaulting to unknown.`);
-      }
 
-      return {
-        repo: `${owner}/${repo}`,
-        lastCommitAt,
-        daysSinceLastCommit,
-        openIssuesCount: repoData.open_issues_count,
-        avgIssueResponseDays: 0, // Would need more API calls to calculate
-        ciStatus,
-        isActive: daysSinceLastCommit < 30,
-        stargazersCount: repoData.stargazers_count,
-        forksCount: repoData.forks_count,
-      };
+        return {
+          repo: `${owner}/${repo}`,
+          lastCommitAt,
+          daysSinceLastCommit,
+          openIssuesCount: repoData.open_issues_count,
+          avgIssueResponseDays: 0, // Would need more API calls to calculate
+          ciStatus,
+          isActive: daysSinceLastCommit < 30,
+          stargazersCount: repoData.stargazers_count,
+          forksCount: repoData.forks_count,
+        };
+      });
     } catch (error) {
       const errMsg = errorMessage(error);
       warn(MODULE, `Error checking project health for ${owner}/${repo}: ${errMsg}`);