[
  {
    "path": ".claude-plugin/marketplace.json",
    "content": "{\n  \"name\": \"ast-grep-marketplace\",\n  \"owner\": {\n    \"name\": \"Herrington Darkholme\"\n  },\n  \"metadata\": {\n    \"description\": \"A marketplace for Claude Code skills including ast-grep structural code search\",\n    \"version\": \"1.0.0\",\n    \"repository\": \"https://github.com/ast-grep/claude-skill\",\n    \"homepage\": \"https://github.com/ast-grep/claude-skill\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"ast-grep\",\n      \"source\": \"./ast-grep\",\n      \"description\": \"Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search.\",\n      \"version\": \"1.0.0\",\n      \"keywords\": [\n        \"ast-grep\",\n        \"code-search\",\n        \"ast\",\n        \"structural-search\",\n        \"pattern-matching\",\n        \"refactoring\"\n      ]\n    }\n  ]\n}\n"
  },
  {
    "path": "README.md",
    "content": "# ast-grep Plugin Marketplace for AI Agents\n\nA Claude Code plugin marketplace containing the ast-grep skill for powerful structural code search using Abstract Syntax Tree (AST) patterns. Search your codebase based on code structure rather than just text matching.\n\n## What is This?\n\nThis is a **Claude Code plugin marketplace** that provides the **ast-grep plugin**. The plugin includes a skill that teaches Claude how to write and use ast-grep rules to perform advanced code searches. Unlike traditional text-based search (grep, ripgrep), ast-grep understands the structure of your code, allowing you to find patterns like:\n\n- \"Find all async functions that don't have error handling\"\n- \"Locate all React components that use a specific hook\"\n- \"Find functions with more than 3 parameters\"\n- \"Search for console.log calls inside class methods\"\n\n\n\n\n## Prerequisites\n\nYou need to have ast-grep installed on your system:\n\n```bash\n# macOS\nbrew install ast-grep\n\n# npm\nnpm install -g @ast-grep/cli\n\n# cargo\ncargo install ast-grep\n```\n\nVerify installation:\n```bash\nast-grep --version\n```\n\n## Installation\n\n### Option 1: Install via skills.sh (Recommended)\n\n```\nnpx skills add ast-grep/agent-skill\n```\n\n### Option 2: Install via Marketplace \n\n1. **Add the marketplace** to your Claude Code:\n\n```bash\n/plugin marketplace add ast-grep/agent-skill\n```\n\n2. **Install the ast-grep plugin**:\n\n```bash\n/plugin install ast-grep\n```\n\n3. **Restart Claude Code** to activate the plugin\n\n4. **Verify installation**: Use `/help` to see if ast-grep skill is available\n\n### Option 3: Install Locally for Development\n\nIf you're developing or testing locally:\n\n```bash\n# Clone the repository\ngit clone https://github.com/ast-grep/claude-skill.git /path/to/local-marketplace\n\n# Add as local marketplace\n/plugin marketplace add /path/to/local-marketplace\n\n# Install the plugin\n/plugin install ast-grep\n```\n\n### Usage Notes\n\nYou will need to ask Claude to use this skill explicitly in your queries, like \"Use ast-grep to find...\". Claude Code, as of Nov 2025, cannot automatically detect when to use ast-grep for all appropriate use cases.\n\n## How to Use\n\nOnce installed, simply ask Claude to search your code using structural patterns. Claude will automatically use this skill when appropriate.\n\n### Example Queries\n\n**Find async functions with await:**\n```\nFind all async functions in this project that use await\n```\n\n**Find missing error handling:**\n```\nShow me async functions that don't have try-catch blocks\n```\n\n**Find specific function calls:**\n```\nFind all places where we call console.log with more than one argument\n```\n\n**Find code in specific contexts:**\n```\nFind all setState calls inside useEffect hooks\n```\n\n### How It Works\n\nWhen you ask Claude to search for code patterns:\n\n1. Claude analyzes your query and determines if ast-grep is appropriate\n2. It creates example code that matches your search criteria\n3. It writes an ast-grep rule to match the pattern\n4. It tests the rule against the example code\n5. Once verified, it searches your entire codebase\n6. Results are presented with file paths and line numbers\n\n## Supported Languages\n\nast-grep supports many programming languages including:\n\n- JavaScript/TypeScript\n- Python\n- Rust\n- Go\n- Java\n- C/C++\n- Ruby\n- PHP\n- And many more\n\n## Key Features\n\n- **Structure-aware search**: Matches code based on AST structure, not just text\n- **Metavariables**: Use `$VAR` to match any expression, statement, or identifier\n- **Relational queries**: Find code inside specific contexts (e.g., \"find X inside Y\")\n- **Composite logic**: Combine rules with AND, OR, NOT operations\n- **Test-driven approach**: Rules are tested before running on your codebase\n\n## Advanced Usage\n\n### Direct ast-grep Commands\n\nWhile Claude will handle most use cases automatically, you can also use ast-grep directly:\n\n```bash\n# Simple pattern search\nast-grep run --pattern 'console.log($ARG)' --lang javascript .\n\n# Complex rule-based search\nast-grep scan --inline-rules \"id: my-rule\nlanguage: javascript\nrule:\n  kind: function_declaration\n  has:\n    pattern: await \\$EXPR\n    stopBy: end\" .\n```\n\n### Debugging\n\nIf a search isn't working as expected, ask Claude to:\n- Show you the ast-grep rule it created\n- Inspect the AST structure of your code\n- Test the rule against example code\n\n## Repository Structure\n\nThis is a Claude Code plugin marketplace repository with the following structure:\n\n```\nclaude-skill/\n├── .claude-plugin/\n│   └── marketplace.json           # Marketplace manifest\n├── ast-grep/                       # ast-grep plugin\n│   ├── .claude-plugin/\n│   │   └── plugin.json            # Plugin manifest\n│   └── skills/\n│       └── ast-grep/\n│           ├── SKILL.md           # Skill instructions for Claude\n│           └── references/\n│               └── rule_reference.md  # ast-grep rule documentation\n├── ast-grep.zip                    # Archived version\n└── README.md                       # This file\n```\n\n### Key Files\n\n- **`.claude-plugin/marketplace.json`**: Marketplace manifest defining available plugins\n- **`ast-grep/.claude-plugin/plugin.json`**: Plugin manifest for the ast-grep plugin\n- **`ast-grep/skills/ast-grep/SKILL.md`**: Main skill instructions that Claude uses\n- **`ast-grep/skills/ast-grep/references/`**: Supporting documentation and reference materials\n\n## Tips for Best Results\n\n1. **Be specific**: The more details you provide, the better the search results\n2. **Provide examples**: If possible, show Claude an example of what you want to find\n3. **Iterate**: Start with a broad search and narrow it down\n4. **Ask for explanations**: Ask Claude to explain the ast-grep rule it creates\n\n## Examples of What You Can Search For\n\n### Code Quality\n- Functions without return statements\n- Functions with too many parameters\n- Unused variables\n- Missing null checks\n\n### Patterns\n- React hooks usage patterns\n- API call patterns\n- Database query patterns\n- Error handling patterns\n\n### Refactoring\n- Find all uses of deprecated functions\n- Locate code that needs migration\n- Find inconsistent patterns across codebase\n\n### Security\n- Potential SQL injection points\n- Unsafe eval usage\n- Missing input validation\n\n## Troubleshooting\n\n**Claude isn't using the skill:**\n- Make sure ast-grep is installed (`ast-grep --version`)\n- Try being more explicit: \"Use ast-grep to search for...\"\n\n**No results found:**\n- Try a simpler query first\n- Ask Claude to show you the rule and test it\n- Provide an example of code you want to match\n\n**Unexpected results:**\n- Refine your query with more details\n- Ask Claude to exclude certain patterns\n- Request to see the AST structure of your code\n\n## Contributing\n\nTo improve this skill:\n1. Edit `SKILL.md` to update Claude's instructions\n2. Add examples to `references/` directory\n3. Test with various code patterns\n\n## Resources\n\n- [ast-grep Official Documentation](https://ast-grep.github.io/)\n- [ast-grep Playground](https://ast-grep.github.io/playground.html) - Test patterns online\n- [ast-grep GitHub](https://github.com/ast-grep/ast-grep)\n\n## License\n\nThis skill follows ast-grep's MIT license for any included documentation or examples.\n\n## Support\n\nFor issues with:\n- **This skill**: Open an issue in this repository\n- **ast-grep itself**: Visit [ast-grep GitHub](https://github.com/ast-grep/ast-grep)\n- **Claude Code**: Check [Claude Code documentation](https://code.claude.com/)\n"
  },
  {
    "path": "ast-grep/.claude-plugin/plugin.json",
    "content": "{\n  \"name\": \"ast-grep\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search.\",\n  \"author\": {\n    \"name\": \"Herrington Darkholme\"\n  },\n  \"homepage\": \"https://github.com/ast-grep/claude-skill\",\n  \"repository\": \"https://github.com/ast-grep/claude-skill\",\n  \"license\": \"MIT\",\n  \"keywords\": [\n    \"ast-grep\",\n    \"code-search\",\n    \"ast\",\n    \"structural-search\",\n    \"pattern-matching\",\n    \"refactoring\"\n  ]\n}\n"
  },
  {
    "path": "ast-grep/skills/ast-grep/SKILL.md",
    "content": "---\nname: ast-grep\ndescription: Guide for writing ast-grep rules to perform structural code search and analysis. Use when users need to search codebases using Abstract Syntax Tree (AST) patterns, find specific code structures, or perform complex code queries that go beyond simple text search. This skill should be used when users ask to search for code patterns, find specific language constructs, or locate code with particular structural characteristics.\n---\n\n# ast-grep Code Search\n\n## Overview\n\nThis skill helps translate natural language queries into ast-grep rules for structural code search. ast-grep uses Abstract Syntax Tree (AST) patterns to match code based on its structure rather than just text, enabling powerful and precise code search across large codebases.\n\n## When to Use This Skill\n\nUse this skill when users:\n- Need to search for code patterns using structural matching (e.g., \"find all async functions that don't have error handling\")\n- Want to locate specific language constructs (e.g., \"find all function calls with specific parameters\")\n- Request searches that require understanding code structure rather than just text\n- Ask to search for code with particular AST characteristics\n- Need to perform complex code queries that traditional text search cannot handle\n\n## General Workflow\n\nFollow this process to help users write effective ast-grep rules:\n\n### Step 1: Understand the Query\n\nClearly understand what the user wants to find. Ask clarifying questions if needed:\n- What specific code pattern or structure are they looking for?\n- Which programming language?\n- Are there specific edge cases or variations to consider?\n- What should be included or excluded from matches?\n\n### Step 2: Create Example Code\n\nWrite a simple code snippet that represents what the user wants to match. Save this to a temporary file for testing.\n\n**Example:**\nIf searching for \"async functions that use await\", create a test file:\n\n```javascript\n// test_example.js\nasync function example() {\n  const result = await fetchData();\n  return result;\n}\n```\n\n### Step 3: Write the ast-grep Rule\n\nTranslate the pattern into an ast-grep rule. Start simple and add complexity as needed.\n\n**Key principles:**\n- Always use `stopBy: end` for relational rules (`inside`, `has`) to ensure search goes to the end of the direction\n- Use `pattern` for simple structures\n- Use `kind` with `has`/`inside` for complex structures\n- Break complex queries into smaller sub-rules using `all`, `any`, or `not`\n\n**Example rule file (test_rule.yml):**\n```yaml\nid: async-with-await\nlanguage: javascript\nrule:\n  kind: function_declaration\n  has:\n    pattern: await $EXPR\n    stopBy: end\n```\n\nSee `references/rule_reference.md` for comprehensive rule documentation.\n\n### Step 4: Test the Rule\n\nUse ast-grep CLI to verify the rule matches the example code. There are two main approaches:\n\n**Option A: Test with inline rules (for quick iterations)**\n```bash\necho \"async function test() { await fetch(); }\" | ast-grep scan --inline-rules \"id: test\nlanguage: javascript\nrule:\n  kind: function_declaration\n  has:\n    pattern: await \\$EXPR\n    stopBy: end\" --stdin\n```\n\n**Option B: Test with rule files (recommended for complex rules)**\n```bash\nast-grep scan --rule test_rule.yml test_example.js\n```\n\n**Debugging if no matches:**\n1. Simplify the rule (remove sub-rules)\n2. Add `stopBy: end` to relational rules if not present\n3. Use `--debug-query` to understand the AST structure (see below)\n4. Check if `kind` values are correct for the language\n\n### Step 5: Search the Codebase\n\nOnce the rule matches the example code correctly, search the actual codebase:\n\n**For simple pattern searches:**\n```bash\nast-grep run --pattern 'console.log($ARG)' --lang javascript /path/to/project\n```\n\n**For complex rule-based searches:**\n```bash\nast-grep scan --rule my_rule.yml /path/to/project\n```\n\n**For inline rules (without creating files):**\n```bash\nast-grep scan --inline-rules \"id: my-rule\nlanguage: javascript\nrule:\n  pattern: \\$PATTERN\" /path/to/project\n```\n\n## ast-grep CLI Commands\n\n### Inspect Code Structure (--debug-query)\n\nDump the AST structure to understand how code is parsed:\n\n```bash\nast-grep run --pattern 'async function example() { await fetch(); }' \\\n  --lang javascript \\\n  --debug-query=cst\n```\n\n**Available formats:**\n- `cst`: Concrete Syntax Tree (shows all nodes including punctuation)\n- `ast`: Abstract Syntax Tree (shows only named nodes)\n- `pattern`: Shows how ast-grep interprets your pattern\n\n**Use this to:**\n- Find the correct `kind` values for nodes\n- Understand the structure of code you want to match\n- Debug why patterns aren't matching\n\n**Example:**\n```bash\n# See the structure of your target code\nast-grep run --pattern 'class User { constructor() {} }' \\\n  --lang javascript \\\n  --debug-query=cst\n\n# See how ast-grep interprets your pattern\nast-grep run --pattern 'class $NAME { $$$BODY }' \\\n  --lang javascript \\\n  --debug-query=pattern\n```\n\n### Test Rules (scan with --stdin)\n\nTest a rule against code snippet without creating files:\n\n```bash\necho \"const x = await fetch();\" | ast-grep scan --inline-rules \"id: test\nlanguage: javascript\nrule:\n  pattern: await \\$EXPR\" --stdin\n```\n\n**Add --json for structured output:**\n```bash\necho \"const x = await fetch();\" | ast-grep scan --inline-rules \"...\" --stdin --json\n```\n\n### Search with Patterns (run)\n\nSimple pattern-based search for single AST node matches:\n\n```bash\n# Basic pattern search\nast-grep run --pattern 'console.log($ARG)' --lang javascript .\n\n# Search specific files\nast-grep run --pattern 'class $NAME' --lang python /path/to/project\n\n# JSON output for programmatic use\nast-grep run --pattern 'function $NAME($$$)' --lang javascript --json .\n```\n\n**When to use:**\n- Simple, single-node matches\n- Quick searches without complex logic\n- When you don't need relational rules (inside/has)\n\n### Search with Rules (scan)\n\nYAML rule-based search for complex structural queries:\n\n```bash\n# With rule file\nast-grep scan --rule my_rule.yml /path/to/project\n\n# With inline rules\nast-grep scan --inline-rules \"id: find-async\nlanguage: javascript\nrule:\n  kind: function_declaration\n  has:\n    pattern: await \\$EXPR\n    stopBy: end\" /path/to/project\n\n# JSON output\nast-grep scan --rule my_rule.yml --json /path/to/project\n```\n\n**When to use:**\n- Complex structural searches\n- Relational rules (inside, has, precedes, follows)\n- Composite logic (all, any, not)\n- When you need the power of full YAML rules\n\n**Tip:** For relational rules (inside/has), always add `stopBy: end` to ensure complete traversal.\n\n## Tips for Writing Effective Rules\n\n### Always Use stopBy: end\n\nFor relational rules, always use `stopBy: end` unless there's a specific reason not to:\n\n```yaml\nhas:\n  pattern: await $EXPR\n  stopBy: end\n```\n\nThis ensures the search traverses the entire subtree rather than stopping at the first non-matching node.\n\n### Start Simple, Then Add Complexity\n\nBegin with the simplest rule that could work:\n1. Try a `pattern` first\n2. If that doesn't work, try `kind` to match the node type\n3. Add relational rules (`has`, `inside`) as needed\n4. Combine with composite rules (`all`, `any`, `not`) for complex logic\n\n### Use the Right Rule Type\n\n- **Pattern**: For simple, direct code matching (e.g., `console.log($ARG)`)\n- **Kind + Relational**: For complex structures (e.g., \"function containing await\")\n- **Composite**: For logical combinations (e.g., \"function with await but not in try-catch\")\n\n### Debug with AST Inspection\n\nWhen rules don't match:\n1. Use `--debug-query=cst` to see the actual AST structure\n2. Check if metavariables are being detected correctly\n3. Verify the node `kind` matches what you expect\n4. Ensure relational rules are searching in the right direction\n\n### Escaping in Inline Rules\n\nWhen using `--inline-rules`, escape metavariables in shell commands:\n- Use `\\$VAR` instead of `$VAR` (shell interprets `$` as variable)\n- Or use single quotes: `'$VAR'` works in most shells\n\n**Example:**\n```bash\n# Correct: escaped $\nast-grep scan --inline-rules \"rule: {pattern: 'console.log(\\$ARG)'}\" .\n\n# Or use single quotes\nast-grep scan --inline-rules 'rule: {pattern: \"console.log($ARG)\"}' .\n```\n\n## Common Use Cases\n\n### Find Functions with Specific Content\n\nFind async functions that use await:\n```bash\nast-grep scan --inline-rules \"id: async-await\nlanguage: javascript\nrule:\n  all:\n    - kind: function_declaration\n    - has:\n        pattern: await \\$EXPR\n        stopBy: end\" /path/to/project\n```\n\n### Find Code Inside Specific Contexts\n\nFind console.log inside class methods:\n```bash\nast-grep scan --inline-rules \"id: console-in-class\nlanguage: javascript\nrule:\n  pattern: console.log(\\$\\$\\$)\n  inside:\n    kind: method_definition\n    stopBy: end\" /path/to/project\n```\n\n### Find Code Missing Expected Patterns\n\nFind async functions without try-catch:\n```bash\nast-grep scan --inline-rules \"id: async-no-trycatch\nlanguage: javascript\nrule:\n  all:\n    - kind: function_declaration\n    - has:\n        pattern: await \\$EXPR\n        stopBy: end\n    - not:\n        has:\n          pattern: try { \\$\\$\\$ } catch (\\$E) { \\$\\$\\$ }\n          stopBy: end\" /path/to/project\n```\n\n## Resources\n\n### references/\nContains detailed documentation for ast-grep rule syntax:\n- `rule_reference.md`: Comprehensive ast-grep rule documentation covering atomic rules, relational rules, composite rules, and metavariables\n\nLoad these references when detailed rule syntax information is needed.\n"
  },
  {
    "path": "ast-grep/skills/ast-grep/references/rule_reference.md",
    "content": "# ast-grep Rule Reference\n\nThis document provides comprehensive documentation for ast-grep rule syntax, covering all rule types and metavariables.\n\n## Introduction to ast-grep Rules\n\nast-grep rules are declarative specifications for matching and filtering Abstract Syntax Tree (AST) nodes. They enable structural code search and analysis by defining conditions an AST node must meet to be matched.\n\n### Rule Categories\n\nast-grep rules are categorized into three types:\n\n* **Atomic Rules**: Match individual AST nodes based on intrinsic properties like code patterns (`pattern`), node type (`kind`), or text content (`regex`).\n* **Relational Rules**: Define conditions based on a target node's position or relationship to other nodes (e.g., `inside`, `has`, `precedes`, `follows`).\n* **Composite Rules**: Combine other rules using logical operations (AND, OR, NOT) to form complex matching criteria (e.g., `all`, `any`, `not`, `matches`).\n\n## Anatomy of an ast-grep Rule Object\n\nThe ast-grep rule object is the core configuration unit defining how ast-grep identifies and filters AST nodes. It's typically written in YAML format.\n\n### General Structure\n\nEvery field within an ast-grep Rule Object is optional, but at least one \"positive\" key (e.g., `kind`, `pattern`) must be present.\n\nA node matches a rule if it satisfies all fields defined within that rule object, implying an implicit logical AND operation.\n\nFor rules using metavariables that depend on prior matching, explicit `all` composite rules are recommended to guarantee execution order.\n\n### Rule Object Properties\n\n| Property | Type | Category | Purpose | Example |\n| :--- | :--- | :--- | :--- | :--- |\n| `pattern` | String or Object | Atomic | Matches AST node by code pattern. | `pattern: console.log($ARG)` |\n| `kind` | String | Atomic | Matches AST node by its kind name. | `kind: call_expression` |\n| `regex` | String | Atomic | Matches node's text by Rust regex. | `regex: ^[a-z]+$` |\n| `nthChild` | number, string, Object | Atomic | Matches nodes by their index within parent's children. | `nthChild: 1` |\n| `range` | RangeObject | Atomic | Matches node by character-based start/end positions. | `range: { start: { line: 0, column: 0 }, end: { line: 0, column: 10 } }` |\n| `inside` | Object | Relational | Target node must be inside node matching sub-rule. | `inside: { pattern: class $C { $$$ }, stopBy: end }` |\n| `has` | Object | Relational | Target node must have descendant matching sub-rule. | `has: { pattern: await $EXPR, stopBy: end }` |\n| `precedes` | Object | Relational | Target node must appear before node matching sub-rule. | `precedes: { pattern: return $VAL }` |\n| `follows` | Object | Relational | Target node must appear after node matching sub-rule. | `follows: { pattern: import $M from '$P' }` |\n| `all` | Array<Rule> | Composite | Matches if all sub-rules match. | `all: [ { kind: call_expression }, { pattern: foo($A) } ]` |\n| `any` | Array<Rule> | Composite | Matches if any sub-rules match. | `any: [ { pattern: foo() }, { pattern: bar() } ]` |\n| `not` | Object | Composite | Matches if sub-rule does not match. | `not: { pattern: console.log($ARG) }` |\n| `matches` | String | Composite | Matches if predefined utility rule matches. | `matches: my-utility-rule-id` |\n\n## Atomic Rules\n\nAtomic rules match individual AST nodes based on their intrinsic properties.\n\n### pattern: String and Object Forms\n\nThe `pattern` rule matches a single AST node based on a code pattern.\n\n**String Pattern**: Directly matches using ast-grep's pattern syntax with metavariables.\n\n```yaml\npattern: console.log($ARG)\n```\n\n**Object Pattern**: Offers granular control for ambiguous patterns or specific contexts.\n\n* `selector`: Pinpoints a specific part of the parsed pattern to match.\n  ```yaml\n  pattern:\n    selector: field_definition\n    context: class { $F }\n  ```\n\n* `context`: Provides surrounding code context for correct parsing.\n\n* `strictness`: Modifies the pattern's matching algorithm (`cst`, `smart`, `ast`, `relaxed`, `signature`).\n  ```yaml\n  pattern:\n    context: foo($BAR)\n    strictness: relaxed\n  ```\n\n### kind: Matching by Node Type\n\nThe `kind` rule matches an AST node by its `tree_sitter_node_kind` name, derived from the language's Tree-sitter grammar. Useful for targeting constructs like `call_expression` or `function_declaration`.\n\n```yaml\nkind: call_expression\n```\n\n### regex: Text-Based Node Matching\n\nThe `regex` rule matches the entire text content of an AST node using a Rust regular expression. It's not a \"positive\" rule, meaning it matches any node whose text satisfies the regex, regardless of its structural kind.\n\n### nthChild: Positional Node Matching\n\nThe `nthChild` rule finds nodes by their 1-based index within their parent's children list, counting only named nodes by default.\n\n* `number`: Matches the exact nth child. Example: `nthChild: 1`\n* `string`: Matches positions using An+B formula. Example: `2n+1`\n* `Object`: Provides granular control:\n  * `position`: `number` or An+B string.\n  * `reverse`: `true` to count from the end.\n  * `ofRule`: An ast-grep rule to filter the sibling list before counting.\n\n### range: Position-Based Node Matching\n\nThe `range` rule matches an AST node based on its character-based start and end positions. A `RangeObject` defines `start` and `end` fields, each with 0-based `line` and `column`. `start` is inclusive, `end` is exclusive.\n\n## Relational Rules\n\nRelational rules filter targets based on their position relative to other AST nodes. They can include `stopBy` and `field` options.\n\n### inside: Matching Within a Parent Node\n\nRequires the target node to be inside another node matching the `inside` sub-rule.\n\n```yaml\ninside:\n  pattern: class $C { $$$ }\n  stopBy: end\n```\n\n### has: Matching with a Descendant Node\n\nRequires the target node to have a descendant node matching the `has` sub-rule.\n\n```yaml\nhas:\n  pattern: await $EXPR\n  stopBy: end\n```\n\n### precedes and follows: Sequential Node Matching\n\n* `precedes`: Target node must appear before a node matching the `precedes` sub-rule.\n* `follows`: Target node must appear after a node matching the `follows` sub-rule.\n\nBoth include `stopBy` but not `field`.\n\n### stopBy and field: Refining Relational Searches\n\n**stopBy**: Controls search termination for relational rules.\n\n* `\"neighbor\"` (default): Stops when immediate surrounding node doesn't match.\n* `\"end\"`: Searches to the end of the direction (root for `inside`, leaf for `has`).\n* `Rule object`: Stops when a surrounding node matches the provided rule (inclusive).\n\n**field**: Specifies a sub-node within the target node that should match the relational rule. Only for `inside` and `has`.\n\n**Best Practice**: When unsure, always use `stopBy: end` to ensure the search goes to the end of the direction.\n\n## Composite Rules\n\nComposite rules combine atomic and relational rules using logical operations.\n\n### all: Conjunction (AND) of Rules\n\nMatches a node only if all sub-rules in the list match. Guarantees order of rule matching, important for metavariables.\n\n```yaml\nall:\n  - kind: call_expression\n  - pattern: console.log($ARG)\n```\n\n### any: Disjunction (OR) of Rules\n\nMatches a node if any sub-rules in the list match.\n\n```yaml\nany:\n  - pattern: console.log($ARG)\n  - pattern: console.warn($ARG)\n  - pattern: console.error($ARG)\n```\n\n### not: Negation (NOT) of a Rule\n\nMatches a node if the single sub-rule does not match.\n\n```yaml\nnot:\n  pattern: console.log($ARG)\n```\n\n### matches: Rule Reuse and Utility Rules\n\nTakes a rule-id string, matching if the referenced utility rule matches. Enables rule reuse and recursive rules.\n\n## Metavariables\n\nMetavariables are placeholders in patterns to match dynamic content in the AST.\n\n### $VAR: Single Named Node Capture\n\nCaptures a single named node in the AST.\n\n* **Valid**: `$META`, `$META_VAR`, `$_`\n* **Invalid**: `$invalid`, `$123`, `$KEBAB-CASE`\n* **Example**: `console.log($GREETING)` matches `console.log('Hello World')`.\n* **Reuse**: `$A == $A` matches `a == a` but not `a == b`.\n\n### $$VAR: Single Unnamed Node Capture\n\nCaptures a single unnamed node (e.g., operators, punctuation).\n\n**Example**: To match the operator in `a + b`, use `$$OP`.\n\n```yaml\nrule:\n  kind: binary_expression\n  has:\n    field: operator\n    pattern: $$OP\n```\n\n### $$$MULTI_META_VARIABLE: Multi-Node Capture\n\nMatches zero or more AST nodes (non-greedy). Useful for variable numbers of arguments or statements.\n\n* **Example**: `console.log($$$)` matches `console.log()`, `console.log('hello')`, and `console.log('debug:', key, value)`.\n* **Example**: `function $FUNC($$$ARGS) { $$$ }` matches functions with varying parameters/statements.\n\n### Non-Capturing Metavariables (_VAR)\n\nMetavariables starting with an underscore (`_`) are not captured. They can match different content even if named identically, optimizing performance.\n\n* **Example**: `$_FUNC($_FUNC)` matches `test(a)` and `testFunc(1 + 1)`.\n\n### Important Considerations for Metavariable Detection\n\n* **Syntax Matching**: Only exact metavariable syntax (e.g., `$A`, `$$B`, `$$$C`) is recognized.\n* **Exclusive Content**: Metavariable text must be the only text within an AST node.\n* **Non-working**: `obj.on$EVENT`, `\"Hello $WORLD\"`, `a $OP b`, `$jq`.\n\nThe ast-grep playground is useful for debugging patterns and visualizing metavariables.\n\n## Common Patterns and Examples\n\n### Finding Functions with Specific Content\n\nFind functions that contain await expressions:\n\n```yaml\nrule:\n  kind: function_declaration\n  has:\n    pattern: await $EXPR\n    stopBy: end\n```\n\n### Finding Code Inside Specific Contexts\n\nFind console.log calls inside class methods:\n\n```yaml\nrule:\n  pattern: console.log($$$)\n  inside:\n    kind: method_definition\n    stopBy: end\n```\n\n### Combining Multiple Conditions\n\nFind async functions that use await but don't have try-catch:\n\n```yaml\nrule:\n  all:\n    - kind: function_declaration\n    - has:\n        pattern: await $EXPR\n        stopBy: end\n    - not:\n        has:\n          pattern: try { $$$ } catch ($E) { $$$ }\n          stopBy: end\n```\n\n### Matching Multiple Alternatives\n\nFind any type of console method call:\n\n```yaml\nrule:\n  any:\n    - pattern: console.log($$$)\n    - pattern: console.warn($$$)\n    - pattern: console.error($$$)\n    - pattern: console.debug($$$)\n```\n\n## Troubleshooting Tips\n\n1. **Rule doesn't match**: Use `dump_syntax_tree` to see the actual AST structure\n2. **Relational rule issues**: Ensure `stopBy: end` is set for deep searches\n3. **Wrong node kind**: Check the language's Tree-sitter grammar for correct kind names\n4. **Metavariable not working**: Ensure it's the only content in its AST node\n5. **Pattern too complex**: Break it down into simpler sub-rules using `all`\n"
  }
]