@intentius/chant 0.49.0 → 0.51.0

package/dist/toml.d.ts

@@ -1,9 +1,44 @@
 /**
- * TOML emitter and parser — re-exports from split modules.
+ * Lightweight TOML parser (#446).
  *
- * Import from here for the public API:
- *   import { emitTOML, parseTOML } from "@intentius/chant/toml";
+ * Written for the audit engine's spike: is there a pure, dependency-free way
+ * to parse a config format the engine can't read today? TOML fits — it is a
+ * fully-specified, static (no macros/interpolation/imports) grammar, so a
+ * hand-rolled tokenizer + recursive-descent parser covers it without any
+ * runtime surface a Workers sandbox would reject (no `eval`, no native
+ * modules, no filesystem/network).
+ *
+ * Covers the subset of TOML v1.0 that real-world deploy configs
+ * (`wrangler.toml`, `Cargo.toml`, `pyproject.toml`, `netlify.toml`) actually
+ * use: basic/literal strings (single-line), integers, floats, booleans,
+ * arrays (including multi-line), inline tables, dotted keys, standard tables
+ * (`[a.b]`), and arrays of tables (`[[a.b]]`).
+ *
+ * Deliberately NOT a full spec implementation:
+ *  - Multi-line strings (`"""..."""`, `'''...'''`) are read as a single
+ *    opaque string body (no line-ending backslash trimming); good enough to
+ *    not crash, not spec-perfect for continuation whitespace.
+ *  - Dates/times are returned as their raw source text (a string), not a
+ *    `Date` — none of the checks built on this parser need calendar math.
+ *  - A dotted-key path element must be a bare word or a plain quoted string;
+ *    mixing exotic key shapes mid-path is not supported.
+ * These gaps only matter for exotic TOML; they don't affect the shapes the
+ * audit checks read (`[vars]`, `[[kv_namespaces]]`, `[env.NAME]`, …).
+ */
+export declare class TomlParseError extends Error {
+}
+type TomlValue = string | number | boolean | TomlValue[] | {
+    [k: string]: TomlValue;
+};
+type TomlTable = {
+    [k: string]: TomlValue;
+};
+/**
+ * Parse a TOML document into a plain nested object. Throws {@link TomlParseError}
+ * on malformed input — callers that scan arbitrary repo files should wrap the
+ * call in a try/catch (matching the rest of the audit engine's tolerance for
+ * unparseable content).
  */
-export { emitTOML, type EmitTOMLOptions } from "./toml-emit.js";
-export { parseTOML } from "./toml-parse.js";
+export declare function parseTOML(input: string): TomlTable;
+export {};
 //# sourceMappingURL=toml.d.ts.map

package/dist/toml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"toml.d.ts","sourceRoot":"","sources":["../src/toml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,qBAAa,cAAe,SAAQ,KAAK;CAAG;AAqK5C,KAAK,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AACtF,KAAK,SAAS,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAgJ5C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CA8BlD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/audit/catalog.test.ts

@@ -91,7 +91,7 @@ describe("RULE_CATALOG (aggregated: core static + lexicon-contributed, #687)", (
       expect(m.remediation.length, `${id} has remediation`).toBeGreaterThan(0);
       expect(["merge-worthy", "report-only"]).toContain(m.tier);
       expect(["deterministic", "guidance"]).toContain(m.fixKind);
-      expect(["security", "correctness", "best-practice"], `${id} has a valid category`).toContain(m.category);
+      expect(["security", "correctness", "best-practice", "efficiency"], `${id} has a valid category`).toContain(m.category);
     }
   });
 

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.ts

@@ -73,6 +73,15 @@ export interface AuditFinding {
   lexicon: string;
   /** Optional entity (e.g. job name) the check attached. */
   entity?: string;
+  /** 1-based line number within `file`, when the check can pin one (e.g. secrets detection, #443). */
+  line?: number;
+  /**
+   * A redaction-safe fingerprint of the flagged value (see
+   * `secrets.ts`'s `fingerprintSecret`), so a finding can be referenced —
+   * for an allowlist entry, for dedup — without ever carrying the value
+   * itself.
+   */
+  fingerprint?: string;
 }
 
 /**

package/src/audit/discover.ts

@@ -104,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>[] = [];
@@ -231,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";
@@ -248,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);
 }
 

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 });