ast-grep-setup

ast-grep Setup Skill

Set up ast-grep with common TypeScript rules for detecting anti-patterns, enforcing best practices, and preventing bugs.

When to Use

• Adding structural linting to a TypeScript codebase
• Banning legacy patterns after migration
• Implementing ratchet gates (block new violations while grandfathering existing ones)
• Enforcing architecture boundaries
• Preventing common TypeScript/JavaScript bugs

CRITICAL: Read YAML Structure First

Agents: Before writing any rules, read the YAML Structure Rules section.

The most common mistakes are:

1. Putting constraints inside rule: (must be at top level)
2. Duplicate YAML keys like multiple not: blocks
3. Not wrapping multiple conditions in all: or any:

Use the validation script to catch these before running ast-grep:

python3 scripts/validate-rule.py rules/*.yml

Quick Start

1. Initialize ast-grep Configuration

# Create sgconfig.yml in project root
mkdir -p rules/ast-grep/rules rules/ast-grep/rule-tests
cat > rules/ast-grep/sgconfig.yml << 'EOF'
ruleDirs:
  - rules
testConfigs:
  - testDir: rule-tests
    allowedFixers: []
EOF

2. Add Rules for Common TypeScript Pain Points

See the Rule Library below for ready-to-use rules.

3. Run and Test

# Scan the codebase
cd rules/ast-grep && ast-grep scan

# Run rule tests
cd rules/ast-grep && ast-grep test

# Update test snapshots after rule changes
cd rules/ast-grep && ast-grep test -U

Rule Library

Type Safety Rules

no-implicit-any-params

Prevents function parameters without explicit types (implicit any).

# rules/no-implicit-any-params.yml
id: no-implicit-any-params
language: TypeScript
severity: warning
message: "Parameter '$PARAM' lacks explicit type annotation"
files:
  - src/**/*.ts
  - src/**/*.tsx
rule:
  pattern: function $FUNC($PARAM) { $$$BODY }
constraints:
  PARAM:
    not:
      has:
        kind: type_annotation