ast-search-python 1.3.0 → 1.4.0

package/AGENTS.md

@@ -18,6 +18,7 @@ ast-search <query> --plugin ast-search-python [--dir <path>] [--format text|json
 | `--exclude` | `-x` | none | Glob pattern(s) to exclude from search (repeatable) |
 | `--lang` | `-l` | all | Pass `python` to restrict to Python files only |
 | `--context` | `-C` | `0` | Show N lines of context around each match (like `grep -C`) |
+| `--show-ast` | — | off | Print the tree-sitter AST subtree of each matched node below the match line |
 | `--ast` | — | off | Print Python AST for a snippet or `--file`; requires `--lang python` |
 
 **Exit codes:** `0` = matches found · `1` = no matches · `2` = error (invalid selector, etc.)

package/build/ast-print.d.ts

@@ -0,0 +1,18 @@
+export interface TSNodeFull {
+    type: string;
+    isNamed: boolean;
+    text: string;
+    children: TSNodeFull[];
+    startPosition: {
+        row: number;
+        column: number;
+    };
+    endPosition: {
+        row: number;
+        column: number;
+    };
+    fieldNameForChild(index: number): string | null;
+}
+export declare function printTSNodeText(node: TSNodeFull, out: string[], indent: string, fieldName?: string): void;
+export declare function printMatchTSNode(node: TSNodeFull): string;
+export declare function serializeTSNode(node: TSNodeFull): Record<string, unknown>;

package/build/ast-print.js

@@ -0,0 +1,51 @@
+export 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);
+        }
+    }
+}
+export function printMatchTSNode(node) {
+    const out = [];
+    printTSNodeText(node, out, "", undefined);
+    return out.join("\n");
+}
+export 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;
+}

package/build/index.d.ts

@@ -1,10 +1,14 @@
 import type { LanguageBackend, LanguageRegistry, Match } from "ast-search-js/plugin";
+import { printMatchTSNode } from "./ast-print.js";
+export { printMatchTSNode };
 export declare class PythonLanguageBackend implements LanguageBackend {
     readonly langId = "python";
     readonly name = "Python";
     readonly extensions: Set<string>;
     parse(source: string, _filePath: string): Promise<unknown>;
-    query(ast: unknown, selector: string, source: string, filePath: string): Promise<Match[]>;
+    query(ast: unknown, selector: string, source: string, filePath: string, options?: {
+        showAst?: boolean;
+    }): Promise<Match[]>;
     validateSelector(selector: string): Promise<void>;
     printAst(ast: unknown, _source: string, format: "text" | "json"): string;
 }

package/build/index.js

@@ -11,53 +11,9 @@ import { createRequire } from "module";
 import path from "path";
 import { expandShorthands } from "./shorthands.js";
 import { runTreeSitterQuery, validateTreeSitterQuery } from "./query.js";
+import { printTSNodeText, printMatchTSNode, serializeTSNode } from "./ast-print.js";
+export { printMatchTSNode };
 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* () {
@@ -90,11 +46,12 @@ export class PythonLanguageBackend {
             return parser.parse(source);
         });
     }
-    query(ast, selector, source, filePath) {
+    query(ast, selector, source, filePath, options) {
         return __awaiter(this, void 0, void 0, function* () {
+            var _a;
             const { language } = yield getRuntime();
             const expanded = expandShorthands(selector);
-            return runTreeSitterQuery(ast, expanded, source, filePath, language);
+            return runTreeSitterQuery(ast, expanded, source, filePath, language, (_a = options === null || options === void 0 ? void 0 : options.showAst) !== null && _a !== void 0 ? _a : false);
         });
     }
     validateSelector(selector) {

package/build/query.d.ts

@@ -1,3 +1,3 @@
 import type { Match } from "ast-search-js/plugin";
-export declare function runTreeSitterQuery(ast: unknown, pattern: string, source: string, filePath: string, language: unknown): Match[];
+export declare function runTreeSitterQuery(ast: unknown, pattern: string, source: string, filePath: string, language: unknown, showAst?: boolean): Match[];
 export declare function validateTreeSitterQuery(pattern: string, language: unknown): void;

package/build/query.js

@@ -1,3 +1,4 @@
+import { printMatchTSNode } from "./ast-print.js";
 function assertValidPattern(pattern) {
     const trimmed = pattern.trim();
     // A valid tree-sitter pattern must start with "(" (S-expression) or contain
@@ -7,7 +8,7 @@ function assertValidPattern(pattern) {
             `Use a shorthand (e.g. "fn", "call") or write a full S-expression (e.g. "(function_definition) @fn").`);
     }
 }
-export function runTreeSitterQuery(ast, pattern, source, filePath, language) {
+export function runTreeSitterQuery(ast, pattern, source, filePath, language, showAst = false) {
     var _a;
     assertValidPattern(pattern);
     const tree = ast;
@@ -40,7 +41,7 @@ export function runTreeSitterQuery(ast, pattern, source, filePath, language) {
                 captureMap[cap.name] = source.slice(cap.node.startIndex, cap.node.endIndex);
             }
         }
-        results.push(Object.assign(Object.assign({ file: filePath, line: anchor.node.startPosition.row + 1, col: anchor.node.startPosition.column, start: anchor.node.startIndex, end: anchor.node.endIndex, source: firstLine }, (text !== firstLine ? { source_full: text } : {})), (Object.keys(captureMap).length > 0 ? { captures: captureMap } : {})));
+        results.push(Object.assign(Object.assign(Object.assign({ file: filePath, line: anchor.node.startPosition.row + 1, col: anchor.node.startPosition.column, start: anchor.node.startIndex, end: anchor.node.endIndex, source: firstLine }, (text !== firstLine ? { source_full: text } : {})), (showAst ? { astSubtree: printMatchTSNode(anchor.node) } : {})), (Object.keys(captureMap).length > 0 ? { captures: captureMap } : {})));
     }
     return results;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-search-python",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Python language plugin for ast-search",
   "type": "module",
   "main": "./build/index.js",