Skip to content

codemap.md

Latest commit

 

History

History
28 lines (20 loc) · 3.25 KB

codemap.md

File metadata and controls

28 lines (20 loc) · 3.25 KB

src/tools/ast-grep/

Responsibility

  • Wrap the external ast-grep CLI so the broader system can invoke AST-aware search and replace without caring about binary discovery or argument details (cli.ts, tools.ts).
  • Provide well-typed tooling primitives (types.ts) plus formatted user output hints/summary helpers (utils.ts) that can be re-used by CLI commands or plugin UI layers.
  • Manage the brittle parts of CLI usage: locating a binary from caches, npm packages, or homebrew, downloading platform-specific releases when needed, and surfacing environment status/limits (constants.ts, downloader.ts).

Design Patterns and Decisions

  • Singleton initialization with retries: getAstGrepPath caches an init promise so concurrent requests share discovery/download work and fallback from local binaries to downloads (cli.ts).
  • Tool definition as declarative metadata: tools.ts exports ast_grep_search and ast_grep_replace via the OpenCode tool registry, which keeps descriptions, schemas, and execution logic centralized.
  • Separation of concerns: cli.ts focuses on process spawning and JSON parsing, constants.ts owns binary path resolution plus environment checks/formatting, utils.ts formats results while downloader.ts handles platform maps, cache directories, and fetch/extraction.
  • Fail fast with hints: Empty-match hints tailored per language (e.g., help removing trailing colons in Python) make search UX better while keeping AST requirements explicit.

Data & Control Flow

  • Tools (ast_grep_search, ast_grep_replace) call runSg, populating CLI arguments (pattern, rewrite, globs, context) and routing output through formatSearchResult/formatReplaceResult before reporting via showOutputToUser (tools.ts).
  • runSg constructs the command, ensures the CLI binary exists (resetting via getAstGrepPath which may call findSgCliPathSync or trigger a download), spawns the process with timeout handling, and parses compact JSON while guarding against truncated output and CLI errors (cli.ts).
  • Binary resolution uses constants.ts helpers to detect cached binaries, installed packages, platform-specific packages, or Homebrew paths, and exposes environment checks/formatting to upstream callers (constants.ts).
  • downloader.ts is the fallback path: it infers the platform key, downloads the matching GitHub release, extracts sg, sets executable bits, and caches it under ~/.cache/oh-my-opencode-slim/bin (or Windows AppData) so subsequent commands reuse the binary.

Integration Points

  • index.ts re-exports ast_grep_search, ast_grep_replace, runtime helpers (ensureCliAvailable, checkEnvironment, etc.), and downloader utilities so other modules can plug into the tooling layer while sharing diagnostics (index.ts).
  • The OpenCode plugin layer imports builtinTools from src/tools/ast-grep/index.ts to surface search/replace capabilities through the CLI tool registry.
  • constants.ts and downloader.ts are used by cli.ts to decide where to execute sg, while environment helpers inform onboarding UIs or setup scripts about missing binaries.
  • types.ts defines the shared CliLanguage, CliMatch, and SgResult shapes that drive type safety across CLI invocation, formatting utilities, and tooling schemas.