ast-grep Codemod Reference

import { parse, Lang, type SgNode } from '@ast-grep/napi';

const ast = parse(Lang.TypeScript, sourceCode);
const root: SgNode = ast.root();

// Find first match (returns null if not found)
node.find(matcher: string | number | NapiConfig): SgNode | null

// Find all matches
node.findAll(matcher: string | number | NapiConfig): SgNode[]

// Boolean checks
node.matches(pattern: string): boolean
node.inside(pattern: string): boolean
node.has(pattern: string): boolean

node.children(): SgNode[]           // Direct children
node.parent(): SgNode | null        // Parent node
node.child(nth: number): SgNode | null
node.field(name: string): SgNode | null  // Named field (e.g., 'name', 'body', 'source')
node.ancestors(): SgNode[]
node.next(): SgNode | null          // Next sibling
node.nextAll(): SgNode[]
node.prev(): SgNode | null          // Previous sibling
node.prevAll(): SgNode[]

node.kind(): string       // Tree-sitter node type (e.g., 'field_definition', 'class_body')
node.text(): string       // Full source text
node.isLeaf(): boolean
node.isNamed(): boolean
node.range(): Range       // { start: Pos, end: Pos } (0-indexed)

// After finding with a pattern containing $VAR or $$$VARS:
node.getMatch('VAR'): SgNode | null
node.getMultipleMatches('VARS'): SgNode[]

const edit = node.replace('newCode');  // Returns Edit object
const newSource = root.commitEdits([edit1, edit2]);  // Apply batch edits

node.findAll({
  rule: { /* rule object */ },
  constraints?: { /* meta-variable constraints */ },
})

// Find all class declarations
root.findAll({ rule: { kind: 'class_declaration' } })

// Common TypeScript/JavaScript kinds:
// class_declaration, class_body, field_definition, method_definition,
// import_statement, identifier, property_identifier, decorator,
// call_expression, member_expression, string, template_string

// Simple pattern
root.findAll({ rule: { pattern: 'console.log($ARG)' } })

// Pattern with context (for ambiguous syntax like class members)
root.findAll({
  rule: {
    pattern: {
      context: 'class A { $FIELD = $INIT }',
      selector: 'field_definition',
    }
  }
})

// Match identifiers starting with underscore
root.findAll({ rule: { kind: 'identifier', regex: '^_' } })

root.findAll({
  rule: {
    all: [
      { kind: 'call_expression' },
      { pattern: '$OBJ.$METHOD($$$ARGS)' },
    ]
  }
})

root.findAll({
  rule: {
    any: [
      { kind: 'field_definition' },
      { kind: 'public_field_definition' },
      { kind: 'class_field' },
    ]
  }
})

// Find all identifiers that aren't 'constructor'
root.findAll({
  rule: {
    kind: 'identifier',
    not: { regex: '^constructor$' },
  }
})

root.findAll({
  rule: { matches: 'is-ember-decorator' },
  utils: {
    'is-ember-decorator': {
      kind: 'decorator',
      has: { pattern: '@$NAME', inside: { kind: 'class_body' } },
    }
  }
})

// Find field_definition nodes that are DIRECT children of class_body
root.findAll({
  rule: {
    kind: 'field_definition',
    inside: {
      kind: 'class_body',
      stopBy: 'neighbor',  // Only check immediate parent
    }
  }
})

// Find class declarations that have a decorator
root.findAll({
  rule: {
    kind: 'class_declaration',
    has: {
      kind: 'decorator',
      stopBy: 'neighbor',  // Only check direct children
    }
  }
})

// Find nodes that follow a decorator
root.findAll({
  rule: {
    kind: 'field_definition',
    follows: { kind: 'decorator' },
  }
})

root.findAll({
  rule: {
    kind: 'decorator',
    precedes: { kind: 'method_definition' },
  }
})