--- title: ast_grep | CodeWeaver Docs description: API reference for codeweaver.semantic.ast_grep url: "https://docs.knitli.com/api/semantic/ast_grep" type: static generatedAt: "2026-04-17T17:21:09.537Z" --- # ast_grep [Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F.%20I%20want%20to%20ask%20questions%20about%20it.)[View in Markdown](/codeweaver/api/semantic/ast_grep.md) [Share on LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F)[Share on X](https://x.com/intent/tweet?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F&text=ast_grep)[Share on Threads](https://threads.net/intent/post?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F&text=ast_grep)[Share on Bluesky](https://bsky.app/intent/compose?text=ast_grep%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F)[Share on Facebook](https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F)[Share on Reddit](https://reddit.com/submit?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F&title=ast_grep)[Share on Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F&t=ast_grep)[Share on Email](mailto:?subject=ast_grep&body=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F)[Share on WhatsApp](https://wa.me/?text=ast_grep%20https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F)[Share on Telegram](https://t.me/share/url?url=https%3A%2F%2Fdocs.knitli.com%2Fcodeweaver%2Fapi%2Fsemantic%2Fast_grep%2F&text=ast_grep) # `codeweaver.semantic.ast_grep` [Section titled “codeweaver.semantic.ast_grep”](#codeweaversemanticast_grep) Custom wrappers around ast-grep’s core types to add functionality and serialization. Like the rest of CodeWeaver, we use our specific vocabulary for concepts to make roles and relationships more clear. See [codeweaver.semantic.grammar_things] for more details. ## The Short(er) Version [Section titled “The Short(er) Version”](#the-shorter-version) ### Translation Table [Section titled “Translation Table”](#translation-table) | Tree-sitter Term | CodeWeaver Term | Notes | | --- | --- | --- | | Abstract type (with subtypes) | Category | Doesn’t appear in parse trees | | Named/unnamed node | Thing | Concrete parse tree node | | Node with no fields | Token | Leaf node | | Node with fields/children | Composite Thing | Non-leaf node | | Field | Direct Connection | Has semantic Role | | Child | Positional Connection | Ordered, no Role | | Field name | Role | Semantic function | | Extra | `can_be_anywhere` | Can be anywhere in the AST | | `named` attribute | `is_explicit_rule` | Has named grammar rule | | `multiple` attribute | `allows_multiple` | Upper cardinality bound | | `required` attribute | `requires_presence` | Lower cardinality bound | | ’root’ attribute | `is_file` | It’s the file. | ### What These Things Are [Section titled “What These Things Are”](#what-these-things-are) - **Thing**: A concrete node in the parse tree. Everything in the tree is a Thing. Things can be Token things or CompositeThings. - **Token**: A Token is a solitary thing — in tree-sitter terms, it is a leaf node with no fields or children. Tokens are the “words” of the programming language, like keywords, operators, and identifiers. - **CompositeThing**: A CompositeThing is a thing that has fields and/or children (direct or positional connections). CompositeThings are the “phrases” of the programming language, like expressions, statements, and declarations. CompositeThings are always made up of other Things (Tokens or CompositeThings). - **Category**: A Category is an abstract type that can have multiple subtypes. Categories do not appear in the parse tree, but they are used to group related Things together. For example, the Category “expression” might include the subtypes “binary_expression”, “call_expression”, and “literal”. While they don’t appear in the parse tree, they can be used in search patterns to match any of their subtypes. Since there aren’t very many categories, they can be an easy way to write patterns that target specific functional parts of the code. - **Direct Connection**: A Direct Connection is a named field in a CompositeThing that has a specific semantic Role. For example, in a function declaration, the “name” field is a Direct Connection with the Role “function_name”. Direct Connections are not ordered, and they can be optional or required (the `constraints` attribute provides this information, which is based on the `allows_multiple` and `requires_presence` attributes). A CompositeThing can have multiple Direct Connections, and each connection can be to more than one target (its `target_things` attribute), and they can be of different types (Token, CompositeThing, and even Category), but it must have at least one *possible* Direct Connection. Depending on constraints, a CompositeThing may appear in the AST without an connections of any kind. - **Positional Connection**: A Positional Connection is a child of a CompositeThing that does not have a specific semantic Role. Positional Connections are ordered, and they can be optional or required (the `constraints` attribute provides this information, which is based on the `allows_multiple` and `requires_presence` attributes). Because of their ordered nature, a CompositeThing will either have 1 or none of a PositionalConnections type. A PositionalConnections may reference multiple types (its `target_things` attribute), which is ordered. - **Role**: A Role is the semantic function of a Direct Connection, like ‘name’ for a function’s name, or ‘condition’ for an if statement’s condition. - **Meta Variable**: A Meta Variable is a special syntax used in search patterns to capture nodes in the AST. Meta Variables are prefixed with a `$` symbol, and they can be named or unnamed. Named Meta Variables are used to capture specific nodes, while unnamed Meta Variables are used to capture any node. There are also Multi-Capture Meta Variables that can capture multiple nodes. See [the ast-grep documentation ↗](https://ast-grep.github.io/docs/patterns/metavars/) for more details. - **Rules** - Ast-grep provides a rich rule system for defining more complex search patterns than what you can do with just meta variables. See [the ast-grep documentation ↗](https://ast-grep.github.io/guide/rule-config.html) for more details. ## Connections and Navigation [Section titled “Connections and Navigation”](#connections-and-navigation) **All connections defined in the grammar are optional.** Sort of. For direct connections, about 36% of them require exactly one target with only one possible target type, so if one of those is present, then so will its target (and probably vice versa). Only about 8% of positional connections require exactly one target with only one possible target type, so positional connections are much more likely to be absent. But in general, you should always code defensively and assume that any connection may be absent. A common way to move (“traverse”) through the AST is to start at the root node (the FileThing) and then move down through its children, and then their children, and so on. You can also move up the tree to a node’s parent, or sideways to its siblings. Each AstThing has methods for moving in these directions, as well as properties for accessing its connections. ## Class: `AstThing` [Section titled “Class: AstThing”](#class-astthing) Wrapper for `SgNode` to make it serializable and give it extra functionality. AstThing represents a node in the AST, which can be a Token (leaf node) or a CompositeThing (non-leaf node). It provides methods for traversing the AST, searching for nodes, and classifying nodes semantically. Each AstThing is associated with a specific programming language, which helps in semantic classification and importance scoring. Other notable improvements over raw `SgNode`: - Serialization support via Pydantic - Unique identifiers for nodes (`thing_id` and `parent_thing_id`) - Cached properties for potentially expensive operations (like `text`, `kind`, `range`, etc.) - Integration with CodeWeaver’s semantic classification and scoring system - Each Thing can determine its semantic classification and importance score, providing richer context for search and analysis. - Allows prioritization of Things based on their semantic importance, the goal of the search, and the task at hand. - Clearer terminology aligned with CodeWeaver’s vocabulary (e.g., Thing, Token, CompositeThing) - Stronger typing and generics for better developer experience - Each AstThing holds references to its “pure” grammar Thing, which provides information about *what it can be* in the AST, not just what we see in this particular instance. ### Method: `ancestors` [Section titled “Method: ancestors”](#method-ancestors) ** ``` ancestors() ``` Get the ancestors of the node. ### Method: `child` [Section titled “Method: child”](#method-child) ** ``` child() ``` Get the nth child of the node. ### Method: `commit_edits` [Section titled “Method: commit_edits”](#method-commit_edits) ** ``` commit_edits() ``` Commit a list of edits to the source code. ### Method: `find` [Section titled “Method: find”](#method-find) ** ``` find() ``` Find a node using a config. ### Method: `find_all` [Section titled “Method: find_all”](#method-find_all) ** ``` find_all() ``` Find all nodes using a config. ### Method: `follows` [Section titled “Method: follows”](#method-follows) ** ``` follows() ``` Check if the node follows the given rule. ### Method: `from_sg_node` [Section titled “Method: from_sg_node”](#method-from_sg_node) ** ``` from_sg_node() ``` Create an AstThing from an ast-grep `SgNode`. ### Method: `get_file` [Section titled “Method: get_file”](#method-get_file) ** ``` get_file() ``` Get the root of the node. ### Method: `get_match` [Section titled “Method: get_match”](#method-get_match) ** ``` get_match() ``` Get the match for the given meta variable. ### Method: `get_multiple_matches` [Section titled “Method: get_multiple_matches”](#method-get_multiple_matches) ** ``` get_multiple_matches() ``` Get the matches for the given meta variable. ### Method: `get_root` [Section titled “Method: get_root”](#method-get_root) ** ``` get_root() ``` Get the root of the node. Alias for `get_file`. ### Method: `get_transformed` [Section titled “Method: get_transformed”](#method-get_transformed) ** ``` get_transformed() ``` Get the transformed text for the given meta variable. ### Method: `has` [Section titled “Method: has”](#method-has) ** ``` has() ``` Check if the node has the given rule. ### Method: `importance_for_context` [Section titled “Method: importance_for_context”](#method-importance_for_context) ** ``` importance_for_context() ``` Calculate the importance score for this node for a specific context. ### Method: `importance_for_task` [Section titled “Method: importance_for_task”](#method-importance_for_task) ** ``` importance_for_task() ``` Calculate the importance score for this node for a specific task. ### Method: `inside` [Section titled “Method: inside”](#method-inside) ** ``` inside() ``` Check if the node is inside the given rule. ### Method: `matches` [Section titled “Method: matches”](#method-matches) ** ``` matches() ``` Check if the node matches the given rule. ### Method: `next` [Section titled “Method: next”](#method-next) ** ``` next() ``` Get the next sibling of the thing. ### Method: `next_all` [Section titled “Method: next_all”](#method-next_all) ** ``` next_all() ``` Get all next siblings of the node. ### Method: `precedes` [Section titled “Method: precedes”](#method-precedes) ** ``` precedes() ``` Check if the node precedes the given rule. ### Method: `prev` [Section titled “Method: prev”](#method-prev) ** ``` prev() ``` Get the previous sibling of the node. ### Method: `prev_all` [Section titled “Method: prev_all”](#method-prev_all) ** ``` prev_all() ``` Get all previous siblings of the node. ### Method: `replace` [Section titled “Method: replace”](#method-replace) ** ``` replace() ``` Replace the text of the node with new_text. ### Method: `serialize_for_cli` [Section titled “Method: serialize_for_cli”](#method-serialize_for_cli) ** ``` serialize_for_cli() ``` Serialize the AstThing for CLI output. ### Method: `serialize_for_embedding` [Section titled “Method: serialize_for_embedding”](#method-serialize_for_embedding) ** ``` serialize_for_embedding() ``` Serialize the AstThing for embedding purposes. ### Method: `serialize_special_fields` [Section titled “Method: serialize_special_fields”](#method-serialize_special_fields) ** ``` serialize_special_fields() ``` Serialize the special fields of the AstThing. ## Class: `FileThing` [Section titled “Class: FileThing”](#class-filething) Wrapper for SgRoot to make it serializable and provide additional functionality. `FileThing` is the root node of an AST, representing the entire source file. It provides access to the filename and the root node of the AST. We call it a FileThing to make its role as the start of a file’s syntax tree more explicit (because… root… of what?). It is a file, and a Thing. ### Method: `from_file` [Section titled “Method: from_file”](#method-from_file) ** ``` from_file() ``` Create a FileThing from a file. ### Method: `from_sg_node` [Section titled “Method: from_sg_node”](#method-from_sg_node-1) ** ``` from_sg_node() ``` Create a FileThing from an ast-grep SgNode. ### Method: `from_sg_root` [Section titled “Method: from_sg_root”](#method-from_sg_root) ** ``` from_sg_root() ``` Create a FileThing from an ast-grep SgRoot. ### Method: `serialize_for_embedding` [Section titled “Method: serialize_for_embedding”](#method-serialize_for_embedding-1) ** ``` serialize_for_embedding() ``` Serialize the FileThing for embedding purposes. ## Class: `MetaVar` [Section titled “Class: MetaVar”](#class-metavar) Represents a meta variable in the AST. ### Method: `to_metavar` [Section titled “Method: to_metavar”](#method-to_metavar) ** ``` to_metavar() ``` Return the pattern representation of the meta variable. ## Class: `Position` [Section titled “Class: Position”](#class-position) Represents a `Pos` from ast-grep with pydantic validation. The position of the node in the source code. ### Method: `from_pos` [Section titled “Method: from_pos”](#method-from_pos) ** ``` from_pos() ``` Create a Position from an ast-grep Pos. ### Method: `to_pos` [Section titled “Method: to_pos”](#method-to_pos) ** ``` to_pos() ``` Convert a Position to an ast-grep Pos. ## Class: `Range` [Section titled “Class: Range”](#class-range) Represents a `Range` from ast-grep with pydantic validation. The range of the node in the source code. ### Method: `from_sg_range` [Section titled “Method: from_sg_range”](#method-from_sg_range) ** ``` from_sg_range() ``` Create a Range from an ast-grep range. ### Method: `to_sg_range` [Section titled “Method: to_sg_range”](#method-to_sg_range) ** ``` to_sg_range() ``` Convert a Range to an ast-grep Range. ## Class: `Strictness` [Section titled “Class: Strictness”](#class-strictness) Represents the strictness level for code analysis. ## Function: `rebuild_models_for_tests` [Section titled “Function: rebuild_models_for_tests”](#function-rebuild_models_for_tests) ** ``` rebuild_models_for_tests() ``` Rebuild all models with AstThing forward references for test scenarios. This should be called at the beginning of test modules that instantiate CodeChunk, ChunkEmbeddings, or other models that depend on AstThing/SemanticMetadata. Returns: bool: True if all models were rebuilt successfully, False otherwise