pi-lens 4.3.0 → 4.4.0

package/dist/clients/ast-grep-rule-manager.js

@@ -1,146 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-/**
- * The candidate sub-paths under `ruleDir` that hold ast-grep rule
- * descriptions — SINGLE source of truth shared by `loadRuleDescriptions`
- * (the real read) and `checkAstGrepRulesHealth` (the #2636 observational
- * probe), so the two can never drift apart on "where do rules live".
- */
-export function candidateAstGrepRulesPaths(ruleDir) {
-    return [
-        path.join(ruleDir, "ast-grep-rules", "rules"),
-        path.join(ruleDir, "rules"),
-        ruleDir,
-    ];
-}
-/**
- * Classify whether `ruleDir` (the resolved ast-grep rules root, `rules/`
- * inside the bundled package or the project override) yields any loadable
- * `.yml` rule description — mirroring `loadRuleDescriptions`'s OWN
- * resolution EXACTLY (first existing candidate wins, then its `.yml`
- * files), so this never reports a status `loadRuleDescriptions` itself
- * would disagree with. Purely observational: never throws, and does not
- * gate what `ruleDir` `AstGrepClient` uses (#2636, following #2626 review
- * F1 — the acceptance criteria ask for a RECORD, never a changed resolution).
- */
-export function checkAstGrepRulesHealth(ruleDir) {
-    const possiblePaths = candidateAstGrepRulesPaths(ruleDir);
-    let rulesPath;
-    for (const candidate of possiblePaths) {
-        if (fs.existsSync(candidate)) {
-            rulesPath = candidate;
-            break;
-        }
-    }
-    if (!rulesPath) {
-        // None of the three candidates exist — distinguish `ruleDir` itself
-        // being unreadable (EACCES and friends) from it simply being absent
-        // (ENOENT), matching #2626 review F4's ENOENT/EACCES split.
-        try {
-            fs.readdirSync(ruleDir);
-        }
-        catch (error) {
-            const fsErrorCode = error?.code;
-            if (fsErrorCode && fsErrorCode !== "ENOENT") {
-                return { status: "unreadable", fsErrorCode };
-            }
-        }
-        return { status: "absent" };
-    }
-    let entries;
-    try {
-        entries = fs.readdirSync(rulesPath).filter((f) => f.endsWith(".yml"));
-    }
-    catch (error) {
-        const fsErrorCode = error?.code ?? "UNKNOWN";
-        return { status: "unreadable", fsErrorCode };
-    }
-    return entries.length > 0
-        ? { status: "healthy", entryCount: entries.length }
-        : { status: "empty" };
-}
-export class AstGrepRuleManager {
-    ruleDir;
-    log;
-    ruleDescriptions = null;
-    constructor(ruleDir, log) {
-        this.ruleDir = ruleDir;
-        this.log = log;
-    }
-    loadRuleDescriptions() {
-        if (this.ruleDescriptions !== null)
-            return this.ruleDescriptions;
-        const descriptions = new Map();
-        const possiblePaths = candidateAstGrepRulesPaths(this.ruleDir);
-        const rulesPath = possiblePaths.find((p) => fs.existsSync(p));
-        if (!rulesPath) {
-            this.log(`Rule descriptions: no rules directory found in ${possiblePaths.join(", ")}`);
-            this.ruleDescriptions = descriptions;
-            return descriptions;
-        }
-        try {
-            const files = fs.readdirSync(rulesPath).filter((f) => f.endsWith(".yml"));
-            this.log(`Loaded ${files.length} rule descriptions from ${rulesPath}`);
-            for (const file of files) {
-                const filePath = path.join(rulesPath, file);
-                const content = fs.readFileSync(filePath, "utf-8");
-                const rule = this.parseRuleYaml(content);
-                if (rule) {
-                    descriptions.set(rule.id, rule);
-                }
-            }
-        }
-        catch (err) {
-            this.log(`Failed to load rule descriptions: ${err.message}`);
-        }
-        this.ruleDescriptions = descriptions;
-        return descriptions;
-    }
-    parseRuleYaml(content) {
-        const result = {};
-        const idMatch = content.match(/^id:\s*(.+)$/m);
-        if (idMatch)
-            result.id = idMatch[1].trim();
-        const msgMatch = content.match(/^message:\s*"([^"]+)"/m) ||
-            content.match(/^message:\s*'([^']+)'/m) ||
-            content.match(/^message:\s*(.+)$/m);
-        if (msgMatch)
-            result.message = (msgMatch[3] || msgMatch[2] || msgMatch[1]).trim();
-        const noteMatch = content.match(/^note:\s*\|([\s\S]*?)(?=^\w|\n\n|\nrule:)/m);
-        if (noteMatch) {
-            result.note = noteMatch[1]
-                .split(/\r?\n/)
-                .map((line) => line.trim())
-                .filter((line) => line.length > 0)
-                .join(" ");
-        }
-        const sevMatch = content.match(/^severity:\s*(.+)$/m);
-        if (sevMatch)
-            result.severity = this.mapSeverity(sevMatch[1].trim());
-        const gradeMatch = content.match(/Grade\s+(\d+\.\d+)/i);
-        if (gradeMatch)
-            result.grade = parseFloat(gradeMatch[1]);
-        const fixMatch = content.match(/^fix:\s*\|?([\s\S]*?)(?=^\w|^rule:|Z)/m);
-        if (fixMatch) {
-            result.fix = fixMatch[1]
-                .split(/\r?\n/)
-                .map((line) => line.replace(/^\s*\|?\s*/, ""))
-                .filter((line) => line.length > 0)
-                .join("\n");
-        }
-        if (result.id && result.message) {
-            return result;
-        }
-        return null;
-    }
-    mapSeverity(severity) {
-        const lower = severity.toLowerCase();
-        if (lower === "error")
-            return "error";
-        if (lower === "warning")
-            return "warning";
-        if (lower === "info")
-            return "info";
-        return "hint";
-    }
-}

