Wire regex support into CLI + docs, homepage and comparison table

shouze · shouze · commit 2f4ba11fa682 · 2026-03-13T11:11:36.000+01:00
- Parse /pattern/flags in query subcommand via isRegexQuery() / buildApiQuery() - Pass regexFilter to aggregate(); display UX warning when query is broadened - Add --regex-hint <term> escape hatch for edge cases - docs/usage/search-syntax.md: new Regex queries section with 4 examples - docs/reference/cli-options.md: document --regex-hint flag - docs/architecture/components.md: add src/regex.ts to C4 Level 3a diagram - docs/.vitepress/theme/ComparisonTable.vue: add Regex queries row (web UI only note) - docs/.vitepress/theme/UseCaseTabs.vue: add Semver / version audit use case - AGENTS.md: add src/regex.ts entry + symptom table row - README.md: add Regex search use case Closes #112
diff --git a/AGENTS.md b/AGENTS.md
@@ -80,6 +80,9 @@ src/
   completions.ts         # Pure shell-completion generators: generateCompletion(),
                          #   detectShell(), getCompletionFilePath() — no I/O
   group.ts               # groupByTeamPrefix — team-prefix grouping logic
+  regex.ts               # Pure query parser: isRegexQuery(), buildApiQuery()
+                         #   Detects /pattern/ syntax, derives safe API term,
+                         #   returns RegExp for local client-side filtering — no I/O
   render.ts              # Façade re-exporting sub-modules + top-level
                          #   renderGroups() / renderHelpOverlay()
   tui.ts                 # Interactive keyboard-driven UI (navigation, filter mode,
diff --git a/README.md b/README.md
@@ -83,6 +83,14 @@ github-code-search query "useFeatureFlag" --org my-org --group-by-team-prefix pl
 
 Get a team-scoped view of every usage site before refactoring a shared hook or utility.
 
