If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/biomejs/gritql shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 18 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 66% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live biomejs/gritql repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/biomejs/gritql.

What it runs against: a local clone of biomejs/gritql — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in biomejs/gritql | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 37 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of biomejs/gritql. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/biomejs/gritql.git
#   cd gritql
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of biomejs/gritql and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "biomejs/gritql(\\.git)?\\b" \\
  && ok "origin remote is biomejs/gritql" \\
  || miss "origin remote is not biomejs/gritql (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/core/src/lib.rs" \\
  && ok "crates/core/src/lib.rs" \\
  || miss "missing critical file: crates/core/src/lib.rs"
test -f "crates/grit-pattern-matcher/src/lib.rs" \\
  && ok "crates/grit-pattern-matcher/src/lib.rs" \\
  || miss "missing critical file: crates/grit-pattern-matcher/src/lib.rs"
test -f "crates/cli/src/lib.rs" \\
  && ok "crates/cli/src/lib.rs" \\
  || miss "missing critical file: crates/cli/src/lib.rs"
test -f "crates/language/src/lib.rs" \\
  && ok "crates/language/src/lib.rs" \\
  || miss "missing critical file: crates/language/src/lib.rs"
test -f "crates/gritmodule/src/lib.rs" \\
  && ok "crates/gritmodule/src/lib.rs" \\
  || miss "missing critical file: crates/gritmodule/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 37 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~7d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/biomejs/gritql"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

GritQL is a declarative query language that searches, lints, and modifies source code across 11+ target languages (JavaScript/TypeScript, Python, Java, Rust, Go, SQL, etc.). It lets developers write code patterns once and apply them to any codebase—from simple grep-like searches (console.log($_)) to sophisticated AST-based rewrites with conditional logic—without learning language-specific AST details. The core is a Rust engine (~2.3M LOC) that compiles patterns to optimized queries, enabling fast execution on 10M+ line repositories. Monorepo with Rust-heavy architecture: crates/core contains the pattern-matching engine, crates/cli (Cargo binary) wraps it for the CLI tool, crates/language handles target language support, crates/gritmodule manages the module/pattern registry, crates/wasm-bindings compiles to WebAssembly for web/Node consumption. generated holds compiled WASM artifacts and TypeScript type definitions. js/gritql provides Node.js/TypeScript integration. .grit/ contains Grit's own pattern definitions and configuration.

Infrastructure engineers and platform teams building internal linting systems; refactoring leads performing large-scale codebase migrations; developers creating reusable, shareable code patterns (the stdlib has 200+ patterns); and organizations needing cross-language code governance without learning each language's AST structure.

Actively developed and production-ready. The project is at v0.5.1 with a mature CI/CD setup (GitHub Actions for code-quality, docs, release, Python testing, and NAPI builds), substantial Rust codebase (2.3M LOC), TypeScript bindings for web/Node consumption, and a well-organized monorepo structure. Release automation via release-plz is configured, indicating intent for frequent updates.

Low risk for core functionality, moderate risk for ecosystem stability. The Rust engine is substantial and well-tested via CI, but the project depends on external tree-sitter grammar vendoring (vendor/tree-sitter-*), which could introduce maintenance burden. The v0.5.x versioning suggests the API may still evolve; breaking changes are possible. Single-repo governance under getgrit organization means feature velocity depends on that team's capacity.

Active development on v0.5.1 with infrastructure automation via release-plz for continuous releases. The .github/workflows show investment in code-quality checks (CodeRabbit), documentation generation, and Python test integration. The repo uses its own patterns (.grit/patterns/) for internal code linting (cargo_meta.md, flushable_unwrap.md, no_panic.md), demonstrating dogfooding. Auth infrastructure (crates/auth) suggests SaaS/cloud features are being built.

git clone https://github.com/getgrit/gritql.git
cd gritql
cargo build --release
./target/release/grit --help

Or install the prebuilt CLI: curl -fsSL https://docs.grit.io/install | bash

Daily commands:

# Dev build
cargo build
# Run CLI on a pattern
cargo run --release -- apply '`console.log($_)`' --dry-run
# Run tests
cargo test
# Build WASM bindings (requires wasm-pack)
cd crates/wasm-bindings && wasm-pack build --target nodejs

