pi-lens 3.8.21 → 3.8.22

package/scripts/validate-rule-catalog.mjs

@@ -0,0 +1,227 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const STRICT = process.argv.includes("--strict");
+
+const root = process.cwd();
+const catalogPath = path.join(root, "rules", "rule-catalog.json");
+const treeSitterRoot = path.join(root, "rules", "tree-sitter-queries");
+const astGrepRoot = path.join(root, "rules", "ast-grep-rules", "rules");
+
+const TRACKED_AST_GREP_IDS = new Set([
+	"no-sql-in-code",
+	"no-sql-in-code-js",
+	"no-open-redirect",
+	"no-open-redirect-js",
+	"no-javascript-url",
+	"no-javascript-url-js",
+	"no-insecure-randomness",
+	"no-insecure-randomness-js",
+	"no-implied-eval",
+	"no-implied-eval-js",
+	"no-hardcoded-secrets",
+	"no-hardcoded-secrets-js",
+	"no-global-eval-js",
+	"jwt-no-verify",
+	"jwt-no-verify-js",
+	"toctou",
+	"toctou-js",
+	"missed-concurrency",
+	"missed-concurrency-js",
+	"no-await-in-loop",
+	"no-await-in-loop-js",
+]);
+
+function walkYaml(dir, acc = []) {
+	if (!fs.existsSync(dir)) return acc;
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) {
+			walkYaml(full, acc);
+		} else if (entry.name.endsWith(".yml")) {
+			acc.push(full);
+		}
+	}
+	return acc;
+}
+
+function readYamlScalar(text, key) {
+	const match = text.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+	if (!match) return undefined;
+	return match[1].trim().replace(/^['\"]|['\"]$/g, "");
+}
+
+function collectTreeSitterSecurityConcurrency() {
+	const files = walkYaml(treeSitterRoot);
+	const rules = [];
+	for (const file of files) {
+		const text = fs.readFileSync(file, "utf8");
+		const id = readYamlScalar(text, "id");
+		const category = readYamlScalar(text, "category");
+		if (!id || !category) continue;
+		if (category !== "security" && category !== "concurrency") continue;
+		const language = readYamlScalar(text, "language") ?? path.basename(path.dirname(file));
+		rules.push({
+			id,
+			category,
+			language,
+			file: path.relative(root, file).replaceAll("\\", "/"),
+		});
+	}
+	return rules;
+}
+
+function collectAstGrepTrackedRules() {
+	const files = walkYaml(astGrepRoot);
+	const rules = [];
+	for (const file of files) {
+		const text = fs.readFileSync(file, "utf8");
+		const id = readYamlScalar(text, "id");
+		if (!id || !TRACKED_AST_GREP_IDS.has(id)) continue;
+		const language = readYamlScalar(text, "language") ?? "unknown";
+		rules.push({
+			id,
+			language,
+			file: path.relative(root, file).replaceAll("\\", "/"),
+		});
+	}
+	return rules;
+}
+
+function validateCatalog(catalog) {
+	const required = [
+		"rule_id",
+		"engine",
+		"language",
+		"family",
+		"scope",
+		"canonical_concept",
+		"severity_default",
+		"confidence",
+		"status",
+	];
+	const validEngine = new Set(["tree-sitter", "ast-grep", "architect"]);
+	const validSeverity = new Set(["error", "warning", "info", "review"]);
+	const validConfidence = new Set(["low", "medium", "high"]);
+	const validStatus = new Set(["experimental", "active", "deprecated"]);
+
+	const errors = [];
+	const warnings = [];
+	const byRuleId = new Map();
+	const activeByConceptScopeLang = new Map();
+
+	for (const [index, entry] of catalog.entries.entries()) {
+		for (const field of required) {
+			if (!entry[field]) {
+				errors.push(`entries[${index}] missing required field '${field}'`);
+			}
+		}
+
+		if (entry.engine && !validEngine.has(entry.engine)) {
+			errors.push(`entries[${index}] has invalid engine '${entry.engine}'`);
+		}
+		if (entry.severity_default && !validSeverity.has(entry.severity_default)) {
+			errors.push(
+				`entries[${index}] has invalid severity_default '${entry.severity_default}'`,
+			);
+		}
+		if (entry.confidence && !validConfidence.has(entry.confidence)) {
+			errors.push(`entries[${index}] has invalid confidence '${entry.confidence}'`);
+		}
+		if (entry.status && !validStatus.has(entry.status)) {
+			errors.push(`entries[${index}] has invalid status '${entry.status}'`);
+		}
+
+		if (entry.rule_id) {
+			if (byRuleId.has(entry.rule_id)) {
+				errors.push(`duplicate rule_id '${entry.rule_id}' in rule catalog`);
+			}
+			byRuleId.set(entry.rule_id, entry);
+		}
+
+		if (entry.status === "active" && !entry.allow_overlap) {
+			const key = `${entry.language}::${entry.scope}::${entry.canonical_concept}`;
+			const prev = activeByConceptScopeLang.get(key);
+			if (prev) {
+				warnings.push(
+					`possible overlap for ${key}: '${prev.rule_id}' and '${entry.rule_id}' (consider allow_overlap or concept split)`,
+				);
+			} else {
+				activeByConceptScopeLang.set(key, entry);
+			}
+		}
+	}
+
+	return { errors, warnings, byRuleId };
+}
+
+if (!fs.existsSync(catalogPath)) {
+	console.error(`[rule-catalog] missing ${catalogPath}`);
+	process.exit(1);
+}
+
+const catalogRaw = fs.readFileSync(catalogPath, "utf8");
+let parsed;
+try {
+	parsed = JSON.parse(catalogRaw);
+} catch (error) {
+	console.error(`[rule-catalog] invalid JSON: ${error}`);
+	process.exit(1);
+}
+
+const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+const treeRules = collectTreeSitterSecurityConcurrency();
+const astRules = collectAstGrepTrackedRules();
+const { errors, warnings, byRuleId } = validateCatalog({ entries });
+
+for (const rule of treeRules) {
+	if (!byRuleId.has(rule.id)) {
+		warnings.push(
+			`missing catalog entry for ${rule.id} (${rule.category}, ${rule.language}) at ${rule.file}`,
+		);
+	}
+}
+
+for (const entry of entries) {
+	if (entry.engine !== "tree-sitter") continue;
+	const exists = treeRules.some((rule) => rule.id === entry.rule_id);
+	if (!exists) {
+		warnings.push(
+			`catalog entry '${entry.rule_id}' has no matching tree-sitter rule file (maybe removed or renamed)`,
+		);
+	}
+}
+
+for (const rule of astRules) {
+	if (!byRuleId.has(rule.id)) {
+		warnings.push(
+			`missing catalog entry for ${rule.id} (ast-grep, ${rule.language}) at ${rule.file}`,
+		);
+	}
+}
+
+for (const entry of entries) {
+	if (entry.engine !== "ast-grep") continue;
+	const exists = astRules.some((rule) => rule.id === entry.rule_id);
+	if (!exists) {
+		warnings.push(
+			`catalog entry '${entry.rule_id}' has no matching tracked ast-grep rule file`,
+		);
+	}
+}
+
+const report = {
+	catalogEntries: entries.length,
+	trackedTreeSitterSecurityConcurrencyRules: treeRules.length,
+	trackedAstGrepRules: astRules.length,
+	errors: errors.length,
+	warnings: warnings.length,
+	strict: STRICT,
+};
+
+console.log(JSON.stringify(report, null, 2));
+for (const err of errors) console.error(`[rule-catalog][error] ${err}`);
+for (const warn of warnings) console.error(`[rule-catalog][warn] ${warn}`);
+
+if (errors.length > 0) process.exit(1);
+if (STRICT && warnings.length > 0) process.exit(1);

package/skills/lsp-navigation/SKILL.md

@@ -16,11 +16,25 @@ Use `lsp_navigation` as **PRIMARY** for code intelligence. Do NOT use grep/glob/
 | "Where is this defined?" | `definition` | filePath, line, character |
 | "Find all usages" | `references` | filePath, line, character |
 | "What type is this?" | `hover` | filePath, line, character |
+| "Show call signature here" | `signatureHelp` | filePath, line, character (at call-site args) |
 | "What symbols in this file?" | `documentSymbol` | filePath |
-| "Find symbol across project" | `workspaceSymbol` | filePath, query |
+| "Find symbol across project" | `workspaceSymbol` | query + **filePath strongly recommended** |
+| "What quick fixes are available?" | `codeAction` | filePath, line, character, endLine, endCharacter |
+| "Rename symbol safely" | `rename` | filePath, line, character, newName |
 | "Who implements this interface?" | `implementation` | filePath, line, character |
 | "Who calls this function?" | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character |
 | "What does this function call?" | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character |
+| "Show tracked LSP diagnostics" | `workspaceDiagnostics` | optional filePath (snapshot, not full pull workspace) |
+
+## Operational Guidance (From Field Tests)
+
+- Always pass `filePath` for `workspaceSymbol` when possible. Unscoped queries are best-effort and often empty.
+- For `references`, prefer querying from the definition site for broader cross-file coverage; usage-site queries can be partial.
+- Use `signatureHelp` only at call-site argument positions; declaration positions often return empty.
+- Treat `workspaceDiagnostics` as tracked push snapshot (`publishDiagnostics`), not protocol pull `workspace/diagnostic` coverage.
+- For `codeAction`, separate `quickfix` from generic refactors (for example "Move to new file"). Do not treat generic refactors as error fixes.
+- `prepareCallHierarchy` is server-capability dependent; if unsupported, skip incoming/outgoing calls.
+- If TypeScript returns `No Project` on `workspaceSymbol`, retry after opening the scoped file context.
 
 ## Call Hierarchy Pattern
 
@@ -36,14 +50,12 @@ const items = await lsp_navigation({
 // Step 2: Get callers (who calls this function)
 const callers = await lsp_navigation({
   operation: "incomingCalls",
-  filePath: "src/api.ts",
   callHierarchyItem: items[0]
 });
 
 // Step 2: Get callees (what this function calls)
 const callees = await lsp_navigation({
   operation: "outgoingCalls",
-  filePath: "src/api.ts",
   callHierarchyItem: items[0]
 });
 ```

package/tools/lsp-navigation.js

@@ -7,6 +7,80 @@ import * as nodeFs from "node:fs";
 import * as path from "node:path";
 import { Type } from "@sinclair/typebox";
 import { getLSPService } from "../clients/lsp/index.js";
+function operationSupportStatus(operation, support) {
+    if (!support)
+        return null;
+    if (operation === "definition")
+        return support.definition;
+    if (operation === "references")
+        return support.references;
+    if (operation === "hover")
+        return support.hover;
+    if (operation === "signatureHelp")
+        return support.signatureHelp;
+    if (operation === "documentSymbol")
+        return support.documentSymbol;
+    if (operation === "workspaceSymbol")
+        return support.workspaceSymbol;
+    if (operation === "codeAction")
+        return support.codeAction;
+    if (operation === "rename")
+        return support.rename;
+    if (operation === "implementation")
+        return support.implementation;
+    if (operation === "prepareCallHierarchy" ||
+        operation === "incomingCalls" ||
+        operation === "outgoingCalls")
+        return support.callHierarchy;
+    return null;
+}
+function emptyReasonForOperation(operation) {
+    if (operation === "signatureHelp")
+        return "position-sensitive-or-no-signature";
+    if (operation === "codeAction")
+        return "no-applicable-actions";
+    if (operation === "rename")
+        return "no-rename-edits-or-symbol-not-renamable";
+    if (operation === "workspaceSymbol")
+        return "no-matching-symbols-or-server-index-unavailable";
+    if (operation === "incomingCalls" || operation === "outgoingCalls")
+        return "no-call-hierarchy-results";
+    return "no-results";
+}
+function classifyCodeActions(actions) {
+    if (!actions || actions.length === 0)
+        return { quickfix: 0, refactor: 0, other: 0 };
+    let quickfix = 0;
+    let refactor = 0;
+    let other = 0;
+    for (const action of actions) {
+        const kind = action.kind ?? "";
+        if (kind.startsWith("quickfix"))
+            quickfix += 1;
+        else if (kind.startsWith("refactor"))
+            refactor += 1;
+        else
+            other += 1;
+    }
+    return { quickfix, refactor, other };
+}
+async function openFileBestEffort(lspService, filePath) {
+    let fileContent;
+    try {
+        fileContent = nodeFs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return;
+    }
+    if (!fileContent)
+        return;
+    try {
+        await lspService.openFile(filePath, fileContent);
+    }
+    catch {
+        /* LSP server may not be ready yet — proceed anyway */
+    }
+}
 export function createLspNavigationTool(getFlag) {
     return {
         name: "lsp_navigation",
@@ -16,12 +90,16 @@ export function createLspNavigationTool(getFlag) {
             "- definition: Jump to where a symbol is defined\n" +
             "- references: Find all usages of a symbol\n" +
             "- hover: Get type/doc info at a position\n" +
+            "- signatureHelp: Show callable signatures at cursor\n" +
             "- documentSymbol: List all symbols (functions/classes/vars) in a file\n" +
-            "- workspaceSymbol: Search symbols across the whole project\n" +
+            "- workspaceSymbol: Search symbols across the whole project (best with filePath context)\n" +
+            "- codeAction: Find available quick fixes/refactors at a range\n" +
+            "- rename: Compute workspace edits for renaming a symbol\n" +
             "- implementation: Jump to interface implementations\n" +
             "- prepareCallHierarchy: Get callable item at position (for incoming/outgoing)\n" +
             "- incomingCalls: Find all functions/methods that CALL this function\n" +
-            "- outgoingCalls: Find all functions/methods CALLED by this function\n\n" +
+            "- outgoingCalls: Find all functions/methods CALLED by this function\n" +
+            "- workspaceDiagnostics: List all diagnostics tracked by active LSP clients\n\n" +
             "Line and character are 1-based (as shown in editors).",
         promptSnippet: "Use lsp_navigation to find definitions, references, and hover info via LSP",
         parameters: Type.Object({
@@ -29,24 +107,37 @@ export function createLspNavigationTool(getFlag) {
                 Type.Literal("definition"),
                 Type.Literal("references"),
                 Type.Literal("hover"),
+                Type.Literal("signatureHelp"),
                 Type.Literal("documentSymbol"),
                 Type.Literal("workspaceSymbol"),
+                Type.Literal("codeAction"),
+                Type.Literal("rename"),
                 Type.Literal("implementation"),
                 Type.Literal("prepareCallHierarchy"),
                 Type.Literal("incomingCalls"),
                 Type.Literal("outgoingCalls"),
+                Type.Literal("workspaceDiagnostics"),
             ], { description: "LSP operation to perform" }),
-            filePath: Type.String({
-                description: "Absolute or relative path to the file",
-            }),
+            filePath: Type.Optional(Type.String({
+                description: "Absolute or relative file path. Required for file-scoped operations; optional for workspaceSymbol/workspaceDiagnostics.",
+            })),
             line: Type.Optional(Type.Number({
                 description: "Line number (1-based). Required for definition/references/hover/implementation",
             })),
             character: Type.Optional(Type.Number({
                 description: "Character offset (1-based). Required for definition/references/hover/implementation",
             })),
+            endLine: Type.Optional(Type.Number({
+                description: "End line (1-based). Optional; used by codeAction range.",
+            })),
+            endCharacter: Type.Optional(Type.Number({
+                description: "End character (1-based). Optional; used by codeAction range.",
+            })),
+            newName: Type.Optional(Type.String({
+                description: "Required for rename operation.",
+            })),
             query: Type.Optional(Type.String({
-                description: "Symbol name to search. Used by workspaceSymbol",
+                description: "Symbol name to search. Used by workspaceSymbol (best with filePath for active project context).",
             })),
             callHierarchyItem: Type.Optional(Type.Object({
                 name: Type.String(),
@@ -77,6 +168,8 @@ export function createLspNavigationTool(getFlag) {
             })),
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+            let supported = null;
+            let diagnosticsMode = "unknown";
             if (!getFlag("lens-lsp") || getFlag("no-lsp")) {
                 return {
                     content: [
@@ -89,43 +182,93 @@ export function createLspNavigationTool(getFlag) {
                     details: {},
                 };
             }
-            const { operation, filePath: rawPath, line, character, query, } = params;
-            const filePath = path.isAbsolute(rawPath)
-                ? rawPath
-                : path.resolve(ctx.cwd || ".", rawPath);
-            const lspService = getLSPService();
-            const hasLSP = await lspService.hasLSP(filePath);
-            if (!hasLSP) {
+            const { operation, filePath: rawPath, line, character, endLine, endCharacter, newName, query, } = params;
+            const isCallHierarchyTraversal = operation === "incomingCalls" || operation === "outgoingCalls";
+            const needsFilePath = operation !== "workspaceDiagnostics" &&
+                operation !== "workspaceSymbol" &&
+                !isCallHierarchyTraversal;
+            if (needsFilePath && (!rawPath || rawPath.trim().length === 0)) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `No LSP server available for ${path.basename(filePath)}. Check that the language server is installed.`,
+                            text: `filePath is required for ${operation}`,
                         },
                     ],
                     isError: true,
                     details: {},
                 };
             }
-            // Ensure file is open in LSP before querying
-            let fileContent;
-            try {
-                fileContent = nodeFs.readFileSync(filePath, "utf-8");
+            const filePath = rawPath
+                ? path.isAbsolute(rawPath)
+                    ? rawPath
+                    : path.resolve(ctx.cwd || ".", rawPath)
+                : "";
+            const lspService = getLSPService();
+            if (operation === "workspaceDiagnostics") {
+                const allDiagnostics = await lspService.getAllDiagnostics();
+                const wsDiagSupport = await lspService.getWorkspaceDiagnosticsSupport(rawPath ? filePath : undefined);
+                diagnosticsMode = wsDiagSupport?.mode ?? "unknown";
+                const result = Array.from(allDiagnostics.entries()).map(([trackedFile, diags]) => ({
+                    filePath: trackedFile,
+                    diagnostics: diags,
+                    count: diags.length,
+                }));
+                const note = diagnosticsMode === "push-only"
+                    ? "Note: push-only tracked diagnostics snapshot (not full workspace pull diagnostics)."
+                    : diagnosticsMode === "pull"
+                        ? "Note: server advertises workspace pull diagnostics support."
+                        : "Note: workspace diagnostics mode unknown (no active capability snapshot).";
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `${note}\n${JSON.stringify(result, null, 2)}`,
+                        },
+                    ],
+                    details: {
+                        operation,
+                        resultCount: result.length,
+                        diagnosticsMode,
+                        coverage: "tracked-open-files",
+                    },
+                };
             }
-            catch {
-                /* ignore */
+            const hasLSP = filePath ? await lspService.hasLSP(filePath) : false;
+            if (needsFilePath && !hasLSP) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `No LSP server available for ${path.basename(filePath)}. Check that the language server is installed.`,
+                        },
+                    ],
+                    isError: true,
+                    details: {},
+                };
             }
-            if (fileContent) {
-                try {
-                    await lspService.openFile(filePath, fileContent);
-                }
-                catch {
-                    /* LSP server may not be ready yet — proceed anyway */
+            if (needsFilePath) {
+                const support = await lspService.getOperationSupport(filePath);
+                supported = operationSupportStatus(operation, support);
+                if (supported === false) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `LSP server for ${path.basename(filePath)} does not advertise support for ${operation}`,
+                            },
+                        ],
+                        isError: true,
+                        details: { operation, supported: false, emptyReason: "unsupported" },
+                    };
                 }
+                await openFileBestEffort(lspService, filePath);
             }
             // Convert 1-based editor coords to 0-based LSP coords
             const lspLine = (line ?? 1) - 1;
             const lspChar = (character ?? 1) - 1;
+            const lspEndLine = (endLine ?? line ?? 1) - 1;
+            const lspEndChar = (endCharacter ?? character ?? 1) - 1;
             let result;
             try {
                 switch (operation) {
@@ -138,11 +281,77 @@ export function createLspNavigationTool(getFlag) {
                     case "hover":
                         result = await lspService.hover(filePath, lspLine, lspChar);
                         break;
+                    case "signatureHelp":
+                        result = await lspService.signatureHelp(filePath, lspLine, lspChar);
+                        break;
                     case "documentSymbol":
                         result = await lspService.documentSymbol(filePath);
                         break;
                     case "workspaceSymbol":
-                        result = await lspService.workspaceSymbol(query ?? "");
+                        supported = operationSupportStatus(operation, await lspService.getOperationSupport(rawPath ? filePath : undefined));
+                        if (supported === false) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Active LSP server does not advertise support for workspaceSymbol",
+                                    },
+                                ],
+                                isError: true,
+                                details: {
+                                    operation,
+                                    supported: false,
+                                    emptyReason: "unsupported",
+                                },
+                            };
+                        }
+                        if (!query || query.trim().length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "query parameter required for workspaceSymbol",
+                                    },
+                                ],
+                                isError: true,
+                                details: {},
+                            };
+                        }
+                        if (rawPath) {
+                            await openFileBestEffort(lspService, filePath);
+                        }
+                        try {
+                            result = await lspService.workspaceSymbol(query ?? "", rawPath ? filePath : undefined);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            if (rawPath && /No Project/i.test(msg)) {
+                                await openFileBestEffort(lspService, filePath);
+                                await new Promise((resolve) => setTimeout(resolve, 120));
+                                result = await lspService.workspaceSymbol(query ?? "", filePath);
+                            }
+                            else {
+                                throw err;
+                            }
+                        }
+                        break;
+                    case "codeAction":
+                        result = await lspService.codeAction(filePath, lspLine, lspChar, lspEndLine, lspEndChar);
+                        break;
+                    case "rename":
+                        if (!newName || newName.trim().length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "newName parameter required for rename",
+                                    },
+                                ],
+                                isError: true,
+                                details: {},
+                            };
+                        }
+                        result = await lspService.rename(filePath, lspLine, lspChar, newName);
                         break;
                     case "implementation":
                         result = await lspService.implementation(filePath, lspLine, lspChar);
@@ -201,13 +410,35 @@ export function createLspNavigationTool(getFlag) {
                 };
             }
             const isEmpty = !result || (Array.isArray(result) && result.length === 0);
-            const output = isEmpty
+            let output = isEmpty
                 ? `No results for ${operation} at ${path.basename(filePath)}${line ? `:${line}:${character}` : ""}`
                 : JSON.stringify(result, null, 2);
+            if (isEmpty && operation === "workspaceSymbol" && !rawPath) {
+                output +=
+                    "\nHint: provide filePath to scope workspaceSymbol to the active language server/root.";
+            }
+            if (operation === "references" &&
+                Array.isArray(result) &&
+                result.length <= 2) {
+                output +=
+                    "\nHint: references from usage sites can be partial; retry from the symbol definition for broader cross-file results.";
+            }
+            const actionStats = operation === "codeAction" && Array.isArray(result)
+                ? classifyCodeActions(result)
+                : null;
+            if (operation === "codeAction" && actionStats) {
+                if (actionStats.quickfix === 0 && actionStats.refactor > 0) {
+                    output +=
+                        "\nNote: no diagnostic quick fixes returned; refactor-only actions available.";
+                }
+            }
             return {
                 content: [{ type: "text", text: output }],
                 details: {
                     operation,
+                    supported,
+                    emptyReason: isEmpty ? emptyReasonForOperation(operation) : undefined,
+                    codeActionKinds: actionStats ?? undefined,
                     resultCount: Array.isArray(result) ? result.length : result ? 1 : 0,
                 },
             };