@intentius/chant 0.46.0 → 0.50.0

package/src/audit/catalog.ts

@@ -26,10 +26,13 @@ export type FixKind = "deterministic" | "guidance";
  * What kind of finding this is — orthogonal to `tier` (fix confidence). Lets the
  * report say "N security, M best-practice, K correctness" instead of branding
  * everything "security." `security` = exposure/vuln/supply-chain; `correctness`
- * = a structural bug (broken reference, invalid schema, never-runs); everything
- * else is `best-practice` (hygiene/style/deprecation/reliability).
+ * = a structural bug (broken reference, invalid schema, never-runs); `efficiency`
+ * (#444) = waste — redundant work, an oversized execution environment,
+ * unintended fan-out, unbounded retention — never a safety/correctness issue,
+ * so it is excluded from the security and correctness tallies; everything else
+ * is `best-practice` (hygiene/style/deprecation/reliability).
  */
-export type Category = "security" | "correctness" | "best-practice";
+export type Category = "security" | "correctness" | "best-practice" | "efficiency";
 
 export interface Authority {
   name: string;
@@ -96,6 +99,34 @@ export const K8S_SECRETS: Authority = {
   name: "Kubernetes — Good practices for Secrets",
   url: "https://kubernetes.io/docs/concepts/security/secrets-good-practices/",
 };
+export const GH_SECRET_SCANNING: Authority = {
+  name: "GitHub — About secret scanning",
+  url: "https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning",
+};
+export const SCORECARD_VULN: Authority = {
+  name: "OSSF Scorecard — Vulnerabilities",
+  url: "https://github.com/ossf/scorecard/blob/main/docs/checks.md#vulnerabilities",
+};
+export const CF_WORKERS_DEV: Authority = {
+  name: "Cloudflare Workers — workers.dev",
+  url: "https://developers.cloudflare.com/workers/configuration/routing/workers-dev/",
+};
+export const CF_SECRETS: Authority = {
+  name: "Cloudflare Workers — Secrets",
+  url: "https://developers.cloudflare.com/workers/configuration/secrets/",
+};
+export const CF_ROUTES: Authority = {
+  name: "Cloudflare Workers — Routes",
+  url: "https://developers.cloudflare.com/workers/configuration/routing/routes/",
+};
+export const CF_ENVIRONMENTS: Authority = {
+  name: "Cloudflare Workers — Wrangler environments",
+  url: "https://developers.cloudflare.com/workers/wrangler/configuration/#environments",
+};
+export const CF_STATIC_ASSETS: Authority = {
+  name: "Cloudflare Workers — Static assets",
+  url: "https://developers.cloudflare.com/workers/static-assets/",
+};
 
 function meta(
   id: string,
@@ -127,6 +158,22 @@ const G = "guidance" as const;
 export const RULE_CATEGORY: Record<string, Category> = {
   COR020: "correctness",
   EXT001: "correctness",
+  SEC001: "security",
+  SEC002: "security",
+  SEC003: "security",
+  SEC004: "security",
+  SEC005: "security",
+  SEC006: "security",
+  SEC007: "security",
+  SEC008: "security",
+  SEC009: "security",
+  SEC010: "security",
+  WRG001: "security",
+  WRG002: "security",
+  WRG003: "best-practice",
+  WRG004: "security",
+  WRG005: "security",
+  WRG006: "security",
 };
 
 /**
@@ -139,6 +186,31 @@ export const RULE_CATEGORY: Record<string, Category> = {
 export const RULE_CATALOG: Record<string, RuleMeta> = {
   COR020: meta("COR020", M, G, "Circular resource dependency", "Break the dependency cycle between resources."),
   EXT001: meta("EXT001", M, G, "Extension constraint violation", "Fix the cross-property constraint flagged by the cfn-lint extension schema."),
+
+  // Secrets & credentials (#443) — lexicon-independent: `secrets.ts` scans the
+  // raw text of every candidate file, so these ids apply regardless of which
+  // (if any) audit lexicons are installed. `fixKind` is `guidance`: removing
+  // a hardcoded credential and rotating it needs a human, never an auto-fix.
+  SEC001: meta("SEC001", M, G, "AWS access key ID found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+  SEC002: meta("SEC002", M, G, "AWS secret access key found", "Remove the key from source, rotate it in IAM, and load it from a secret store or environment variable instead.", [GH_SECRET_SCANNING]),
+  SEC003: meta("SEC003", M, G, "GitHub token found", "Remove the token from source and revoke it at github.com/settings/tokens; use a GitHub Actions secret instead.", [GH_SECRET_SCANNING]),
+  SEC004: meta("SEC004", M, G, "Slack token found", "Remove the token from source and revoke it in the Slack app's OAuth settings.", [GH_SECRET_SCANNING]),
+  SEC005: meta("SEC005", M, G, "Google API key found", "Remove the key from source and regenerate it in the Google Cloud Console credentials page.", [GH_SECRET_SCANNING]),
+  SEC006: meta("SEC006", M, G, "Stripe live secret key found", "Remove the key from source and roll it in the Stripe dashboard immediately — this is a live-mode key.", [GH_SECRET_SCANNING]),
+  SEC007: meta("SEC007", M, G, "Private key block found", "Remove the private key from source, rotate the keypair, and load the key from a secret store instead.", [GH_SECRET_SCANNING]),
+  SEC008: meta("SEC008", M, G, "Bearer/authorization token found", "Remove the token from source; if it's long-lived, revoke and reissue it via the issuing service.", [GH_SECRET_SCANNING]),
+  SEC009: meta("SEC009", M, G, "Credentials embedded in a connection string", "Move the username/password out of the URI into a secret store, and rotate the credential.", [GH_SECRET_SCANNING]),
+  SEC010: meta("SEC010", M, G, "High-entropy string — possible secret", "Confirm whether this is a live credential; if so, remove it from source and rotate it. If it's a false positive, suppress with a `chant-audit-ignore` comment or an allowlist entry.", [GH_SECRET_SCANNING]),
+
+  // Wrangler config audit (#446) — lexicon-independent, same shape as the SEC
+  // family above: `wrangler.ts` scans every `wrangler.toml` it finds
+  // regardless of which (if any) audit lexicons are installed.
+  WRG001: meta("WRG001", M, G, "Production environment exposed on *.workers.dev", "Remove workers_dev (or set it to false) for this environment and rely on its custom domain/route instead of the shared public subdomain.", [CF_WORKERS_DEV]),
+  WRG002: meta("WRG002", M, G, "Credential-shaped key stored in [vars]", "Move the value out of [vars] and into `wrangler secret put <name>` so it isn't committed to source or visible in `wrangler dev`/the dashboard.", [CF_SECRETS]),
+  WRG003: meta("WRG003", R, G, "Observability explicitly disabled", "Set observability.enabled = true (or remove the override) so Workers Logs are recorded for this deployment."),
+  WRG004: meta("WRG004", M, G, "Unscoped wildcard route", "Scope the route pattern to the intended zone (e.g. \"example.com/*\") instead of a bare \"*\" or \"*/*\" that matches every zone on the account.", [CF_ROUTES]),
+  WRG005: meta("WRG005", M, G, "Non-production environment shares a data store with production", "Give the non-production environment its own KV namespace/R2 bucket/D1 database id instead of reusing production's.", [CF_ENVIRONMENTS]),
+  WRG006: meta("WRG006", M, G, "Static assets served from the project root", "Point [site].bucket / [assets].directory at a dedicated public output folder, not the project root, so non-public files (config, source maps, .git) aren't served.", [CF_STATIC_ASSETS]),
 };
 
 /**

package/src/audit/core.test.ts

@@ -187,4 +187,61 @@ describe("auditFiles", () => {
     });
     expect(findings.map((f) => f.checkId)).toEqual(["OK001"]);
   });
+
+  test("parse-to-graph: an injected entities parser lets entity-reading checks fire per file (#1567)", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT001",
+      description: "reads ctx.entities, not ctx.outputs",
+      check: (ctx) =>
+        [...ctx.entities.keys()].map((name) => ({ checkId: "ENT001", severity: "warning" as const, message: `saw ${name}`, entity: name })),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.yaml", content: "one", lexicon: "custom" },
+        { path: "b.yaml", content: "two", lexicon: "custom" },
+      ],
+      {
+        checksProvider: async () => [entityCheck],
+        entitiesProvider: async () => (content) => new Map([[content, { entityType: "T::X" } as never]]),
+      },
+    );
+    expect(findings.map((f) => `${f.file}:${f.entity}`).sort()).toEqual(["a.yaml:one", "b.yaml:two"]);
+  });
+
+  test("parse-to-graph merge: the same entity name in two files keeps both — a duplicate check sees the collision cross-file", async () => {
+    const dupCheck: PostSynthCheck = {
+      id: "DUP001",
+      description: "fires when more than one entity is present",
+      check: (ctx) => (ctx.entities.size > 1 ? [{ checkId: "DUP001", severity: "error" as const, message: "name declared twice" }] : []),
+    };
+    const findings = await auditFiles(
+      [
+        { path: "a.yaml", content: "x", lexicon: "custom" },
+        { path: "b.yaml", content: "y", lexicon: "custom" },
+      ],
+      {
+        checksProvider: async () => [dupCheck],
+        // both files declare the entity name "dev" — the merged pass must keep both
+        entitiesProvider: async () => () => new Map([["dev", { entityType: "T::X" } as never]]),
+      },
+    );
+    const dup = findings.find((f) => f.checkId === "DUP001");
+    expect(dup).toBeDefined();
+    expect(dup!.file).toBe(CROSS_FILE);
+  });
+
+  test("an entities parser that throws contributes no entities and does not abort the audit", async () => {
+    const entityCheck: PostSynthCheck = {
+      id: "ENT002",
+      description: "counts entities",
+      check: (ctx) => (ctx.entities.size > 0 ? [{ checkId: "ENT002", severity: "warning" as const, message: "saw entities" }] : []),
+    };
+    const findings = await auditFiles([{ path: "a.yaml", content: "x", lexicon: "custom" }], {
+      checksProvider: async () => [entityCheck],
+      entitiesProvider: async () => () => {
+        throw new Error("unparseable");
+      },
+    });
+    expect(findings).toEqual([]);
+  });
 });

package/src/audit/detect-bundle.test.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "url";
  * service content-detect all lexicons on Workers.
  */
 const repoRoot = fileURLToPath(new URL("../../../../", import.meta.url));
-const LEXICONS = ["k8s", "docker", "aws", "azure", "gcp", "helm"];
+const LEXICONS = ["k8s", "docker", "aws", "azure", "gcp", "helm", "fountain"];
 
 describe("detectTemplate modules are edge-bundle clean", () => {
   test("importing every lexicon's /detect pulls in no typescript or plugin.ts", async () => {

package/src/audit/discover.test.ts

@@ -42,6 +42,29 @@ describe("discoverByDetection (unified, detectTemplate-driven)", () => {
     expect(found.some((i) => i.lexicon === "k8s")).toBe(false);
   });
 
+  test("fountain wins over k8s in a mixed repo — each manifest classifies to its own lexicon (#1566)", async () => {
+    const plugins = await loadAuditPlugins();
+    const found = discoverByDetection(fixture("audit-fountain"), plugins);
+    expect(targets(found)).toEqual(["fountain:agents/fleet.yaml", "k8s:k8s/deploy.yaml"]);
+  });
+
+  test("a multi-document fountain file classifies as one fountain input (no document dropped)", async () => {
+    const plugins = await loadAuditPlugins();
+    const found = discoverByDetection(fixture("audit-fountain"), plugins);
+    const fountain = found.find((i) => i.lexicon === "fountain")!;
+    // All three documents ride along in the input's content.
+    expect(fountain.content.match(/apiVersion: fountain\.dev\/v1/g)).toHaveLength(3);
+  });
+
+  test("without the fountain plugin, fountain YAML falls to k8s (not-installed convention)", () => {
+    const files = [{ path: "fleet.yaml", content: "apiVersion: fountain.dev/v1\nkind: Environment\nmetadata:\n  name: dev\n" }];
+    const k8s = { name: "k8s", detectTemplate: (d: unknown) => !!d && typeof d === "object" && "apiVersion" in (d as object) && "kind" in (d as object) };
+    expect(classifyFiles(files, [k8s]).map((i) => i.lexicon)).toEqual(["k8s"]);
+    // with a fountain plugin present, fountain claims it first
+    const fountain = { name: "fountain", detectTemplate: (d: unknown) => (d as { apiVersion?: unknown })?.apiVersion === "fountain.dev/v1" };
+    expect(classifyFiles(files, [k8s, fountain]).map((i) => i.lexicon)).toEqual(["fountain"]);
+  });
+
   test("detects a Helm chart as a bundle, not loose manifests", async () => {
     const plugins = await loadAuditPlugins();
     const found = discoverByDetection(fixture("audit-helm"), plugins);
@@ -80,6 +103,7 @@ describe("lexicon hints for unclaimed files (#1623)", () => {
     expect(hintLexiconForFile("charts/x/Chart.yaml", "name: x\n")).toBe("helm");
     expect(hintLexiconForFile("infra/main.tf", "resource {}\n")).toBe("terraform");
     expect(hintLexiconForFile("k8s/deploy.yaml", "apiVersion: apps/v1\nkind: Deployment\n")).toBe("k8s");
+    expect(hintLexiconForFile("agents/fleet.yaml", "apiVersion: fountain.dev/v1\nkind: Environment\n")).toBe("fountain");
     expect(hintLexiconForFile("gcp/bucket.yaml", "apiVersion: storage.cnrm.cloud.google.com/v1beta1\nkind: StorageBucket\n")).toBe("gcp");
     expect(hintLexiconForFile("cfn/stack.yaml", "AWSTemplateFormatVersion: '2010-09-09'\nResources: {}\n")).toBe("aws");
     expect(hintLexiconForFile("cfn/stack.json", '{"Resources":{"B":{"Type":"AWS::S3::Bucket"}}}')).toBe("aws");

package/src/audit/discover.ts

@@ -22,7 +22,8 @@
  *   - Helm charts are a directory BUNDLE keyed by `Chart.yaml`; the helm checks
  *     read `output.files`, so the whole chart is one AuditInput.
  *   - k8s `detectTemplate` matches any `apiVersion`+`kind`, including GCP Config
- *     Connector (`cnrm.cloud.google.com`) resources, so gcp must be tried first.
+ *     Connector (`cnrm.cloud.google.com`) resources and fountain
+ *     (`fountain.dev/v1`) manifests, so gcp and fountain must be tried first.
  *   - aws/azure checks `JSON.parse` their input, so YAML/templated content is
  *     normalized to a JSON string here.
  */
@@ -34,7 +35,7 @@ import type { LexiconPlugin } from "../lexicon";
 import type { AuditInput, AuditLexicon } from "./core";
 
 /** Lexicons the auditor knows how to detect and run checks for. */
-export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm"] as const;
+export const AUDIT_LEXICONS = ["github", "gitlab", "forgejo", "k8s", "docker", "aws", "azure", "gcp", "helm", "fountain"] as const;
 
 /**
  * Load the plugins used for detection. Each is loaded in isolation (no
@@ -103,6 +104,27 @@ function isDockerfileName(name: string): boolean {
   return name === "Dockerfile" || name.startsWith("Dockerfile.") || name.endsWith(".Dockerfile") || name.endsWith(".dockerfile");
 }
 
+/**
+ * Filenames the secrets scan (#443) wants that no lexicon otherwise reads —
+ * dotenv files and key/cert material. Included in `isCandidatePath` so both
+ * the local walk and the remote fetch pick them up; `classifyFiles` doesn't
+ * claim them for any lexicon, they just ride along for `scanForSecrets`.
+ */
+function isSecretBearingName(name: string): boolean {
+  if (/^\.env(\..+)?$/i.test(name)) return true;
+  return /\.(pem|key|crt|cer|pfx|p12)$/i.test(name);
+}
+
+/**
+ * `wrangler.toml` (#446) — Cloudflare Workers' declarative deploy config.
+ * Native TOML, so it rides along the same way secret-bearing filenames do:
+ * `wrangler.ts` reads it directly (no lexicon plugin, no authoring surface),
+ * so it only needs to be a candidate path, not a `detectTemplate` entry.
+ */
+function isWranglerConfigName(name: string): boolean {
+  return name === "wrangler.toml";
+}
+
 /** Split a possibly multi-document YAML string into per-doc parsed objects. */
 function parseDocs(content: string): Record<string, unknown>[] {
   const docs: Record<string, unknown>[] = [];
@@ -170,6 +192,13 @@ const CONTENT_DETECTORS: ContentDetector[] = [
     accepts: isYaml,
     detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
   },
+  {
+    // fountain (`apiVersion: fountain.dev/v1`) — must win over k8s, whose
+    // detectTemplate matches any apiVersion+kind document (#1566).
+    lexicon: "fountain",
+    accepts: isYaml,
+    detect: (plugin, _name, content) => (anyDoc(plugin, content) ? content : null),
+  },
   {
     lexicon: "k8s",
     accepts: isYaml,
@@ -223,8 +252,12 @@ export interface DetectPlugin {
   detectTemplate?: (data: unknown) => boolean;
 }
 
-/** Which CI lexicon a path belongs to (by location — content can't disambiguate github vs forgejo). */
-function ciLexiconForPath(path: string): AuditLexicon | undefined {
+/**
+ * Which CI lexicon a path belongs to (by location — content can't disambiguate
+ * github vs forgejo). Exported for the fetch module: known-path lexicons stay a
+ * direct path match even in search-first (large-repo) discovery (#520).
+ */
+export function ciLexiconForPath(path: string): AuditLexicon | undefined {
   if (/^\.github\/workflows\/[^/]+\.ya?ml$/.test(path)) return "github";
   if (/^\.forgejo\/workflows\/[^/]+\.ya?ml$/.test(path)) return "forgejo";
   if (path === ".gitlab-ci.yml") return "gitlab";
@@ -240,6 +273,8 @@ export function isCandidatePath(path: string): boolean {
   if (ciLexiconForPath(path)) return true;
   if (isDockerfileName(name)) return true;
   if (name === "Chart.yaml") return true;
+  if (isSecretBearingName(name)) return true;
+  if (isWranglerConfigName(name)) return true;
   return /\.(ya?ml|json|template)$/i.test(name);
 }
 
@@ -263,6 +298,7 @@ export function hintLexiconForFile(path: string, content: string): LexiconHint |
   if (/\.tf$/i.test(name)) return "terraform";
   const head = content.slice(0, 64 * 1024);
   if (/cnrm\.cloud\.google\.com/.test(head)) return "gcp";
+  if (/fountain\.dev\/v1/.test(head)) return "fountain";
   if (/AWSTemplateFormatVersion|["']?Type["']?\s*:\s*["']AWS::/.test(head)) return "aws";
   if (/deploymentTemplate\.json/.test(head)) return "azure";
   if (isYaml(name)) {

package/src/audit/fetch.test.ts

@@ -54,15 +54,28 @@ function gitTreeMock(files: Record<string, string>, sizes: Record<string, number
   return { impl, calls };
 }
 
+/** A full root-level tree page (>=100 entries) — the "large repo" signal `listTreeGitLab` probes for. */
+const LARGE_ROOT_PAGE = Array.from({ length: 100 }, (_, i) => ({ path: `dir${i}`, type: "tree" }));
+/** A small root-level tree page (<100 entries) — the "small repo" signal, keeps the walk. */
+const SMALL_ROOT_PAGE: Array<{ path: string; type: string }> = [];
+
 /**
  * GitLab mock for authenticated search-based discovery. `searchMap` maps search
  * term → array of blob paths the search API returns. `files` maps path → content.
- * Pass `token` to fetchRepoFiles when using this mock so the code takes the
- * search path (unauthenticated calls fall back to BFS).
+ * The root tree probe reports a large repo by default (`rootPage`
+ * overridable) so these mocks exercise the search path; pass `token` to
+ * `fetchRepoFiles` too, since search additionally requires authentication.
  */
-function gitlabMock(searchMap: Record<string, string[]>, files: Record<string, string>) {
+function gitlabMock(searchMap: Record<string, string[]>, files: Record<string, string>, rootPage: Array<{ path: string; type: string }> = LARGE_ROOT_PAGE) {
   const impl = (async (url: string | URL | Request) => {
     const u = String(url);
+    if (u.includes("/repository/tree")) {
+      const params = new URL(u).searchParams;
+      const path = params.get("path") ?? "";
+      const page = Number(params.get("page") ?? "1");
+      const entries = path === "" && page === 1 ? rootPage : [];
+      return new Response(JSON.stringify(entries), { status: 200 });
+    }
     if (u.includes("/search")) {
       const params = new URL(u).searchParams;
       const term = params.get("search") ?? "";
@@ -112,6 +125,85 @@ function gitlabBfsMock(
   return { impl };
 }
 
+/**
+ * A GitHub-shaped mock for large-repo (search-first) discovery: `fillerCount`
+ * inflates the recursive tree past `LARGE_REPO_TREE_ENTRIES` so `listTree`
+ * switches strategies; `searchMap` maps a bare search term (no `repo:` qualifier)
+ * to the paths GitHub's code search returns for it, paginated 100/page.
+ */
+function githubCodeSearchMock(fillerCount: number, files: Record<string, string>, searchMap: Record<string, string[]>) {
+  const calls: Array<{ url: string }> = [];
+  const impl = (async (url: string | URL | Request) => {
+    const u = String(url);
+    calls.push({ url: u });
+    if (u.includes("/git/trees/")) {
+      const filler = Array.from({ length: fillerCount }, (_, i) => ({ path: `filler/file${i}.md`, type: "blob", size: 10 }));
+      const real = Object.keys(files).map((path) => ({ path, type: "blob", size: files[path].length }));
+      return new Response(JSON.stringify({ tree: [...filler, ...real] }), { status: 200 });
+    }
+    if (u.includes("/search/code")) {
+      const params = new URL(u).searchParams;
+      const term = (params.get("q") ?? "").replace(/\s*repo:.*/, "");
+      const page = Number(params.get("page") ?? "1");
+      const all = searchMap[term] ?? [];
+      const start = (page - 1) * 100;
+      const items = all.slice(start, start + 100).map((path) => ({ path }));
+      return new Response(JSON.stringify({ items, total_count: all.length }), { status: 200 });
+    }
+    const rawm = u.match(/raw\.githubusercontent\.com\/[^/]+\/[^/]+\/[^/]+\/(.+)$/);
+    if (rawm) {
+      const path = decodeURIComponent(rawm[1]);
+      if (files[path] === undefined) return new Response("not found", { status: 404 });
+      return new Response(files[path], { status: 200 });
+    }
+    const cm = u.match(/\/contents\/(.+?)\?/);
+    if (cm) {
+      const path = decodeURIComponent(cm[1]);
+      if (files[path] === undefined) return new Response("not found", { status: 404 });
+      return new Response(JSON.stringify({ path, type: "file", content: b64(files[path]), encoding: "base64" }), { status: 200 });
+    }
+    if (/\/repos\/[^/]+\/[^/]+(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
+/**
+ * A Forgejo/Gitea-shaped mock for large-repo discovery. `searchMap` maps a bare
+ * search term to the paths its (best-effort, `{ok, data}`-enveloped) search
+ * endpoint returns, paginated 100/page.
+ */
+function forgejoCodeSearchMock(fillerCount: number, files: Record<string, string>, searchMap: Record<string, string[]>) {
+  const calls: Array<{ url: string }> = [];
+  const impl = (async (url: string | URL | Request) => {
+    const u = String(url);
+    calls.push({ url: u });
+    if (u.includes("/git/trees/")) {
+      const filler = Array.from({ length: fillerCount }, (_, i) => ({ path: `filler/file${i}.md`, type: "blob", size: 10 }));
+      const real = Object.keys(files).map((path) => ({ path, type: "blob", size: files[path].length }));
+      return new Response(JSON.stringify({ tree: [...filler, ...real] }), { status: 200 });
+    }
+    if (u.includes("/search")) {
+      const params = new URL(u).searchParams;
+      const term = params.get("q") ?? "";
+      const page = Number(params.get("page") ?? "1");
+      const all = searchMap[term] ?? [];
+      const start = (page - 1) * 100;
+      const data = all.slice(start, start + 100).map((path) => ({ path }));
+      return new Response(JSON.stringify({ ok: true, data }), { status: 200 });
+    }
+    const cm = u.match(/\/contents\/(.+?)\?/);
+    if (cm) {
+      const path = decodeURIComponent(cm[1]);
+      if (files[path] === undefined) return new Response("not found", { status: 404 });
+      return new Response(JSON.stringify({ path, type: "file", content: b64(files[path]), encoding: "base64" }), { status: 200 });
+    }
+    if (/\/repos\/[^/]+\/[^/]+(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+  return { impl, calls };
+}
+
 describe("parseRepoUrl", () => {
   test("rejects non-https", () => {
     expect(() => parseRepoUrl("http://github.com/o/r")).toThrow(FetchError);
@@ -285,12 +377,133 @@ describe("fetchRepoFiles", () => {
     expect(files.map((f) => f.path)).toContain(".gitlab-ci.yml");
   });
 
+  // ── Strategy selection: small repo → walk, large repo → search (#520) ────
+
+  test("gitlab: a small repo uses the walk even when a token is present (no search call)", async () => {
+    // The root page has one blob and no filler dirs — well under the large-repo
+    // threshold — so the walk is used regardless of the token, and the search
+    // API is never called.
+    const rootPage = [{ path: ".gitlab-ci.yml", type: "blob" }];
+    const { impl } = gitlabMock({ "stages:": [".gitlab-ci.yml"] }, { ".gitlab-ci.yml": "stages:\n  - build\n" }, rootPage);
+    const calls: string[] = [];
+    const spy = (async (url: string | URL | Request, init?: RequestInit) => {
+      calls.push(String(url));
+      return impl(url, init);
+    }) as unknown as typeof fetch;
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: spy, token: "tok" });
+    expect(files.map((f) => f.path)).toEqual([".gitlab-ci.yml"]);
+    expect(calls.some((c) => c.includes("/search"))).toBe(false);
+  });
+
+  test("gitlab: a large repo without a token falls back to the BFS walk (search needs auth)", async () => {
+    const dirEntries = {
+      "": [{ path: ".gitlab-ci.yml", type: "blob" as const }, ...Array.from({ length: 99 }, (_, i) => ({ path: `dir${i}`, type: "tree" as const }))],
+    };
+    const { impl } = gitlabBfsMock(dirEntries, { ".gitlab-ci.yml": "stages:\n  - build\n" });
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl }); // no token
+    expect(files.map((f) => f.path)).toContain(".gitlab-ci.yml");
+  });
+
+  test("gitlab: search failure on a large repo falls back to the BFS walk (#520)", async () => {
+    const dirEntries = {
+      "": [{ path: ".gitlab-ci.yml", type: "blob" as const }, ...Array.from({ length: 99 }, (_, i) => ({ path: `dir${i}`, type: "tree" as const }))],
+    };
+    const { impl: bfsImpl } = gitlabBfsMock(dirEntries, { ".gitlab-ci.yml": "stages:\n  - build\n" });
+    const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+      if (String(url).includes("/search")) return new Response("rate limited", { status: 429 });
+      return bfsImpl(url, init);
+    }) as unknown as typeof fetch;
+    const files = await fetchRepoFiles("https://gitlab.com/acme/widgets", { fetchImpl: impl, token: "tok" });
+    expect(files.map((f) => f.path)).toContain(".gitlab-ci.yml");
+  });
+
+  test("github: a small repo never calls the code search API", async () => {
+    const { impl, calls } = gitTreeMock({ ".github/workflows/ci.yml": CI_YAML, "k8s/deploy.yaml": "apiVersion: apps/v1\nkind: Deployment\n" });
+    await fetchRepoFiles("https://github.com/acme/widgets", { fetchImpl: impl });
+    expect(calls.some((c) => c.url.includes("/search/code"))).toBe(false);
+  });
+
+  test("github: a large repo switches to per-lexicon search; known-path CI bypasses search entirely", async () => {
+    const files = { ".github/workflows/ci.yml": CI_YAML, "infra/eks.yaml": "apiVersion: v1\nkind: ConfigMap\n" };
+    const { impl, calls } = githubCodeSearchMock(600, files, { apiVersion: ["infra/eks.yaml"] });
+    const found = await fetchRepoFiles("https://github.com/acme/monorepo", { fetchImpl: impl, maxFiles: 100 });
+    const paths = found.map((f) => f.path);
+    expect(paths).toContain(".github/workflows/ci.yml");
+    expect(paths).toContain("infra/eks.yaml");
+    // The workflow came straight from the tree already in hand — no search
+    // query was needed (or issued) to find it.
+    expect(calls.some((c) => c.url.includes("/search/code") && c.url.includes("workflows"))).toBe(false);
+  });
+
+  test("github: search results paginate past 100 until a short page", async () => {
+    const manyPaths = Array.from({ length: 150 }, (_, i) => `k8s/deploy${i}.yaml`);
+    const files: Record<string, string> = {};
+    for (const p of manyPaths) files[p] = "apiVersion: apps/v1\nkind: Deployment\n";
+    const { impl, calls } = githubCodeSearchMock(600, files, { apiVersion: manyPaths });
+    const found = await fetchRepoFiles("https://github.com/acme/monorepo", { fetchImpl: impl, maxFiles: 1000 });
+    expect(found.length).toBe(150);
+    const searchCalls = calls.filter((c) => c.url.includes("/search/code") && c.url.includes("q=apiVersion"));
+    expect(searchCalls.some((c) => c.url.includes("page=1"))).toBe(true);
+    expect(searchCalls.some((c) => c.url.includes("page=2"))).toBe(true);
+  });
+
+  test("github: search failure (rate limit) on a large repo falls back to the full tree", async () => {
+    const files = { ".github/workflows/ci.yml": CI_YAML, "infra/eks.yaml": "apiVersion: v1\nkind: ConfigMap\n" };
+    const { impl: base } = githubCodeSearchMock(600, files, {});
+    const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+      if (String(url).includes("/search/code")) return new Response("rate limited", { status: 403 });
+      return base(url, init);
+    }) as unknown as typeof fetch;
+    const found = await fetchRepoFiles("https://github.com/acme/monorepo", { fetchImpl: impl, maxFiles: 1000 });
+    const paths = found.map((f) => f.path);
+    expect(paths).toContain(".github/workflows/ci.yml");
+    expect(paths).toContain("infra/eks.yaml");
+  });
+
   test("forgejo (codeberg): gitea tree + contents", async () => {
     const { impl } = gitTreeMock({ ".forgejo/workflows/ci.yml": CI_YAML });
     const files = await fetchRepoFiles("https://codeberg.org/acme/widgets", { fetchImpl: impl });
     expect(files.map((f) => f.path)).toEqual([".forgejo/workflows/ci.yml"]);
   });
 
+  test("forgejo: a large repo switches to search; known-path CI bypasses search entirely", async () => {
+    const files = { ".forgejo/workflows/ci.yml": CI_YAML, "charts/app/Chart.yaml": "apiVersion: v2\nname: app\nversion: 1.0.0\n" };
+    const { impl, calls } = forgejoCodeSearchMock(600, files, { "apiVersion: v2": ["charts/app/Chart.yaml"] });
+    const found = await fetchRepoFiles("https://codeberg.org/acme/monorepo", { fetchImpl: impl, maxFiles: 100 });
+    const paths = found.map((f) => f.path);
+    expect(paths).toContain(".forgejo/workflows/ci.yml");
+    expect(paths).toContain("charts/app/Chart.yaml");
+    expect(calls.some((c) => c.url.includes("/search") && c.url.includes("workflows"))).toBe(false);
+  });
+
+  test("forgejo: search paginates past 100 until a short page", async () => {
+    const manyPaths = Array.from({ length: 120 }, (_, i) => `k8s/deploy${i}.yaml`);
+    const files: Record<string, string> = {};
+    for (const p of manyPaths) files[p] = "apiVersion: apps/v1\nkind: Deployment\n";
+    const { impl, calls } = forgejoCodeSearchMock(600, files, { apiVersion: manyPaths });
+    const found = await fetchRepoFiles("https://codeberg.org/acme/monorepo", { fetchImpl: impl, maxFiles: 1000 });
+    expect(found.length).toBe(120);
+    const searchCalls = calls.filter((c) => c.url.includes("/search") && c.url.includes("q=apiVersion"));
+    expect(searchCalls.some((c) => c.url.includes("page=1"))).toBe(true);
+    expect(searchCalls.some((c) => c.url.includes("page=2"))).toBe(true);
+  });
+
+  test("forgejo: an instance with no code search (404) falls back to the full tree", async () => {
+    // Forgejo's code-search availability/shape is undocumented (#520) — an
+    // instance without a code indexer, or with a different API shape, must
+    // still produce a full audit via the fallback, not an empty/failed one.
+    const files = { ".forgejo/workflows/ci.yml": CI_YAML, "charts/app/Chart.yaml": "apiVersion: v2\nname: app\nversion: 1.0.0\n" };
+    const { impl: base } = forgejoCodeSearchMock(600, files, {});
+    const impl = (async (url: string | URL | Request, init?: RequestInit) => {
+      if (String(url).includes("/search")) return new Response("not found", { status: 404 });
+      return base(url, init);
+    }) as unknown as typeof fetch;
+    const found = await fetchRepoFiles("https://codeberg.org/acme/monorepo", { fetchImpl: impl, maxFiles: 1000 });
+    const paths = found.map((f) => f.path);
+    expect(paths).toContain(".forgejo/workflows/ci.yml");
+    expect(paths).toContain("charts/app/Chart.yaml");
+  });
+
   test("an empty repo returns []", async () => {
     const { impl } = gitTreeMock({});
     const files = await fetchRepoFiles("https://github.com/acme/empty", { fetchImpl: impl });