package/dist/clients/ast-grep-tool-logger.js

@@ -1,118 +0,0 @@
-/**
- * NDJSON telemetry for the agent-facing ast_grep_search / ast_grep_replace
- * tools. Captures inputs, outcome, and failure category so we can answer:
- *
- *   - How often do agents hit "Multiple AST nodes" with multi-line patterns?
- *   - Which language emits which failure most often?
- *   - Do retries (post-skill-read) succeed within the same session?
- *   - Which patterns keep getting tried and keep failing?
- *
- * Mirrors `actionable-warnings-logger.ts` for shape + rotation behaviour.
- */
-import * as path from "node:path";
-import { isTestMode } from "./env-utils.js";
-import { getGlobalPiLensLogDir } from "./probe-home-state.js";
-import { createNdjsonLogger } from "./ndjson-logger.js";
-const AG_LOG_DIR = getGlobalPiLensLogDir();
-const AG_LOG_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log");
-const AG_LOG_BACKUP_FILE = path.join(AG_LOG_DIR, "ast-grep-tools.log.1");
-const MAX_LOG_BYTES = Math.max(128 * 1024, Number.parseInt(process.env.PI_LENS_AST_GREP_LOG_MAX_BYTES ?? "1048576", 10) || 1048576);
-const writer = createNdjsonLogger({
-    filePath: AG_LOG_FILE,
-    maxBytes: MAX_LOG_BYTES,
-    backupPath: AG_LOG_BACKUP_FILE,
-});
-const PATTERN_TRUNCATE_AT = 500;
-const ERROR_TRUNCATE_AT = 300;
-function truncate(value, max) {
-    if (value === undefined)
-        return undefined;
-    if (value.length <= max)
-        return value;
-    return `${value.slice(0, max)}…[truncated ${value.length - max} chars]`;
-}
-function countLines(value) {
-    if (value === undefined)
-        return undefined;
-    if (value.length === 0)
-        return 0;
-    let lines = 1;
-    for (let i = 0; i < value.length; i++) {
-        if (value.charCodeAt(i) === 10)
-            lines++;
-    }
-    return lines;
-}
-/**
- * Categorise an error string from the sg-runner / spawn layer. Looks first
- * at the friendly wrappers sg-runner.ts emits (which already contain the
- * original stderr); falls back to raw stderr substring checks for codepaths
- * that don't go through that wrapper.
- */
-export function classifyAstGrepError(errorMessage) {
-    if (!errorMessage)
-        return "other";
-    const lower = errorMessage.toLowerCase();
-    if (lower.includes("multiple ast nodes are detected") ||
-        lower.includes("the pattern appears to contain multiple ast nodes")) {
-        return "multiple_ast_nodes";
-    }
-    if (lower.includes("cannot parse query") ||
-        lower.includes("pattern syntax error") ||
-        lower.includes("could not be parsed as valid code")) {
-        return "cannot_parse_query";
-    }
-    if (lower.includes("cli not found") ||
-        lower.includes("enoent") ||
-        lower.includes("not installed")) {
-        return "tool_not_found";
-    }
-    if (lower.includes("timed out") || lower.includes("timeout")) {
-        return "timeout";
-    }
-    if (lower.includes("failed to parse output")) {
-        return "json_parse_failed";
-    }
-    return "other";
-}
-/**
- * Map a classified error kind to a one-line, agent-facing remediation hint.
- *
- * The runner layer (sg-runner.ts) already wraps the two highest-frequency
- * spawn errors — "Multiple AST nodes" and "Cannot parse query" — with curated
- * multi-line guidance, so those return `null` here (don't double up). This
- * closes the loop for the categories that otherwise reach the agent as raw
- * stderr (`other`/`timeout`/`tool_not_found`/`json_parse_failed`): we already
- * classify them for telemetry, so reuse that classification to help the agent
- * self-correct on the error path the way getPatternHint() does on zero-matches.
- */
-export function astGrepRemediationHint(kind) {
-    switch (kind) {
-        case "multiple_ast_nodes":
-        case "cannot_parse_query":
-            // Error text already carries curated guidance from sg-runner.ts.
-            return null;
-        case "tool_not_found":
-            return "Hint: the ast-grep CLI is missing or not on PATH — install it with `npm i -D @ast-grep/cli`.";
-        case "timeout":
-            return "Hint: the operation timed out — scope `paths` to specific files/folders, or narrow the pattern.";
-        case "json_parse_failed":
-            return "Hint: ast-grep produced output that could not be parsed — retry with a simpler pattern; the installed CLI version may be incompatible.";
-        default:
-            return "Hint: verify the pattern is a single valid AST node for this `lang` (use ast_grep_search with dump=true to discover node kinds), or fall back to grep for plain-text search.";
-    }
-}
-export function logAstGrepToolEvent(event) {
-    if (isTestMode())
-        return;
-    const payload = {
-        ...event,
-        pattern: truncate(event.pattern, PATTERN_TRUNCATE_AT) ?? "",
-        patternLineCount: event.patternLineCount,
-        rewrite: truncate(event.rewrite, PATTERN_TRUNCATE_AT),
-        rewriteLineCount: event.rewriteLineCount,
-        errorRaw: truncate(event.errorRaw, ERROR_TRUNCATE_AT),
-    };
-    writer.log({ ts: new Date().toISOString(), ...payload });
-}
-export { countLines as _countLinesForTest };

