tree-sitter CLI

tree-sitter CLI로 AST 덤프, S-expression 쿼리, 태그 추출을 수행합니다.

핵심 철학:

• ast-grep 우선: 검색/대체는 ast-grep, tree-sitter는 분석/이해 목적

• AST 시각화: 코드 구조를 트리로 확인하여 정확한 노드 타입 파악

• S-expression 쿼리: predicates로 정밀한 구조적 검색 (neovim query와 동일 문법)

• 태그 추출: 정의/참조를 구조적으로 추출 (ctags 대체)

Prerequisites

tree-sitter dump-languages # 사용 가능한 파서 목록

"not configured" 경고 시 → 워크플로우 1 실행.

Instructions

워크플로우 1: Setup (on-demand 파서 설치)

dump-languages 출력에 언어가 없으면 grammar을 설치한다.

초기 설정 (1회)

tree-sitter init-config # parser-directories: ["~/.local/share/tree-sitter/grammars"]

언어별 설치 (필요 시)

cd ~/.local/share/tree-sitter/grammars git clone --depth 1 https://github.com/tree-sitter/tree-sitter-<언어>

일부 언어는 tree-sitter-grammars org: https://github.com/tree-sitter-grammars/tree-sitter-<언어>

워크플로우 2: Parse (AST 덤프)

쿼리 작성 전 노드 타입 파악에 필수.

tree-sitter parse --no-ranges file.py # 간결한 AST tree-sitter parse --cst file.py # 정렬된 트리 tree-sitter parse --xml file.py # XML 출력 tree-sitter parse --scope source.python file.txt # 언어 지정

출력 예시:

(function_definition name: (identifier) parameters: (parameters (identifier) (identifier)) body: (block (return_statement)))

노드 타입(function_definition )과 필드명(name: , body: )을 확인하여 query 패턴 작성에 사용.

워크플로우 3: Query (S-expression 쿼리)

S-expression 패턴으로 코드를 검색한다. .scm 파일에 작성 후 실행.

;; queries/find-functions.scm (function_definition name: (identifier) @func.name)

tree-sitter query queries/find-functions.scm file.py tree-sitter query queries/find-functions.scm src/ # 디렉토리 전체 tree-sitter query --captures queries/q.scm file.py # 캡처 순서 출력 tree-sitter query --row-range 10-50 queries/q.scm file.py # 행 범위 제한

S-expression 쿼리 문법은 resources/01-query-syntax.md 참조.

워크플로우 4: Tags (태그 추출)

코드에서 정의(definition)와 참조(reference)를 추출한다.

tree-sitter tags file.py tree-sitter tags src/ # 디렉토리 전체

중요 원칙

• Parse 먼저: 쿼리 작성 전 반드시 parse 로 노드 타입 확인

• 쿼리 파일 사용: .scm 파일 작성 (재사용, 가독성)

• 언어별 노드 차이: 같은 개념이라도 언어마다 노드 타입이 다름

Examples

AST 구조 파악

User: "이 Python 파일의 AST 구조 보여줘" → tree-sitter parse --no-ranges file.py → 노드 타입과 필드 구조 보고

복잡한 쿼리

User: "데코레이터가 붙은 async 함수만 찾아줘" → parse로 노드 타입 확인 → .scm 쿼리 작성 → tree-sitter query query.scm src/

References

• S-expression 쿼리 문법: resources/01-query-syntax.md

• 공식 문서: https://tree-sitter.github.io/tree-sitter/

• Grammar 목록: https://github.com/tree-sitter

• 설정 파일: ~/.config/tree-sitter/config.json

• Grammar 경로: ~/.local/share/tree-sitter/grammars/