Merge pull request #23 from fulll/feat/team-cache

Feat: cache GitHub team list (24 h) with --no-cache option

Author: shouze

AGENTS.md

@@ -71,6 +71,8 @@ src/
   api.ts                 # GitHub REST API client (search, team fetching)
   api-utils.ts           # Shared retry (fetchWithRetry) and pagination (paginatedFetch)
                          #   helpers used exclusively by api.ts — performs network I/O
+  cache.ts               # Disk cache for the team list (getCacheDir, getCacheKey,
+                         #   readCache, writeCache) — performs filesystem I/O
   aggregate.ts           # Result grouping & filtering (applyFiltersAndExclusions)
   group.ts               # groupByTeamPrefix — team-prefix grouping logic
   render.ts              # Façade re-exporting sub-modules + top-level
@@ -94,7 +96,7 @@ src/
 ## Key architectural principles
 
 - **Pure functions first.** All business logic lives in pure, side-effect-free functions (`aggregate.ts`, `group.ts`, `output.ts`, `render/` sub-modules). This makes them straightforward to unit-test.
-- **Side effects are isolated.** API calls (`api.ts`, `api-utils.ts`), TTY interaction (`tui.ts`) and CLI parsing (`github-code-search.ts`) are the only side-effectful surfaces. `api-utils.ts` hosts shared retry/pagination helpers that perform network I/O and must not be used outside `api.ts`.
+- **Side effects are isolated.** API calls (`api.ts`, `api-utils.ts`), TTY interaction (`tui.ts`) and CLI parsing (`github-code-search.ts`) are the only side-effectful surfaces. `api-utils.ts` hosts shared retry/pagination helpers that perform network I/O and must not be used outside `api.ts`. `cache.ts` hosts disk-cache helpers that perform filesystem I/O and must not be used outside `api.ts`.
 - **`render.ts` is a façade.** It re-exports everything from `render/` and adds two top-level rendering functions. Consumers import from `render.ts`, not directly from sub-modules.
 - **`types.ts` is the single source of truth** for all shared interfaces. Any new shared type must go there.
 - **No classes** — the codebase uses plain TypeScript interfaces and functions throughout.
@@ -105,6 +107,7 @@ src/
 - Use `describe` / `it` / `expect` from Bun's test runner.
 - Only pure functions need tests; `tui.ts` and `api.ts` are not unit-tested.
   `api-utils.ts` is the exception: its helpers are unit-tested by mocking `globalThis.fetch`.
+  `cache.ts` is also tested: it uses the `GITHUB_CODE_SEARCH_CACHE_DIR` env var override to redirect to a temp directory, so tests have no filesystem side effects on the real cache dir.
 - When adding a function to an existing module, add the corresponding test case in the existing `<module>.test.ts`.
 - When creating a new module that contains pure functions, create a companion `<module>.test.ts`.
 - Tests must be self-contained: no network calls, no filesystem side effects.

README.md

@@ -65,6 +65,7 @@ github-code-search upgrade
 | `--output-type <type>`           | ❌       | Output type: `repo-and-matches` (default) or `repo-only`                                              |
 | `--include-archived`             | ❌       | Include archived repositories in results (default: false)                                             |
 | `--group-by-team-prefix <pfxs>`  | ❌       | Comma-separated team-name prefixes to group repos by GitHub team (e.g. `squad-,chapter-`)             |
+| `--no-cache`                     | ❌       | Bypass the 24 h team-list cache and re-fetch teams from GitHub (only with `--group-by-team-prefix`)   |
 
 ## Interactive mode
 
@@ -391,6 +392,44 @@ Navigation (↑ / ↓) automatically skips section header rows.
 Fetching team membership requires the token to have the **`read:org`** (or
 `admin:org`) scope in addition to `repo` / `public_repo`.
 