package/dist/clients/ast-grep-types.js

@@ -1,10 +0,0 @@
-/**
- * Shared types for ast-grep client, parser, and rule manager.
- *
- * Extracted to prevent circular dependencies between:
- * - ast-grep-client.ts
- * - ast-grep-rule-manager.ts
- */
-export {};
-// =============================================================================
-// JSON FORMAT (ast-grep CLI output)

package/dist/clients/ast-grep-yaml-synth.js

@@ -1,154 +0,0 @@
-/**
- * YAML rule synthesis for ast_grep_search / ast_grep_replace (Issue #125 Phase 3).
- *
- * Takes a pattern + structural-intent parameters and produces a valid
- * ast-grep YAML rule that routes through `sg scan --config`.
- *
- * This lets agents express cross-context queries without writing raw YAML:
- *   insideKind: "function_declaration"   → rule.inside: { kind, stopBy: "end" }
- *   hasKind: "await_expression"          → rule.has: { kind }
- *   follows: "return $X"                 → rule.follows: { pattern }
- *   precedes: "return $X"                → rule.precedes: { pattern }
- *
- * Multiple constraints are combined directly on the rule object — ast-grep
- * evaluates all of them as an implicit AND.
- */
-import { dump } from "./deps/js-yaml.js";
-const MAX_SYNTHESIZED_PATTERN_CHARS = 4_000;
-const MAX_NODE_KIND_CHARS = 80;
-const NODE_KIND_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/**
- * Returns true when at least one structural-intent field is present.
- */
-export function hasStructuralIntent(intent) {
-    return !!(intent.nodeKind ||
-        intent.insideKind ||
-        intent.hasKind ||
-        intent.hasDescendantKind ||
-        intent.follows ||
-        intent.precedes);
-}
-/**
- * Synthesize an ast-grep YAML rule for replace operations.
- * Adds a `fix:` field so `sg scan --update-all` applies the rewrite.
- */
-export function synthesizeReplaceRule(intent) {
-    const base = synthesizeRule(intent);
-    // js-yaml dump ends with \n; append fix field
-    return `${base}fix: ${JSON.stringify(intent.rewrite)}\n`;
-}
-/**
- * Synthesize an ast-grep YAML rule from a pattern (or node kind) and
- * structural constraints.
- *
- * The generated rule uses `stopBy: end` on `inside` and
- * `hasDescendantKind`, so those two explicit recursive forms climb all
- * ancestors/descendants. `hasKind` intentionally retains ast-grep's default
- * immediate-child semantics for compatibility.
- *
- * @throws if neither pattern nor nodeKind is supplied, or both are supplied
- */
-export function synthesizeRule(intent) {
-    const hasPattern = !!intent.pattern?.trim();
-    const hasNodeKind = !!intent.nodeKind?.trim();
-    if (hasPattern === hasNodeKind) {
-        throw new Error("provide exactly one of pattern or nodeKind");
-    }
-    const pattern = intent.pattern;
-    if (hasPattern && pattern)
-        assertSafePattern(pattern, "pattern");
-    if (intent.hasKind?.trim() && intent.hasDescendantKind?.trim()) {
-        throw new Error("hasKind and hasDescendantKind are mutually exclusive");
-    }
-    // Canonical language name for the YAML header (ast-grep is case-sensitive here).
-    const language = canonicalLanguage(intent.lang);
-    const rule = hasNodeKind
-        ? { kind: assertSafeNodeKind(intent.nodeKind ?? "", "nodeKind") }
-        : { pattern };
-    if (intent.insideKind) {
-        rule.inside = {
-            kind: assertSafeNodeKind(intent.insideKind, "insideKind"),
-            stopBy: "end",
-        };
-    }
-    if (intent.hasKind) {
-        rule.has = { kind: assertSafeNodeKind(intent.hasKind, "hasKind") };
-    }
-    if (intent.hasDescendantKind) {
-        rule.has = {
-            kind: assertSafeNodeKind(intent.hasDescendantKind, "hasDescendantKind"),
-            stopBy: "end",
-        };
-    }
-    if (intent.follows) {
-        assertSafePattern(intent.follows, "follows");
-        rule.follows = { pattern: intent.follows };
-    }
-    if (intent.precedes) {
-        assertSafePattern(intent.precedes, "precedes");
-        rule.precedes = { pattern: intent.precedes };
-    }
-    const doc = {
-        id: "agent-rule",
-        language,
-        rule,
-    };
-    return dump(doc, { lineWidth: -1 });
-}
-function assertSafePattern(value, field) {
-    if (!value.trim()) {
-        throw new Error(`${field} is required for YAML synthesis`);
-    }
-    if (value.length > MAX_SYNTHESIZED_PATTERN_CHARS) {
-        throw new Error(`${field} is too long for YAML synthesis`);
-    }
-    if (value.includes("\0")) {
-        throw new Error(`${field} contains a NUL byte`);
-    }
-}
-function assertSafeNodeKind(value, field) {
-    const kind = value.trim();
-    if (kind.length === 0) {
-        throw new Error(`${field} is required for YAML synthesis`);
-    }
-    if (kind.length > MAX_NODE_KIND_CHARS || !NODE_KIND_RE.test(kind)) {
-        throw new Error(`${field} must be a single AST node kind like function_declaration`);
-    }
-    return kind;
-}
-/**
- * Map a user-supplied lang value (e.g. "typescript", "TypeScript") to the
- * capitalisation ast-grep expects in the YAML `language:` field.
- */
-function canonicalLanguage(lang) {
-    const map = {
-        typescript: "TypeScript",
-        tsx: "Tsx",
-        javascript: "JavaScript",
-        jsx: "JavaScript",
-        python: "Python",
-        rust: "Rust",
-        go: "Go",
-        java: "Java",
-        kotlin: "Kotlin",
-        swift: "Swift",
-        csharp: "CSharp",
-        cpp: "Cpp",
-        c: "C",
-        ruby: "Ruby",
-        php: "Php",
-        dart: "Dart",
-        elixir: "Elixir",
-        lua: "Lua",
-        ocaml: "OCaml",
-        zig: "Zig",
-        bash: "Bash",
-        css: "Css",
-        html: "Html",
-        json: "Json",
-        yaml: "Yaml",
-        toml: "Toml",
-        vue: "Vue",
-    };
-    return map[lang.toLowerCase()] ?? lang;
-}