+**Regex search — pattern-based code audit**
+
+```bash
+github-code-search query "/from.*['\"\`]axios/" --org my-org
+```
+
+Use `/pattern/` syntax to run a regex search. The CLI automatically derives a safe API query term and filters results locally — no manual post-processing needed. Use `--regex-hint` to override the derived term when auto-extraction is too broad.
+
 ## Why not `gh search code`?
 
 The official [`gh` CLI](https://cli.github.com/) does support `gh search code`, but it returns a **flat paginated list** — one result per line, no grouping, no interactive selection, no structured output.
diff --git a/docs/.vitepress/theme/ComparisonTable.vue b/docs/.vitepress/theme/ComparisonTable.vue
@@ -59,6 +59,13 @@ const ROWS: Row[] = [
     gcs: true,
     docLink: "/usage/interactive-mode",
   },
+  {
+    feature: "Regex queries (/pattern/flags)",
+    desc: "Use full regular expressions in queries — top-level alternation (A|B|C) maps to GitHub OR, client-side filtering applies the real pattern. GitHub supports regex in the web UI only, not in the REST API or gh CLI.",
+    gh: false,
+    gcs: true,
+    docLink: "/usage/search-syntax",
+  },
   {
     feature: "Pagination (up to 1\u202f000 results)",
     desc: "Both tools auto-paginate the GitHub search API \u2014 up to 1\u202f000 results per query.",
diff --git a/docs/.vitepress/theme/UseCaseTabs.vue b/docs/.vitepress/theme/UseCaseTabs.vue
@@ -50,6 +50,14 @@ const USE_CASES: UseCase[] = [
       "Get a team-scoped view of every usage site before refactoring a shared hook or utility. Essential for onboarding or large-scale refactors.",
     command: `github-code-search query "useFeatureFlag" --org my-org --group-by-team-prefix platform/`,
   },
+  {
+    id: "semver",
+    label: "Semver / version audit",
+    headline: "Which repos are pinned to a vulnerable minor version?",
+    description:
+      "Use regex syntax to target a precise version range — something a plain keyword search cannot do. Find every repo still locked to axios 1.x, react 17.x, or any other outdated pin, then export the list to a migration issue.",
+    command: `github-code-search query '/"axios": "1./' --org my-org`,
+  },
 ];
 
 const active = ref(0);
diff --git a/docs/architecture/components.md b/docs/architecture/components.md
@@ -14,17 +14,21 @@ into a filtered, grouped, formatted output.
 C4Component
   title Level 3a: CLI data pipeline
 
-  UpdateLayoutConfig($c4ShapeInRow="4", $c4BoundaryInRow="1")
+  UpdateLayoutConfig($c4ShapeInRow="5", $c4BoundaryInRow="1")
 
   Container(cli, "CLI parser", "github-code-search.ts", "Orchestrates filter,<br/>group, output and<br/>shell completions")
 
   Container_Boundary(core, "Pure-function core — no I/O") {
+    Component(regexParser, "Query parser", "src/regex.ts", "isRegexQuery()<br/>buildApiQuery()")
     Component(aggregate, "Filter & aggregation", "src/aggregate.ts", "aggregate()<br/>exclude repos & extracts")
     Component(group, "Team grouping", "src/group.ts", "groupByTeamPrefix()<br/>flattenTeamSections()")
     Component(outputFn, "Output formatter", "src/output.ts", "buildOutput()<br/>markdown or JSON")
     Component(completions, "Shell completions", "src/completions.ts", "generateCompletion()<br/>detectShell()<br/>getCompletionFilePath()")
   }
 
+  Rel(cli, regexParser, "Parse regex<br/>query")
+  UpdateRelStyle(cli, regexParser, $offsetX="35", $offsetY="-17")
+
   Rel(cli, aggregate, "Filter<br/>CodeMatch[]")
   UpdateRelStyle(cli, aggregate, $offsetX="0", $offsetY="-17")
 
@@ -38,6 +42,7 @@ C4Component
   UpdateRelStyle(cli, completions, $offsetX="-90", $offsetY="-17")
 
   UpdateElementStyle(cli, $bgColor="#FFCC33", $borderColor="#0000CC", $fontColor="#000000")
+  UpdateElementStyle(regexParser, $bgColor="#9933FF", $borderColor="#0000CC", $fontColor="#ffffff")
   UpdateElementStyle(aggregate, $bgColor="#9933FF", $borderColor="#0000CC", $fontColor="#ffffff")
   UpdateElementStyle(group, $bgColor="#9933FF", $borderColor="#0000CC", $fontColor="#ffffff")
   UpdateElementStyle(outputFn, $bgColor="#9933FF", $borderColor="#0000CC", $fontColor="#ffffff")
diff --git a/docs/reference/cli-options.md b/docs/reference/cli-options.md
@@ -31,17 +31,18 @@ github-code-search completions [--shell <shell>]
 
 ## Search options
 
-| Option                              | Type                              | Required | Default            | Description                                                                                                                                                           |
-| ----------------------------------- | --------------------------------- | -------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--org <org>`                       | string                            | ✅       | —                  | GitHub organization to search in. Automatically injected as `org:<org>` in the query.                                                                                 |
-| `--exclude-repositories <repos>`    | string                            | ❌       | `""`               | Comma-separated list of repositories to exclude. Short form (`repoA,repoB`) or full form (`org/repoA,org/repoB`) both accepted.                                       |
-| `--exclude-extracts <refs>`         | string                            | ❌       | `""`               | Comma-separated extract refs to exclude. Format: `repoName:path/to/file:index`. Short form (without org prefix) accepted.                                             |
-| `--no-interactive`                  | boolean (flag)                    | ❌       | `true` (on)        | Disable interactive mode. Interactive mode is **on** by default; pass this flag to disable it. Also triggered by `CI=true`.                                           |
-| `--format <format>`                 | `markdown` \| `json`              | ❌       | `markdown`         | Output format. See [Output formats](/usage/output-formats).                                                                                                           |
-| `--output-type <type>`              | `repo-and-matches` \| `repo-only` | ❌       | `repo-and-matches` | Controls output detail level. `repo-only` lists repository names only, without individual extracts.                                                                   |
-| `--include-archived`                | boolean (flag)                    | ❌       | `false`            | Include archived repositories in results (excluded by default).                                                                                                       |
-| `--group-by-team-prefix <prefixes>` | string                            | ❌       | `""`               | Comma-separated team-name prefixes for grouping result repos by GitHub team (e.g. `squad-,chapter-`). Requires `read:org` scope.                                      |
-| `--no-cache`                        | boolean (flag)                    | ❌       | `true` (on)        | Bypass the 24 h team-list cache and re-fetch teams from GitHub. Cache is **on** by default; pass this flag to disable it. Only applies with `--group-by-team-prefix`. |
+| Option                              | Type                              | Required | Default            | Description                                                                                                                                                                                                      |
+| ----------------------------------- | --------------------------------- | -------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--org <org>`                       | string                            | ✅       | —                  | GitHub organization to search in. Automatically injected as `org:<org>` in the query.                                                                                                                            |
+| `--exclude-repositories <repos>`    | string                            | ❌       | `""`               | Comma-separated list of repositories to exclude. Short form (`repoA,repoB`) or full form (`org/repoA,org/repoB`) both accepted.                                                                                  |
+| `--exclude-extracts <refs>`         | string                            | ❌       | `""`               | Comma-separated extract refs to exclude. Format: `repoName:path/to/file:index`. Short form (without org prefix) accepted.                                                                                        |
+| `--no-interactive`                  | boolean (flag)                    | ❌       | `true` (on)        | Disable interactive mode. Interactive mode is **on** by default; pass this flag to disable it. Also triggered by `CI=true`.                                                                                      |
+| `--format <format>`                 | `markdown` \| `json`              | ❌       | `markdown`         | Output format. See [Output formats](/usage/output-formats).                                                                                                                                                      |
+| `--output-type <type>`              | `repo-and-matches` \| `repo-only` | ❌       | `repo-and-matches` | Controls output detail level. `repo-only` lists repository names only, without individual extracts.                                                                                                              |
+| `--include-archived`                | boolean (flag)                    | ❌       | `false`            | Include archived repositories in results (excluded by default).                                                                                                                                                  |
+| `--group-by-team-prefix <prefixes>` | string                            | ❌       | `""`               | Comma-separated team-name prefixes for grouping result repos by GitHub team (e.g. `squad-,chapter-`). Requires `read:org` scope.                                                                                 |
+| `--no-cache`                        | boolean (flag)                    | ❌       | `true` (on)        | Bypass the 24 h team-list cache and re-fetch teams from GitHub. Cache is **on** by default; pass this flag to disable it. Only applies with `--group-by-team-prefix`.                                            |
+| `--regex-hint <term>`               | string                            | ❌       | —                  | Override the API search term used when the query is a regex (`/pattern/`). Useful when auto-extraction produces a term that is too broad or too narrow. See [Regex queries](/usage/search-syntax#regex-queries). |
 
 ## Global options
 
diff --git a/docs/usage/search-syntax.md b/docs/usage/search-syntax.md
@@ -77,6 +77,54 @@ github-code-search "useFeatureFlag repo:fulll/billing-api repo:fulll/auth-servic
 github-code-search "password= language:TypeScript NOT filename:test" --org fulll
 ```
 
+## Regex queries
+
+`github-code-search` supports regex syntax using the `/pattern/flags` notation, just like the GitHub web UI.
+
+Because the GitHub Code Search API does not natively support regex, the CLI automatically extracts a representative literal term from the regex to send to the API, then filters the returned results locally with the full pattern. In most cases this is fully transparent.
+
+```bash
+# Imports using the axios module (any quote style)
+github-code-search "/from.*['\"\`]axios/" --org fulll
+
+# Axios dependency in package.json (any semver prefix)
+github-code-search '"axios": "[~^]?[0-9]" filename:package.json' --org fulll
+
+# Old library require() calls
+github-code-search "/require\\(['\"](old-lib)['\"]\\)/" --org fulll
+
+# Any of TODO, FIXME or HACK comments
+github-code-search "/TODO|FIXME|HACK/" --org fulll
+```
+
+::: tip Top-level alternation
+When the regex contains a **top-level `|`** (e.g. `TODO|FIXME|HACK`), the CLI sends
+an `A OR B OR C` query to the GitHub API so that **all branches are covered** — no results are missed.
+:::
+
+### When auto-extraction is not precise enough
+
+If the extracted term is very short (fewer than 3 characters), the CLI will exit with a warning and ask you to provide a manual hint:
+
+```
+⚠  Regex mode — could not extract a term longer than 2 chars from /[~^]?[0-9]/
+   Provide a manual hint with --regex-hint <term>.
+```
+
+Use `--regex-hint` to override the API search term while still applying the full regex filter locally:
+
+```bash
+github-code-search '/"axios":\s*"[~^]?[0-9]/ filename:package.json' \
+  --org fulll \
+  --regex-hint '"axios"'
+```
+
+::: warning API coverage
+The GitHub Code Search API returns **at most 1,000 results** per query. The regex filter
+is applied to those results; results beyond the API cap can never be seen. Refine the
+query with qualifiers (`language:`, `path:`, `filename:`) to keep the result set small.
+:::
+
 ## API limits
 
 The GitHub Code Search API returns at most **1,000 results** per query. If your query returns more, refine it with qualifiers (especially `language:` or `path:`) to stay below the limit.
diff --git a/github-code-search.ts b/github-code-search.ts
@@ -24,6 +24,7 @@ import { groupByTeamPrefix, flattenTeamSections } from "./src/group.ts";
 import { checkForUpdate } from "./src/upgrade.ts";
 import { runInteractive } from "./src/tui.ts";
 import { generateCompletion, detectShell } from "./src/completions.ts";
+import { buildApiQuery, isRegexQuery } from "./src/regex.ts";
 import type { OutputFormat, OutputType } from "./src/types.ts";
 
 // Version + build metadata injected at compile time via --define (see build.ts).
@@ -179,6 +180,15 @@ function addSearchOptions(cmd: Command): Command {
     .option(
       "--no-cache",
       "Bypass the 24 h team-list cache and re-fetch teams from GitHub (only applies with --group-by-team-prefix).",
+    )
+    .option(
+      "--regex-hint <term>",
+      [
+        "Override the search term sent to the GitHub API when using a regex query.",
+        "Useful when auto-extraction produces a term that is too broad or too narrow.",
+        'Example: --regex-hint "axios"  (for query /from.*[\'"]axios/)',
+        "Docs: https://fulll.github.io/github-code-search/usage/search-syntax#regex-queries",
+      ].join("\n"),
     );
 }
 
@@ -195,6 +205,7 @@ async function searchAction(
     includeArchived: boolean;
     groupByTeamPrefix: string;
     cache: boolean;
+    regexHint?: string;
   },
 ): Promise<void> {
   // ─── GitHub API token ───────────────────────────────────────────────────────
@@ -264,8 +275,32 @@ async function searchAction(
     return activeCooldown;
   };
 
-  const rawMatches = await fetchAllResults(query, org, GITHUB_TOKEN!, onRateLimit);
-  let groups = aggregate(rawMatches, excludedRepos, excludedExtractRefs, includeArchived);
+  // ─── Regex query detection ───────────────────────────────────────────────
+  let effectiveQuery = query;
+  let regexFilter: RegExp | undefined;
+  if (isRegexQuery(query)) {
+    const { apiQuery, regexFilter: rf, warn } = buildApiQuery(query);
+    if (warn && !opts.regexHint) {
+      console.error(
+        pc.yellow(`⚠  Regex mode — ${warn}\n   Provide a manual hint with --regex-hint <term>.`),
+      );
+      process.exit(1);
+    }
+    effectiveQuery = opts.regexHint ?? apiQuery;
+    regexFilter = rf ?? undefined;
+    process.stderr.write(
+      pc.dim(`  ℹ  Regex mode — GitHub query: "${effectiveQuery}", local filter: ${query}\n`),
+    );
+  }
+
+  const rawMatches = await fetchAllResults(effectiveQuery, org, GITHUB_TOKEN!, onRateLimit);
+  let groups = aggregate(
+    rawMatches,
+    excludedRepos,
+    excludedExtractRefs,
+    includeArchived,
+    regexFilter,
+  );
 
   // ─── Team-prefix grouping ─────────────────────────────────────────────────
   if (opts.groupByTeamPrefix) {
