@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/dist/tools/ast-grep-search.js

@@ -43,11 +43,14 @@ function toSearchReads(matches) {
     }
     return out;
 }
-// Default and ceiling for matches returned per call. `maxMatches` lets a caller
+// Default and ceilings for agent-facing search inputs. `maxMatches` lets a caller
 // trade volume for completeness within these bounds (the default preserves the
-// historical page size).
+// historical page size). Explicit path lists are capped like the other bounded
+// multi-file tools, while a single directory path remains a valid project scope.
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 200;
+const MAX_PATHS = 200;
+const AST_GREP_SEARCH_TIMEOUT_MS = 30_000;
 /**
  * Compact, file-grouped rendering for high-volume searches (refs #345). Instead
  * of each match's full body, emit one line per file with its 1-based
@@ -225,19 +228,20 @@ export function createAstGrepSearchTool(astGrepClient) {
         name: "ast_grep_search",
         label: "AST Search",
         description: "Search code using AST-aware pattern matching. IMPORTANT: Use specific AST patterns, NOT text search.\n\n" +
-            "✅ GOOD patterns (single AST node):\n" +
-            "  - function $NAME() { $$$BODY }     (function declaration)\n" +
-            "  - fetchMetrics($ARGS)               (function call)\n" +
-            '  - import { $NAMES } from "$PATH"   (import statement)\n' +
-            "  - console.log($MSG)                  (method call)\n\n" +
+            "✅ GOOD patterns (complete AST shapes; $$$ accepts zero or more nodes):\n" +
+            "  - function $NAME($$$ARGS) { $$$BODY } (function declaration)\n" +
+            "  - fetchMetrics($$$ARGS)             (call with any arguments)\n" +
+            '  - import { $$$NAMES } from "module-name" (exact string-literal import)\n' +
+            "  - console.log($MSG)                 (method call)\n\n" +
             "❌ BAD patterns (multiple nodes / raw text):\n" +
-            '  - it"test name"                    (missing parens - use it($TEST))\n' +
-            "  - console.log without args          (incomplete code)\n" +
+            '  - it"test name"                     (missing parens - use it($TEST))\n' +
+            "  - console.log without args           (incomplete code)\n" +
             "  - arbitrary text without code structure\n\n" +
-            "Always prefer specific patterns with context over bare identifiers. " +
+            'Metavariables match AST nodes, not text inside quoted string literals: `from "$PATH"` matches the literal text $PATH. Use an exact quoted string for a known import, or grep for wildcard text. ' +
             "Use 'paths' to scope to specific files/folders. " +
-            "Avoid 'selector' unless you know the exact AST node kind; it narrows search roots and does not extract fields. " +
-            "Use 'context' to show surrounding lines. If zero matches, retry once with a simpler AST pattern, then use ast_grep_dump on a small representative snippet before falling back to grep.",
+            "Use 'nodeKind' to find every node of a known AST kind, or 'ast_grep_dump' first when the kind is unknown. " +
+            "Avoid 'selector' unless you know the exact AST node kind; it narrows matching and does not extract fields. " +
+            'If this tool is inactive, call pi_lens_activate_tools with tools=["ast_grep_search"]; activation takes effect next turn. If zero matches, retry once with a simpler AST pattern, then use ast_grep_dump on a small representative snippet before falling back to grep.',
         promptSnippet: "AST-aware structural code search",
         renderResult: compactRenderResult(({ details, isError, text }) => {
             if (details?.validateOnly) {
@@ -257,14 +261,15 @@ export function createAstGrepSearchTool(astGrepClient) {
         }),
         parameters: Type.Object({
             pattern: Type.Optional(Type.String({
-                description: "AST pattern (use function/class/call context, not text). Required unless `rule` is provided.",
+                description: "AST pattern (use function/class/call context, not text). Required unless `rule` or `nodeKind` is provided. Do not put metavariables inside quoted string literals; they match literally.",
             })),
             lang: Type.String({
                 enum: [...LANGUAGES],
                 description: "Target language",
             }),
             paths: Type.Optional(Type.Array(Type.String(), {
-                description: "Specific files/folders to search",
+                maxItems: MAX_PATHS,
+                description: `Specific files/folders to search (max ${MAX_PATHS} entries)`,
             })),
             selector: Type.Optional(Type.String({
                 description: "Advanced: restrict search to a specific AST node kind (for example 'call_expression' or 'function_declaration'). This narrows matching; it does not extract fields from matches.",
@@ -272,11 +277,17 @@ export function createAstGrepSearchTool(astGrepClient) {
             context: Type.Optional(Type.Number({
                 description: "Show N lines before/after each match for context",
             })),
+            nodeKind: Type.Optional(Type.String({
+                description: "Expert grammar-specific escape hatch: find every node of this exact AST kind (for example `call_expression`) without writing a pattern. Node kinds are not universal across languages; use ast_grep_dump to discover them. Mutually exclusive with `pattern` and `rule`; can be combined with structural constraints.",
+            })),
             insideKind: Type.Optional(Type.String({
                 description: 'Restrict matches to nodes inside an ancestor of this AST node kind. Example: `insideKind: "function_declaration"` finds the pattern only when it appears inside a function body. Searches all ancestors (stopBy: end), not just the immediate parent. Synthesizes a YAML rule — takes precedence over `selector` and `strictness`.',
             })),
             hasKind: Type.Optional(Type.String({
-                description: 'Restrict matches to nodes that contain a descendant of this AST node kind. Example: `hasKind: "await_expression"` finds the pattern only when it contains an await inside it.',
+                description: 'Restrict matches to nodes whose immediate child has this AST node kind (ast-grep default stopBy: neighbor). Example: `hasKind: "await_expression"`.',
+            })),
+            hasDescendantKind: Type.Optional(Type.String({
+                description: "Restrict matches to nodes containing this AST node kind anywhere in their descendants. Explicit recursive form (`stopBy: end`); use this instead of `hasKind` when nesting is not immediate.",
             })),
             follows: Type.Optional(Type.String({
                 description: 'Restrict matches to nodes that immediately follow a sibling matching this pattern. Example: `follows: "return $X"` finds the pattern only when preceded by a return statement.',
@@ -309,12 +320,15 @@ export function createAstGrepSearchTool(astGrepClient) {
             // tool-call one. Honor both so a broad search cancels on Escape.
             const abortSignal = combineAbortSignals(_signal, ctx.signal);
             const startedAt = Date.now();
-            const { paths, selector, context, skip, maxMatches, groupByFile, strictness, rule, insideKind, hasKind, follows, precedes, validateOnly, } = params;
+            const deadlineAt = startedAt + AST_GREP_SEARCH_TIMEOUT_MS;
+            const { paths, nodeKind, selector, context, skip, maxMatches, groupByFile, strictness, rule, insideKind, hasKind, hasDescendantKind, follows, precedes, validateOnly, } = params;
             const pattern = typeof params.pattern === "string" ? params.pattern : "";
             const rawLang = typeof params.lang === "string" ? params.lang : "";
+            const normalizedNodeKind = typeof nodeKind === "string" ? nodeKind.trim() : "";
             const skipOffset = Math.max(0, Math.floor(skip ?? 0));
             const lang = rawLang.replace(/^"|"$/g, "");
             const searchPathsCount = paths?.length ?? 1;
+            const executionOptions = { signal: abortSignal, deadlineAt };
             function logOutcome(outcome, details = {}) {
                 try {
                     const errorRaw = _telemetryErrorForTest(details.errorRaw);
@@ -360,7 +374,22 @@ export function createAstGrepSearchTool(astGrepClient) {
             }
             try {
                 const rawRule = typeof rule === "string" ? rule : undefined;
-                const hasRawRule = !!rawRule?.trim();
+                const hasRawRule = Boolean(rawRule?.trim());
+                const hasPattern = Boolean(pattern.trim());
+                const hasNodeKind = normalizedNodeKind.length > 0;
+                const rawPaths = params.paths;
+                if (rawPaths !== undefined &&
+                    (!Array.isArray(rawPaths) ||
+                        rawPaths.length > MAX_PATHS ||
+                        rawPaths.some((value) => typeof value !== "string"))) {
+                    const errorRaw = `paths must contain at most ${MAX_PATHS} string entries`;
+                    logOutcome("error", { errorRaw });
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorRaw}` }],
+                        isError: true,
+                        details: {},
+                    };
+                }
                 const rawRuleError = rawRuleValidationError(rawRule);
                 if (rawRuleError) {
                     logOutcome("error", { errorRaw: rawRuleError });
@@ -372,11 +401,16 @@ export function createAstGrepSearchTool(astGrepClient) {
                         details: {},
                     };
                 }
-                if (!pattern.trim() && !hasRawRule) {
-                    logOutcome("error", { errorRaw: "pattern is required" });
+                if (!hasPattern && !hasRawRule && !hasNodeKind) {
+                    logOutcome("error", {
+                        errorRaw: "pattern is required unless rule or nodeKind is provided",
+                    });
                     return {
                         content: [
-                            { type: "text", text: "Error: pattern is required" },
+                            {
+                                type: "text",
+                                text: "Error: pattern is required unless rule or nodeKind is provided",
+                            },
                         ],
                         isError: true,
                         details: {},
@@ -422,7 +456,9 @@ export function createAstGrepSearchTool(astGrepClient) {
                 }
                 if (abortSignal?.aborted)
                     return abortError();
-                if (!hasRawRule && looksLikeRuleYamlOrPlainText(pattern)) {
+                if (!hasRawRule &&
+                    hasPattern &&
+                    looksLikeRuleYamlOrPlainText(pattern)) {
                     logOutcome("error", {
                         errorRaw: "pattern looks like rule YAML or plain text (rejected pre-spawn)",
                     });
@@ -457,6 +493,24 @@ export function createAstGrepSearchTool(astGrepClient) {
                         details: {},
                     };
                 }
+                if (hasNodeKind && hasPattern) {
+                    const errorRaw = "nodeKind cannot be combined with pattern";
+                    logOutcome("error", { errorRaw });
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorRaw}` }],
+                        isError: true,
+                        details: {},
+                    };
+                }
+                if (hasNodeKind && hasRawRule) {
+                    const errorRaw = "nodeKind cannot be combined with rule";
+                    logOutcome("error", { errorRaw });
+                    return {
+                        content: [{ type: "text", text: `Error: ${errorRaw}` }],
+                        isError: true,
+                        details: {},
+                    };
+                }
                 const searchPaths = paths?.length ? paths : [ctx.cwd || "."];
                 const PAGE_SIZE = Math.max(1, Math.min(MAX_PAGE_SIZE, Number.isFinite(maxMatches)
                     ? Math.floor(maxMatches)
@@ -464,13 +518,23 @@ export function createAstGrepSearchTool(astGrepClient) {
                 // Phase 3: synthesize YAML from structural-intent params
                 let effectiveRule = hasRawRule ? rawRule : undefined;
                 if (!effectiveRule &&
-                    hasStructuralIntent({ insideKind, hasKind, follows, precedes })) {
+                    (hasNodeKind ||
+                        hasStructuralIntent({
+                            nodeKind: normalizedNodeKind,
+                            insideKind,
+                            hasKind,
+                            hasDescendantKind,
+                            follows,
+                            precedes,
+                        }))) {
                     try {
                         effectiveRule = synthesizeRule({
-                            pattern,
+                            pattern: hasPattern ? pattern : undefined,
+                            nodeKind: hasNodeKind ? normalizedNodeKind : undefined,
                             lang,
                             insideKind,
                             hasKind,
+                            hasDescendantKind,
                             follows,
                             precedes,
                         });
@@ -491,10 +555,11 @@ export function createAstGrepSearchTool(astGrepClient) {
                 }
                 if (validateOnly) {
                     const validation = effectiveRule?.trim()
-                        ? await astGrepClient.validateRule(effectiveRule)
+                        ? await astGrepClient.validateRule(effectiveRule, executionOptions)
                         : await astGrepClient.validatePattern(pattern, lang, {
                             selector,
                             strictness,
+                            ...executionOptions,
                         });
                     if (!validation.valid) {
                         logOutcome("error", { errorRaw: validation.error });
@@ -530,7 +595,7 @@ export function createAstGrepSearchTool(astGrepClient) {
                 if (effectiveRule && effectiveRule.trim().length > 0) {
                     if (abortSignal?.aborted)
                         return abortError();
-                    const ruleResult = await astGrepClient.searchWithRule(effectiveRule, searchPaths);
+                    const ruleResult = await astGrepClient.searchWithRule(effectiveRule, searchPaths, executionOptions);
                     if (abortSignal?.aborted)
                         return abortError();
                     if (ruleResult.error) {
@@ -551,7 +616,7 @@ export function createAstGrepSearchTool(astGrepClient) {
                     const hasMore = afterSkip.length > PAGE_SIZE;
                     const output = groupByFile
                         ? formatGroupedByFile(page)
-                        : astGrepClient.formatMatches(page);
+                        : astGrepClient.formatMatches(page, false, false, PAGE_SIZE);
                     const paginationNote = hasMore && page.length > 0
                         ? `\n\n(Showing ${page.length} of ${ruleResult.matches.length - skipOffset} remaining matches. Use skip=${skipOffset + PAGE_SIZE} for the next page.)`
                         : "";
@@ -586,6 +651,7 @@ export function createAstGrepSearchTool(astGrepClient) {
                     selector,
                     context,
                     strictness,
+                    ...executionOptions,
                 });
                 if (abortSignal?.aborted)
                     return abortError();
@@ -605,7 +671,7 @@ export function createAstGrepSearchTool(astGrepClient) {
                 const hasMore = afterSkip.length > PAGE_SIZE || result.truncated;
                 const output = groupByFile
                     ? formatGroupedByFile(page)
-                    : astGrepClient.formatMatches(page);
+                    : astGrepClient.formatMatches(page, false, false, PAGE_SIZE);
                 const hint = page.length === 0 && !result.error
                     ? getPatternHint(pattern, lang, selector)
                     : undefined;