• crates/core/src/lib.rs — Core pattern matching engine—entry point for all query execution and AST traversal logic that powers GritQL
• crates/grit-pattern-matcher/src/lib.rs — Pattern matcher abstraction layer that orchestrates code queries and rewrites across all supported languages
• crates/cli/src/lib.rs — CLI library facade exposing all user-facing commands; essential for understanding how patterns flow from files to execution
• crates/language/src/lib.rs — Language detection and tree-sitter parser bindings for multi-language support—load-bearing for code analysis
• crates/gritmodule/src/lib.rs — Module system for pattern discovery, loading, and dependency resolution—required for understanding pattern reuse
• Cargo.toml — Workspace definition and version management; shows repo structure and all crate dependencies
• crates/cli/src/commands/mod.rs — Command router for all CLI operations; maps user input to pattern matching and code transformation logic

Add a new CLI command

1. Create a new file in crates/cli/src/commands/ following the naming convention (crates/cli/src/commands/my_command.rs)
2. Implement the command struct with clap derive macros and a run() method (crates/cli/src/commands/my_command.rs)
3. Add the command module declaration and enum variant in mod.rs (crates/cli/src/commands/mod.rs)
4. Export the command in the main CLI router to wire it into the argument parser (crates/cli/src/lib.rs)

Add support for a new programming language

1. Create a tree-sitter grammar and parser library in vendor/tree-sitter-<lang>/ (vendor/tree-sitter-<lang>/grammar.js)
2. Register the new language in the language detection module (crates/language/src/lib.rs)
3. Add language-specific pattern examples in .grit/patterns/ (.grit/patterns/<lang>_example.md)
4. Test pattern matching on sample code files using the patterns_test command (crates/cli/src/commands/patterns_test.rs)

Create a reusable pattern library

1. Create a .md pattern file in .grit/patterns/ or in your grit workspace (.grit/patterns/my_pattern.md)
2. Define the pattern using GritQL syntax with sections for description, pattern, and test cases (.grit/patterns/my_pattern.md)
3. Register the pattern in grit.yaml for module discovery (.grit/grit.yaml)
4. Test the pattern using patterns_test command and publish via patterns_list (crates/cli/src/commands/patterns_test.rs)

Add a new caching or optimization strategy

1. Create or extend the caching layer in gritcache (crates/gritcache/src/lib.rs)
2. Integrate cache invalidation logic into the pattern matching engine (crates/grit-pattern-matcher/src/lib.rs)
3. Add configuration flags in the CLI flags module to control cache behavior (crates/cli/src/flags.rs)

• Rust — Enables safe, high-performance AST traversal and pattern matching at scale (10M+ line repos); memory safety prevents crashes in long-running CLI processes
• Tree-sitter — Provides incremental, language-agnostic parsing for 30+ languages without vendor lock-in; enables AST-based queries instead of regex
• WebAssembly (WASM) — Allows GritQL execution in browsers and web services without requiring users to install Rust toolchain; enables playground demos and web IDE integration
• clap (CLI framework) — Declarative command/flag parsing with derive macros; reduces boilerplate for subcommands and reduces bugs in argument handling
• Workspace Cargo structure — Separates concerns (core engine, CLI, WASM, auth) while sharing dependencies; enables independent deployment of CLI vs library vs WASM

• GritQL as a declarative query language (not imperative scripting)

  • Why: Declarative patterns are easier for non-programmers to read and optimize (query planner can reorder matches); imperative would be more expressive
  • Consequence: Complex transformations require composing multiple patterns or adding new pattern syntax; not suitable for arbitrary control flow

• Single-pass pattern matching with on-disk results (not multi-pass in-memory graph database)

  • Why: Enables scanning massive repos without storing entire AST in memory; simple streaming architecture
  • Consequence: Cannot perform complex relational queries across disconnected parts of codebase; cross-file analysis requires multiple pattern passes

• File-based pattern library (.md files in .grit/patterns/) instead of centralized registry

  • Why: Patterns are versioned with code; teams control which patterns apply to their repo; no network dependency
  • Consequence: Harder to discover community patterns; requires explicit opt-in to each pattern version

