ast-search-python 1.0.6 → 1.1.0

package/AGENTS.md

@@ -71,6 +71,34 @@ Python queries use [tree-sitter](https://tree-sitter.github.io/tree-sitter/) S-e
 
 Output formats (`text`, `json`, `files`) work identically to the core tool. See [ast-search AGENTS](../../AGENTS.md#output-formats) for details.
 
+### Captures
+
+Named captures (`@name` in your pattern, excluding `@_`) are included in the `captures` field of each match. The capture key is the name without the `@`.
+
+Text output appends captures after the source line:
+
+```
+src/app.py:5:0: logging.info("user logged in") | fn=logging.info msg="user logged in" call=logging.info("user logged in")
+```
+
+JSON output includes a `captures` field when captures are present:
+
+```json
+{
+  "file": "src/app.py",
+  "line": 5,
+  "col": 0,
+  "source": "logging.info(\"user logged in\")",
+  "captures": {
+    "fn": "logging.info",
+    "msg": "\"user logged in\"",
+    "call": "logging.info(\"user logged in\")"
+  }
+}
+```
+
+All captures from a single pattern application are grouped onto one match — `@fn`, `@msg`, and `@call` from the same query match produce one result, not three.
+
 ---
 
 ## Python Refactoring Patterns
@@ -96,6 +124,18 @@ ast-search 'from' --plugin ast-search-python
 ast-search '(call function: (identifier) @n (#eq? @n "my_func")) @c' --plugin ast-search-python
 ```
 
+### Find calls to any logging method and capture the method name and string argument
+```bash
+ast-search '(call function: [(identifier)(attribute)] @fn (#match? @fn "^(log|info|warn|error|debug)") arguments: (argument_list (string) @msg)) @call' --plugin ast-search-python
+# output: ... | fn=logging.info msg="user logged in" call=logging.info("user logged in")
+```
+
+### Find functions whose name matches a regex
+```bash
+ast-search '(function_definition name: (identifier) @name (#match? @name "^handle_")) @fn' --plugin ast-search-python
+# output: ... | name=handle_request fn=def handle_request(...):
+```
+
 ### Find all decorators
 ```bash
 ast-search 'decorator' --plugin ast-search-python
@@ -164,4 +204,4 @@ const matches = await searchRepo('fn', './src');
 - **Unparseable files are silently skipped.** Syntax errors in source files do not abort the search.
 - **`node_modules` is always excluded**, as are files/directories whose names start with `.`.
 - **Verify the AST structure before writing a query.** Python attribute chains like `self.client.send()` nest deeply — `self` is not the direct `object:` of the outer call; `self.client` is. If a predicate query returns no results, first remove the predicate and confirm the base pattern matches what you expect.
-- **`captures()` returns every named capture, not just the outermost.** A query like `(function_definition name: (identifier) @n) @fn` produces two matches per function: one for `@fn` (the whole definition) and one for `@n` (the name identifier). Filter by `source` or capture name if you only want one.
+- **All captures from one pattern match are grouped on a single result.** A query like `(function_definition name: (identifier) @n) @fn` produces one match per function, with both `@fn` and `@n` in the `captures` field. The anchor (location) is the first non-underscore capture — `@fn` in this case.

package/README.md

@@ -1,5 +1,7 @@
 # ast-search-python
 
+[![npm](https://img.shields.io/npm/v/ast-search-python?label=ast-search-python)](https://www.npmjs.com/package/ast-search-python)
+
 Python language plugin for [ast-search-js](../ast-search-js/README.md). Adds `.py` / `.pyw` file support using [tree-sitter](https://tree-sitter.github.io/tree-sitter/) S-expression queries.
 
 ## Table of Contents
@@ -65,11 +67,22 @@ ast-search '(class_definition) @cls' --plugin ast-search-python
 # Find all calls to a specific function by name
 ast-search '(call function: (identifier) @n (#eq? @n "my_func")) @c' --plugin ast-search-python
 
+# Find calls to any function matching a regex (using #match? predicate)
+ast-search '(call function: (identifier) @n (#match? @n "^(get|post|put|delete)_")) @c' --plugin ast-search-python
+
 # Restrict to only Python files in a mixed-language repo
 ast-search 'fn' --lang python --plugin ast-search-python
 ```
 
-Raw S-expression queries must include at least one `@capture_name` — tree-sitter's `captures()` requires it to return results. Shorthands include `@_` automatically.
+Raw S-expression queries must include at least one `@capture_name` — tree-sitter requires it to return results. Shorthands include `@_` automatically.
+
+Named captures (`@name`, excluding `@_`) appear in the `captures` field of each match. All captures from a single pattern application are grouped on one result. In text output they appear after ` | `; in JSON they're in a `captures` object.
+
+```bash
+# Find logging calls — capture the method name and string argument
+ast-search '(call function: [(identifier)(attribute)] @fn (#match? @fn "^(log|info|warn|error)") arguments: (argument_list (string) @msg)) @call' --plugin ast-search-python
+# text output: src/app.py:5:0: logging.info("msg") | fn=logging.info msg="msg" call=logging.info("msg")
+```
 
 ### Shorthands
 

package/build/index.d.ts

@@ -6,6 +6,7 @@ export declare class PythonLanguageBackend implements LanguageBackend {
     parse(source: string, _filePath: string): Promise<unknown>;
     query(ast: unknown, selector: string, source: string, filePath: string): Promise<Match[]>;
     validateSelector(selector: string): Promise<void>;
+    printAst(ast: unknown, _source: string, format: "text" | "json"): string;
 }
 /**
  * Register the Python backend with an ast-search LanguageRegistry.

package/build/index.js

@@ -12,6 +12,52 @@ import path from "path";
 import { expandShorthands } from "./shorthands.js";
 import { runTreeSitterQuery, validateTreeSitterQuery } from "./query.js";
 const _require = createRequire(import.meta.url);
+function printTSNodeText(node, out, indent, fieldName) {
+    var _a;
+    const label = fieldName ? `${fieldName}: ${node.type}` : node.type;
+    const namedChildren = node.children.filter((c) => c.isNamed);
+    if (namedChildren.length === 0) {
+        const text = node.text.replace(/\n/g, "\\n");
+        const suffix = text.length <= 60 ? ` [text="${text}"]` : "";
+        out.push(`${indent}${label}${suffix}`);
+    }
+    else {
+        out.push(`${indent}${label}`);
+        for (let i = 0; i < node.children.length; i++) {
+            const child = node.children[i];
+            if (!child.isNamed)
+                continue;
+            const childField = (_a = node.fieldNameForChild(i)) !== null && _a !== void 0 ? _a : undefined;
+            printTSNodeText(child, out, indent + "  ", childField);
+        }
+    }
+}
+function serializeTSNode(node) {
+    const result = {
+        type: node.type,
+        isNamed: node.isNamed,
+        start: node.startPosition,
+        end: node.endPosition,
+    };
+    const namedChildren = [];
+    for (let i = 0; i < node.children.length; i++) {
+        const child = node.children[i];
+        if (!child.isNamed)
+            continue;
+        const fieldName = node.fieldNameForChild(i);
+        const serialized = serializeTSNode(child);
+        if (fieldName)
+            serialized.field = fieldName;
+        namedChildren.push(serialized);
+    }
+    if (namedChildren.length > 0) {
+        result.children = namedChildren;
+    }
+    else {
+        result.text = node.text;
+    }
+    return result;
+}
 let _runtimePromise = null;
 function getRuntime() {
     return __awaiter(this, void 0, void 0, function* () {
@@ -57,6 +103,15 @@ export class PythonLanguageBackend {
             validateTreeSitterQuery(expandShorthands(selector), language);
         });
     }
+    printAst(ast, _source, format) {
+        const tree = ast;
+        if (format === "json") {
+            return JSON.stringify(serializeTSNode(tree.rootNode), null, 2);
+        }
+        const out = [];
+        printTSNodeText(tree.rootNode, out, "", undefined);
+        return out.join("\n");
+    }
 }
 /**
  * Register the Python backend with an ast-search LanguageRegistry.

package/build/query.js

@@ -8,32 +8,39 @@ function assertValidPattern(pattern) {
     }
 }
 export function runTreeSitterQuery(ast, pattern, source, filePath, language) {
+    var _a;
     assertValidPattern(pattern);
     const tree = ast;
-    // captures() only returns nodes that have a capture name (@something).
+    // matches() only returns nodes that have a capture name (@something).
     // If the user wrote a bare S-expression like (function_definition), add @_
     // so results are returned.
     const queryPattern = pattern.includes("@") ? pattern : `${pattern} @_`;
     const q = language.query(queryPattern);
-    const captures = q.captures(tree.rootNode);
-    // web-tree-sitter may return different JS objects for the same node when
-    // multiple capture names match it, so deduplicate by position instead of identity.
+    // Use matches() instead of captures() so all captures from one pattern
+    // application are grouped together — enabling multi-node capture output.
     const seen = new Set();
     const results = [];
-    for (const capture of captures) {
-        const node = capture.node;
-        const key = `${node.startIndex}:${node.endIndex}`;
+    for (const match of q.matches(tree.rootNode)) {
+        // Anchor on the first non-underscore capture (the primary match location).
+        // @_ is the auto-appended anonymous marker; user captures like @fn, @msg
+        // are the meaningful ones and also serve as the anchor.
+        const anchor = (_a = match.captures.find((c) => !c.name.startsWith("_"))) !== null && _a !== void 0 ? _a : match.captures[0];
+        if (!anchor)
+            continue;
+        const key = `${anchor.node.startIndex}:${anchor.node.endIndex}`;
         if (seen.has(key))
             continue;
         seen.add(key);
-        const text = source.slice(node.startIndex, node.endIndex);
+        const text = source.slice(anchor.node.startIndex, anchor.node.endIndex);
         const firstLine = text.split("\n")[0].trimEnd();
-        results.push({
-            file: filePath,
-            line: node.startPosition.row + 1, // 1-indexed to match JS backend
-            col: node.startPosition.column,
-            source: firstLine,
-        });
+        // Collect all named captures except the anonymous @_ marker.
+        const captureMap = {};
+        for (const cap of match.captures) {
+            if (!cap.name.startsWith("_")) {
+                captureMap[cap.name] = source.slice(cap.node.startIndex, cap.node.endIndex);
+            }
+        }
+        results.push(Object.assign({ file: filePath, line: anchor.node.startPosition.row + 1, col: anchor.node.startPosition.column, source: firstLine }, (Object.keys(captureMap).length > 0 ? { captures: captureMap } : {})));
     }
     return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-search-python",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Python language plugin for ast-search",
   "type": "module",
   "main": "./build/index.js",
@@ -16,7 +16,7 @@
     "prepublishOnly": "tsc"
   },
   "author": "shiplet",
-  "license": "ISC",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/willey-shiplet/ast-search.git",
@@ -26,7 +26,8 @@
     "build/*.js",
     "build/*.d.ts",
     "README.md",
-    "AGENTS.md"
+    "AGENTS.md",
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public",
@@ -40,12 +41,11 @@
     "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.12.7",
-    "ast-search-js": "1.0.2",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.2",
     "typescript": "^5.4.5"
   },
   "peerDependencies": {
-    "ast-search-js": "1.0.2"
+    "ast-search-js": "^1.0.0"
   }
 }