ast-search-python 1.2.0 → 1.4.0

package/AGENTS.md

@@ -15,8 +15,10 @@ ast-search <query> --plugin ast-search-python [--dir <path>] [--format text|json
 | `--plugin` | `-p` | — | Must be `ast-search-python` to activate Python support |
 | `--dir` | `-d` | `cwd` | Root directory to search |
 | `--format` | `-f` | `text` | Output format: `text`, `json`, `files`, or `count` |
+| `--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.)
@@ -83,13 +85,15 @@ 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 output includes `start`/`end` byte offsets and `source_full` (for multi-line matches) in addition to `captures`:
 
 ```json
 {
   "file": "src/app.py",
   "line": 5,
   "col": 0,
+  "start": 87,
+  "end": 116,
   "source": "logging.info(\"user logged in\")",
   "captures": {
     "fn": "logging.info",
@@ -99,6 +103,11 @@ JSON output includes a `captures` field when captures are present:
 }
 ```
 
+- `start` / `end`: **byte offsets** from the start of the file (not UTF-16 character offsets as in the JS backend). For ASCII-only source these are equivalent; for non-ASCII source (e.g. Unicode identifiers or string literals), byte offsets and character offsets diverge — account for this when slicing file contents.
+- `source_full`: full text of the matched node. Only present when the match spans multiple lines (differs from `source`).
+
+⚠️ **Python `start`/`end` are byte offsets; JS/TS `start`/`end` are UTF-16 character offsets.** When writing tools that consume both, use the `file`/`line`/`col` fields for display and treat `start`/`end` as language-specific.
+
 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.
 
 ---
@@ -204,6 +213,6 @@ const matches = await searchRepo('fn', './src');
 - **`async def` functions are typed as `function_definition`** in tree-sitter-python 0.21+. There is no separate `async_function_definition` node. The `fn` shorthand matches both. To match only async, use a predicate query.
 - **Shorthands are not expanded inside quoted strings.** `'(call function: (identifier) @n (#eq? @n "fn"))'` keeps `"fn"` literal.
 - **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 `.`.
+- **`node_modules` is always excluded**, as are files/directories whose names start with `.`. Use `--exclude` / `-x` for additional patterns (e.g. `--exclude '**/*_test.py'`). Patterns match against paths relative to `--dir`.
 - **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.
 - **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/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({ file: filePath, line: anchor.node.startPosition.row + 1, col: anchor.node.startPosition.column, source: firstLine }, (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.2.0",
+  "version": "1.4.0",
   "description": "Python language plugin for ast-search",
   "type": "module",
   "main": "./build/index.js",