+## Cache
+
+When `--group-by-team-prefix` is used, the tool caches the GitHub team list on
+disk for **24 hours** to avoid repeating dozens of API calls on every run.
+
+### Cache location
+
+| OS      | Path                                                                    |
+| ------- | ----------------------------------------------------------------------- |
+| macOS   | `~/Library/Caches/github-code-search/`                                  |
+| Linux   | `$XDG_CACHE_HOME/github-code-search/` or `~/.cache/github-code-search/` |
+| Windows | `%LOCALAPPDATA%\github-code-search\`                                    |
+
+You can also override the cache directory with the `GITHUB_CODE_SEARCH_CACHE_DIR`
+environment variable.
+
+### Bypassing the cache
+
+Pass `--no-cache` to skip the cache and force a fresh fetch:
+
+```bash
+github-code-search "useFeatureFlag" --org fulll \
+  --group-by-team-prefix squad- --no-cache
+```
+
+### Purging the cache
+
+```bash
+# macOS / Linux
+rm -rf ~/Library/Caches/github-code-search   # macOS
+rm -rf "${XDG_CACHE_HOME:-$HOME/.cache}/github-code-search"  # Linux
+```
+
+```powershell
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\github-code-search"
+```
+
 ## Known limitations
 
 - The GitHub Code Search API is capped at **1,000 results** per query and **10 requests/minute** without authentication (30/min with a token).

github-code-search.ts

@@ -90,6 +90,10 @@ function addSearchOptions(cmd: Command): Command {
         "then by the next prefix, and so on. Repos matching no prefix go into 'other'.",
       ].join("\n"),
       "",
+    )
+    .option(
+      "--no-cache",
+      "Bypass the 24 h team-list cache and re-fetch teams from GitHub (only applies with --group-by-team-prefix).",
     );
 }
 
@@ -105,6 +109,7 @@ async function searchAction(
     outputType: string;
     includeArchived: boolean;
     groupByTeamPrefix: string;
+    cache: boolean;
   },
 ): Promise<void> {
   // ─── GitHub API token ───────────────────────────────────────────────────────
@@ -144,7 +149,7 @@ async function searchAction(
       .map((p) => p.trim())
       .filter(Boolean);
     if (prefixes.length > 0) {
-      const teamMap = await fetchRepoTeams(org, GITHUB_TOKEN!, prefixes);
+      const teamMap = await fetchRepoTeams(org, GITHUB_TOKEN!, prefixes, opts.cache);
       // Attach team lists to each group
       for (const g of groups) {
         g.teams = teamMap.get(g.repoFullName) ?? [];

src/api.test.ts

@@ -322,7 +322,7 @@ describe("fetchRepoTeams", () => {
         headers: { "content-type": "application/json" },
       })) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     expect(result.size).toBe(0);
   });
 
@@ -342,7 +342,7 @@ describe("fetchRepoTeams", () => {
       });
     }) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     expect(result.get("myorg/my-repo")).toEqual(["frontend-web"]);
   });
 
@@ -365,7 +365,7 @@ describe("fetchRepoTeams", () => {
       });
     }) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     const slugs = result.get("myorg/shared-ui") ?? [];
     expect(slugs).toContain("frontend-web");
     expect(slugs).toContain("frontend-mobile");
@@ -374,7 +374,7 @@ describe("fetchRepoTeams", () => {
   it("throws when the teams list request fails", async () => {
     globalThis.fetch = (async () => new Response("Forbidden", { status: 403 })) as typeof fetch;
 
-    await expect(fetchRepoTeams("myorg", "tok", ["frontend"])).rejects.toThrow("403");
+    await expect(fetchRepoTeams("myorg", "tok", ["frontend"], false)).rejects.toThrow("403");
   });
 
   it("silently skips a team's repos when its repo list request fails", async () => {
@@ -389,7 +389,7 @@ describe("fetchRepoTeams", () => {
       return new Response("Not Found", { status: 404 });
     }) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     expect(result.size).toBe(0);
   });
 
@@ -422,7 +422,7 @@ describe("fetchRepoTeams", () => {
       });
     }) as typeof fetch;
 
-    await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     expect(teamPage).toBe(2);
   });
 
@@ -453,7 +453,7 @@ describe("fetchRepoTeams", () => {
       });
     }) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["frontend"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["frontend"], false);
     expect(result.has("myorg/repo-extra")).toBe(true);
     expect(result.has("myorg/repo-0")).toBe(true);
   });
@@ -473,7 +473,7 @@ describe("fetchRepoTeams", () => {
       });
     }) as typeof fetch;
 
-    const result = await fetchRepoTeams("myorg", "tok", ["FRONTEND"]);
+    const result = await fetchRepoTeams("myorg", "tok", ["FRONTEND"], false);
     expect(result.has("myorg/repo-a")).toBe(true);
   });
 });

src/api.ts

@@ -1,6 +1,7 @@
 import pc from "picocolors";
 import type { CodeMatch } from "./types.ts";
 import { fetchWithRetry, paginatedFetch } from "./api-utils.ts";
+import { getCacheKey, readCache, writeCache } from "./cache.ts";
 
 // ─── Raw GitHub API types (internal) ─────────────────────────────────────────
 
@@ -192,7 +193,20 @@ export async function fetchRepoTeams(
   org: string,
   token: string,
   prefixes: string[],
+  useCache = true,
 ): Promise<Map<string, string[]>> {
+  // ── Cache lookup ────────────────────────────────────────────────────────────
+  // The team list is quasi-static; cache it for 24 h to avoid dozens of API
+  // calls on every run. Bypass with useCache = false (--no-cache flag).
+  const cacheKey = getCacheKey(org, prefixes);
+  if (useCache) {
+    const cached = readCache<[string, string[]][]>(cacheKey);
+    if (cached !== null) {
+      process.stderr.write(pc.dim("Using cached team data (— use --no-cache to refresh)\n"));
+      return new Map(cached);
+    }
+  }
+
   const lowerPrefixes = prefixes.map((p) => p.toLowerCase());
 
   // ── 1. List all org teams (paginated), filtering to matching prefixes per page ──
@@ -278,5 +292,11 @@ export async function fetchRepoTeams(
     }),
   );
 
+  // ── Persist result ──────────────────────────────────────────────────────────
+  // Serialise the Map as an array of entries for JSON round-trip stability.
+  if (useCache) {
+    writeCache(cacheKey, [...repoTeams.entries()]);
+  }
+
   return repoTeams;
 }