package/dist/clients/atomic-write-staging.js

@@ -1,75 +0,0 @@
-/** Owns the generic atomic-write `.tmp-<pid>-<threadId>-<seq>` namespace. */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { threadId } from "node:worker_threads";
-let stageSeq = 0;
-export const STAGE_TMP_PATTERN = /\.tmp-(0|[1-9]\d*)-(0|[1-9]\d*)-(0|[1-9]\d*)$/;
-const STAGE_TMP_PID_PATTERN = /\.tmp-(0|[1-9]\d*)-(?:0|[1-9]\d*)-(?:0|[1-9]\d*)$/;
-export function stagePathFor(targetPath) {
-    return `${targetPath}.tmp-${process.pid}-${threadId}-${stageSeq++}`;
-}
-export function stageOwnerPidFromName(name) {
-    if (!STAGE_TMP_PATTERN.test(name))
-        return undefined;
-    const match = STAGE_TMP_PID_PATTERN.exec(name);
-    if (!match)
-        return undefined;
-    const pid = Number(match[1]);
-    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
-}
-export async function sweepOwnStagingFiles(directories, options) {
-    const uniqueDirectories = [...new Set(directories)].filter(Boolean);
-    const result = {
-        directories: uniqueDirectories.length,
-        scanned: 0,
-        removed: 0,
-        liveSkipped: 0,
-        truncated: false,
-    };
-    for (const directory of uniqueDirectories) {
-        let handle;
-        try {
-            handle = await fs.promises.opendir(directory);
-        }
-        catch {
-            continue;
-        }
-        try {
-            let reachedEntryCap = true;
-            for (let i = 0; i < options.maxEntries; i++) {
-                const entry = await handle.read();
-                if (entry === null) {
-                    reachedEntryCap = false;
-                    break;
-                }
-                result.scanned++;
-                if (!entry.isFile())
-                    continue;
-                const pid = stageOwnerPidFromName(entry.name);
-                if (pid === undefined)
-                    continue;
-                if (pid === process.pid || options.isPidAlive(pid)) {
-                    result.liveSkipped++;
-                    continue;
-                }
-                try {
-                    await fs.promises.rm(path.join(directory, entry.name), {
-                        force: true,
-                    });
-                    result.removed++;
-                }
-                catch {
-                    /* leave it for the next bounded sweep */
-                }
-            }
-            result.truncated ||= reachedEntryCap;
-        }
-        catch {
-            /* best-effort directory scan */
-        }
-        finally {
-            await handle.close().catch(() => { });
-        }
-    }
-    return result;
-}