ast-search-python 1.4.1 → 1.5.0-beta.1

package/AGENTS.md

@@ -94,6 +94,7 @@ JSON output includes `start`/`end` byte offsets and `source_full` (for multi-lin
   "col": 0,
   "start": 87,
   "end": 116,
+  "offsetEncoding": "bytes",
   "source": "logging.info(\"user logged in\")",
   "captures": {
     "fn": "logging.info",
@@ -103,10 +104,10 @@ JSON output includes `start`/`end` byte offsets and `source_full` (for multi-lin
 }
 ```
 
-- `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.
+- `start` / `end`: character offsets from the start of the file. `offsetEncoding` is always `"bytes"` for Python matches (tree-sitter). For ASCII-only source, byte offsets and UTF-16 offsets are equivalent; for non-ASCII source (e.g. Unicode identifiers or string literals) they 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.
+⚠️ **`offsetEncoding` differs by language: `"bytes"` for Python, `"utf16"` for JS/TS.** When writing tools that consume both, use `offsetEncoding` to determine how to interpret `start`/`end`, or use `file`/`line`/`col` for display and avoid `start`/`end` cross-language comparisons.
 
 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.
 

package/build/query.js

@@ -45,12 +45,31 @@ export function runTreeSitterQuery(ast, pattern, source, filePath, language, sho
     }
     return results;
 }
+// Common tree-sitter error patterns and more actionable hints.
+function enrichTreeSitterError(raw, pattern) {
+    const lines = [`Invalid tree-sitter query: ${raw}`];
+    // Detect "Invalid node type" — the most common authoring mistake
+    const nodeTypeMatch = raw.match(/Invalid node type[:\s]+["']?(\w+)["']?/i);
+    if (nodeTypeMatch) {
+        lines.push(`Hint: node type "${nodeTypeMatch[1]}" is not recognized by the Python grammar.`, `Use show_ast on a real .py file to discover the correct node names.`);
+        return lines.join("\n");
+    }
+    // Missing @ capture
+    if (!pattern.includes("@") && !raw.toLowerCase().includes("capture")) {
+        lines.push(`Hint: tree-sitter S-expressions require a capture name, e.g. "(function_definition) @fn".`, `Without @capture, no results are returned. The query engine may also reject bare S-expressions.`);
+        return lines.join("\n");
+    }
+    // Generic fallback guidance
+    lines.push(`Hint: use show_ast on a .py file to see the correct node types and property names before authoring a query.`, `Example valid queries: "(function_definition) @fn"  |  "(call) @_"  |  "(import_statement) @import"`);
+    return lines.join("\n");
+}
 export function validateTreeSitterQuery(pattern, language) {
     try {
         assertValidPattern(pattern);
         language.query(pattern);
     }
     catch (e) {
-        throw new Error(`Invalid tree-sitter query: ${e instanceof Error ? e.message : String(e)}`);
+        const raw = e instanceof Error ? e.message : String(e);
+        throw new Error(enrichTreeSitterError(raw, pattern));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ast-search-python",
-  "version": "1.4.1",
+  "version": "1.5.0-beta.1",
   "description": "Python language plugin for ast-search",
   "type": "module",
   "main": "./build/index.js",
@@ -47,6 +47,6 @@
     "typescript": "^5.4.5"
   },
   "peerDependencies": {
-    "ast-search-js": "^1.0.0"
+    "ast-search-js": "1.9.0-beta.1"
   }
 }