feat: wire regex support into CLI — UX messaging, --regex-hint option, docs, C4 diagrams

[shouze]

Context

Part of #110 (EPIC: Support regex syntax /pattern/ in search queries) — step 2 of 2.

Depends on #111 (Core src/regex.ts module + aggregate() regex filter) being merged first.

This issue wires the core module into the CLI, adds user-facing messaging, an escape hatch for edge cases, updates the documentation, and keeps the architecture diagrams and AGENTS.md in sync.

Scope

github-code-search.ts — searchAction()

1. Detect regex — call isRegexQuery(query) before fetchAllResults
2. Derive API query — call buildApiQuery(query) to get { apiQuery, regexFilter, warn }
3. Warn on stderr when warn is set (no exploitable literal found):

   ⚠ Regex mode — could not extract a search term from the pattern.
     Use --regex-hint <term> to specify the term to send to the GitHub API.
   

   In this case, exit with a helpful error (do not send an empty query to the API).
4. Inform on stderr in normal regex mode (before the progress bar):

   ℹ Regex mode — searching GitHub for "axios", filtering locally with /from.*['"]axios/
   

5. Add --regex-hint <term> option — overrides the apiQuery term derived by buildApiQuery():

   --regex-hint <term>   Override the search term sent to the GitHub API when using a
                         regex query. Useful when auto-extraction is too broad or too narrow.
                         Example: --regex-hint "axios"
   

6. Pass regexFilter to aggregate() (new param from feat: add src/regex.ts core module + aggregate() regex filter #111)

Behaviour summary

Query	--regex-hint	API query sent	Local filter
/from.*['"]axios/	—	axios org:fulll	/from.*['"]axios/
/from.*['"]axios/	"from axios"	from axios org:fulll	/from.*['"]axios/
/TODO|FIXME|HACK/	—	TODO OR FIXME OR HACK org:fulll	/TODO|FIXME|HACK/
filename:package.json /["']axios["']:/	—	filename:package.json axios org:fulll	✓
/[~^]?[0-9]+\.[0-9]+/	"axios"	axios org:fulll	/[~^]?[0-9]+\.[0-9]+/
/[~^]?[0-9]+\.[0-9]+/	—	❌ error + exit	—
plain text query	—	plain text query org:fulll (unchanged)	none

docs/usage/search-syntax.md

Add a new "Regex queries" section:

• Lead with the limitation clearly first: "The GitHub REST API does not support regex syntax natively. github-code-search works around this by extracting a literal term from your pattern to query the API, then filtering the results locally."
• Document --regex-hint with its use case (semver patterns where auto-extraction fails)
• Four real-world CLI examples with expected behaviour:
  • /from.*['"]axios/ — import pattern matching
  • /TODO|FIXME|HACK/ — TODO triage (alternation → OR)
  • /require\(['"]old-lib['"]\)/ — deprecated library
  • filename:package.json /"axios":\s*"[~^]?[0-9]/ + --regex-hint axios — semver audit
• VitePress admonition:

  ::: warning GitHub API cap
  Regex filtering applies to the first 1 000 results returned by the GitHub API.
  For broad patterns, combine with qualifiers like `filename:` or `language:` to reduce noise.
  See [GitHub API limits](/reference/github-api-limits).
  :::
  

README.md

Add a "Regex search" entry in the "Use cases" section with one example and a link to the docs.

docs/architecture/components.md — C4 Level 3a

Add src/regex.ts as a new component in the "CLI data pipeline" diagram (diagram 3a).

• New Component node: "Query parser" — src/regex.ts — isRegexQuery()\nbuildApiQuery()
• New arrow from cli to the regex component: "Parse regex\nquery"
• Follow the existing style conventions (violet #9933FF background, white text)

Update the Container descriptions table in containers.md if needed (the CLI parser description covers its orchestration role — add a note about regex query detection if the description no longer matches).

AGENTS.md

Add src/regex.ts to the Project layout table and the module map:

src/
  regex.ts               # Pure query parser: isRegexQuery(), buildApiQuery()
                         #   Detects /pattern/ syntax and derives a safe GitHub API
                         #   query term + a local RegExp filter
  regex.test.ts          # Unit tests for regex.ts

Also add a row to the Symptom → module table in the bug-fixing instruction file:

Symptom	Look in
Regex query returns wrong or no results	src/regex.ts, src/aggregate.ts

docs/reference/cli-options.md

Add --regex-hint <term> to the CLI options reference table.

Acceptance criteria

• isRegexQuery(query) is called in searchAction() before fetchAllResults
• buildApiQuery() result used to substitute the API query
• --regex-hint <term> option present — overrides the derived API term
• Regex mode info line printed to stderr before the progress bar
• No exploitable term + no --regex-hint → non-zero exit, no empty API query sent
• regexFilter passed through to aggregate() correctly
• docs/usage/search-syntax.md has "Regex queries" section with all 4 use-case examples + admonition
• README.md has a "Regex search" use case
• docs/architecture/components.md — C4 Level 3a updated with src/regex.ts component
• AGENTS.md project layout + module map updated
• docs/reference/cli-options.md updated with --regex-hint
• bun test — full suite green
• bun run lint — zero errors
• bun run format:check — no diff
• bun run knip — no unused exports
• bun run build.ts — binary compiles
• bun run docs:build — no errors, no dead-link warnings

Branch

feat/regex-cli