• AST-based matching only (

  • Why: undefined
  • Consequence: undefined

Tree-sitter submodules: .gitmodules references vendor/tree-sitter-* and vendor/tree-sitter-gritql; must run git submodule update --init --recursive after clone. WASM build: requires wasm-pack toolchain (not standard Rust); see crates/wasm-bindings build scripts. Auth secrets: crates/auth uses Auth0; CI likely requires AUTH0_* env vars for integration tests (check .github/workflows/). Release automation: release-plz.toml is configured; commits and tags are auto-created on version bumps—do not manually edit Cargo.toml versions. Generated code: generated/ is not checked in; WASM build via CI regenerates it for releases.

• Abstract Syntax Tree (AST) Matching — GritQL operates on ASTs rather than text; understanding how tree-sitter builds and traverses ASTs is essential to writing patterns that work correctly across code variations
• Tree-sitter Incremental Parsing — Tree-sitter (the core parser) uses incremental parsing for speed; knowing how it caches parse trees lets you understand why GritQL scales to 10M+ line repos
• Metaprogramming & Code Generation — GritQL is a domain-specific language (DSL) that generates code transformations; the compiler pipeline (pattern → matcher → rewrite rules) is a practical example of metaprogramming in Rust
• Pattern Rewriting & Term Rewriting Systems — GritQL's => operator executes term rewriting rules; understanding rewrite semantics (left-hand side match, right-hand side substitution) is core to using the tool effectively
• WebAssembly (WASM) for Code Distribution — GritQL compiles to WASM to run in browsers and Node.js without a separate binary; WASM bindings bridge Rust and JavaScript ecosystems
• Constraint Solving & Where Clauses — GritQL's where { } syntax enforces logical constraints on matches (e.g., 'match only if variable is NOT inside a try-catch'); this is declarative constraint programming
• Multi-language Code Analysis — Supporting 11+ languages requires language-agnostic AST abstractions; GritQL's crates/language module normalizes across tree-sitter grammars so one pattern works everywhere

• getgrit/stdlib — Official Grit pattern library with 200+ reusable patterns; direct dependency for users and source of canonical pattern examples
• tree-sitter/tree-sitter — Foundational parsing library used by Grit; tree-sitter grammars enable language support across the tool
• ast-grep/ast-grep — Direct competitor: also a declarative code search tool using tree-sitter; solves the same problem with different syntax and ecosystem
• comby-tools/comby — Spiritual predecessor: early declarative code rewrite tool; Grit improves on it with AST-awareness and broader language support
• getgrit/docs — Grit's documentation site and tutorials; essential for understanding pattern syntax and CLI usage

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Python bindings in crates/wasm-bindings

The repo has a python-tests.yml workflow but the crates/wasm-bindings directory lacks visible Python test files. Given that GritQL compiles to WASM and likely has Python bindings, adding comprehensive integration tests would ensure cross-language compatibility. This is critical for a polyglot tool like GritQL.

• [ ] Create tests/python/ directory in crates/wasm-bindings or at repo root
• [ ] Add pytest fixtures for wasm module initialization
• [ ] Write tests for core query execution, pattern matching, and code modification flows
• [ ] Update .github/workflows/python-tests.yml to run the new test suite with proper coverage reporting
• [ ] Document Python API usage in crates/wasm-bindings/README.md

Add missing E2E tests for CLI commands in crates/cli/tests/

The crates/cli/src/commands/ directory shows 15+ command implementations (apply, parse, format, check, install, etc.) but there's no visible tests/ directory. E2E tests for these commands would catch regressions and make the CLI more reliable for users. This is especially important for commands that modify code (apply, apply_migration).

• [ ] Create crates/cli/tests/ directory with integration test files
• [ ] Write E2E tests for crates/cli/src/commands/apply.rs using a temporary file fixture
• [ ] Write E2E tests for crates/cli/src/commands/parse.rs with sample code input
• [ ] Write E2E tests for crates/cli/src/commands/check.rs validating exit codes
• [ ] Add test fixtures (sample code files) in crates/cli/tests/fixtures/
• [ ] Update main.yaml CI workflow to run 'cargo test --package grit-cli' with verbose output

Add cargo deny configuration to catch supply chain vulnerabilities

The workspace has many dependencies (auth, externals, tree-sitter bindings) but there's no cargo-deny.toml or supply-chain security checks in CI. Given the security-sensitive nature of code transformation tools, this is a high-value hardening measure that other major Rust projects implement.

• [ ] Create cargo-deny.toml at repo root with deny rules for crates (advisories, licenses, bans)
• [ ] Configure to block unmaintained dependencies and GPL licenses (if MIT-only is desired)
• [ ] Add 'cargo deny check' step to .github/workflows/code-quality.yaml
• [ ] Document supply-chain security policy in SECURITY.md with guidance on reporting vulnerable dependencies
• [ ] Consider adding SBOM generation step using cargo-sbom in release workflow

• Add comprehensive unit tests for crates/grit-pattern-matcher/src/binding.rs—current coverage unknown and this is core logic for variable capture and scoping.
• Document the pattern syntax BNF grammar in docs/ and link from README—users currently rely on examples; a formal grammar spec would aid tool developers and reduce confusion.
• Create end-to-end test suite in crates/cli/tests/ with runnable examples for each target language (currently only Python tests are in workflows; TypeScript/Rust/Java examples are missing).

The GritQL repository shows a generally good security posture with a dedicated SECURITY.md file and security contact information established. The main concerns are around generated artifacts (WASM binaries), vendored dependencies management, and ensuring authentication implementation follows security best practices. The codebase lacks visible hardcoded secrets or obvious injection vulnerabilities in the provided file structure. Recommendations focus on strengthening CI/CD security controls, dependency auditing, and ensuring auth module implements secure patterns. No critical vulnerabilities were identified in the static structure analysis.

• Medium · Potential Sensitive Information in Repository Structure — .grit/grit.yaml, .grit/patterns/. The repository contains a .grit directory with patterns and configuration files. While no secrets are directly visible in the provided structure, pattern files and configuration could potentially contain sensitive information if not properly managed. Fix: Ensure .grit configuration files do not contain hardcoded API keys, tokens, or credentials. Use environment variables for sensitive configuration. Add sensitive files to .gitignore.
• Low · Generated WASM Bindings Not Explicitly Signed — __generated__/grit-wasm-bindings/. The generated directory contains WASM bindings (.wasm files) that are binary artifacts. Binary files in version control can pose supply chain risks if not properly validated. Fix: Consider generating WASM bindings during build rather than committing them. If committed, ensure integrity checks and code signing are in place. Document the build process for reproducibility.
• Low · Vendored Dependencies — Cargo.toml (exclude section), vendor/tree-sitter-* directories. The repository excludes 'vendor/' directory in Cargo.toml but references tree-sitter components. Vendored code can become outdated and miss security patches. Fix: Regularly audit vendored dependencies for security updates. Consider using dependency management tools like cargo-audit or dependabot to track vulnerabilities in vendored code.
• Low · Multiple Workflow Files Without Explicit Security Context — .github/workflows/. GitHub Actions workflows are present but specific security configurations (permissions, secrets management, branch protections) are not visible in the provided snippet. Fix: Review all workflow files to ensure: 1) Minimal required permissions are used, 2) Secrets are not logged, 3) Dependency pinning is used, 4) Branch protection rules are enforced, 5) Third-party actions are from trusted sources.
• Low · Release Process Configuration Visible — .release-plz.toml. The .release-plz.toml file indicates automated release process. Improper access controls on this configuration could lead to unauthorized releases. Fix: Ensure release automation is protected by proper CI/CD access controls. Require code review and approval for release PRs. Verify that only authorized users can trigger releases.
• Medium · Auth Module Present Without Visible Implementation Details — crates/auth/src/auth0.rs, crates/auth/src/lib.rs. The crates/auth module contains auth0.rs, suggesting third-party authentication integration. Implementation details are not visible but authentication logic is critical. Fix: Conduct thorough code review of authentication module. Ensure: 1) Tokens are not logged, 2) Secure storage of credentials, 3) Proper token expiration, 4) Protection against CSRF and token reuse attacks, 5) Regular security audit of OAuth/OIDC implementation.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.