|
| 1 | +--- |
| 2 | +applyTo: "website/catalog/**/*.md" |
| 3 | +--- |
| 4 | + |
| 5 | +# Catalog Instructions |
| 6 | + |
| 7 | +These instructions apply specifically to markdown files in the `website/catalog/` directory and help with creating and managing ast-grep rule examples. |
| 8 | + |
| 9 | +## Rule Creation Workflow |
| 10 | + |
| 11 | +When creating or modifying catalog rules, follow this structured approach: |
| 12 | + |
| 13 | +### 1. Determine Example Language |
| 14 | +- Identify the programming language for the rule example |
| 15 | +- Ensure the language folder exists in `website/catalog/` (e.g., `typescript/`, `python/`, `rust/`) |
| 16 | +- If the language folder doesn't exist, create it with an `index.md` file |
| 17 | + |
| 18 | +### 2. Determine Rule Format |
| 19 | +Choose between two formats: |
| 20 | +- **Pattern**: Use ast-grep's pattern syntax for simple rules |
| 21 | +- **YAML**: Use YAML configuration for complex rules with multiple conditions |
| 22 | + |
| 23 | +### 3. Use Rule Template |
| 24 | +- Base new rules on `website/catalog/rule-template.md` |
| 25 | +- Include all required sections: |
| 26 | + - Title with optional `<Badge type="tip" text="Has Fix" />` if rule has a fix |
| 27 | + - Playground link |
| 28 | + - Description |
| 29 | + - Pattern OR YAML section (delete unused section) |
| 30 | + - Example code with highlighted lines |
| 31 | + - Diff section (if rule has a fix) |
| 32 | + - Contributed by section |
| 33 | + |
| 34 | +### 4. Include Rule in Language Index |
| 35 | +- Add the new rule to the language folder's `index.md` using the include syntax: |
| 36 | + ```markdown |
| 37 | + <!--@include: ./rule-filename.md--> |
| 38 | + ``` |
| 39 | +- Place includes in appropriate order within the index file |
| 40 | + |
| 41 | +### 5. Required Components |
| 42 | +Ensure every rule has: |
| 43 | +- **Example code**: Realistic code that demonstrates the pattern |
| 44 | +- **Rule/Pattern**: Either a pattern or YAML configuration |
| 45 | +- **Playground link**: URL to test the rule in the ast-grep playground |
| 46 | +- **Clear description**: Concise explanation of what the rule does and why it's useful |
| 47 | + |
| 48 | +### 6. Content Guidelines |
| 49 | +- **Descriptions**: Keep them clear, short, and explain the purpose |
| 50 | +- **Examples**: Use realistic code that developers would encounter |
| 51 | +- **Highlighting**: Use `{lineNum}` syntax to highlight matched lines in examples |
| 52 | +- **Diff annotations**: Use `// [!code --]` and `// [!code ++]` for before/after code |
| 53 | +- **Badges**: Add `<Badge type="tip" text="Has Fix" />` to rule titles that include fixes |
| 54 | + |
| 55 | +### 7. Fix Rules |
| 56 | +If the rule includes a fix/rewrite capability: |
| 57 | +- Add the "Has Fix" badge to the title |
| 58 | +- Include a "Diff" section showing before/after code |
| 59 | +- Ensure the fix is demonstrated in the playground link |
| 60 | + |
| 61 | +## File Naming |
| 62 | +- Use kebab-case for rule filenames (e.g., `no-await-in-promise-all.md`) |
| 63 | +- Make filenames descriptive of the rule's purpose |
| 64 | +- Keep filenames concise but clear |
| 65 | + |
| 66 | +## Language-Specific Notes |
| 67 | +- **TypeScript vs TSX**: These are different parsers - TSX allows JSX elements |
| 68 | +- **Include syntax**: Always use `<!--@include: ./filename.md-->` format |
| 69 | +- **Language folders**: Each language should have its own folder with an `index.md` |
| 70 | + |
| 71 | +## Quality Standards |
| 72 | +- Test rules in the playground before submitting |
| 73 | +- Ensure examples are syntactically correct |
| 74 | +- Verify playground links work correctly |
| 75 | +- Use consistent formatting across all rules |
| 76 | +- Provide proper attribution in "Contributed by" section |
| 77 | + |
| 78 | +## Example Structure |
| 79 | +```markdown |
| 80 | +## Rule Name <Badge type="tip" text="Has Fix" /> |
| 81 | + |
| 82 | +* [Playground Link](/playground.html#...) |
| 83 | + |
| 84 | +### Description |
| 85 | +Clear explanation of what the rule does and why it's useful. |
| 86 | + |
| 87 | +### YAML |
| 88 | +```yaml |
| 89 | +id: rule-id |
| 90 | +language: typescript |
| 91 | +rule: |
| 92 | + pattern: pattern here |
| 93 | +fix: fix pattern |
| 94 | +``` |
| 95 | + |
| 96 | +### Example |
| 97 | +```ts {1,3} |
| 98 | +// Example code with highlighted lines |
| 99 | +``` |
| 100 | + |
| 101 | +### Diff |
| 102 | +```ts |
| 103 | +old code // [!code --] |
| 104 | +new code // [!code ++] |
| 105 | +``` |
| 106 | + |
| 107 | +### Contributed by |
| 108 | +[Author Name](https://link) |
| 109 | +``` |
0 commit comments