jev-agent-tools 0.1.4 → 0.3.0

package/dist/adapters/shell.js

@@ -0,0 +1,92 @@
+import { accessSync, constants } from "node:fs";
+// Candidates are Windows paths whatever the host OS, so the helpers use win32
+// semantics explicitly; the host-native `node:path` splits PATH on ":" on POSIX.
+import { win32 } from "node:path";
+function executable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Windows ships `bash.exe` launchers for WSL in System32 (and SysWOW64,
+ * Sysnative) and in WindowsApps. They run in a Linux VM that cannot see Windows
+ * temporary paths, so they are never used for command evidence, including
+ * when named explicitly in JEV_TOOLS_BASH.
+ */
+export function isWslLauncher(path) {
+    const lower = win32.normalize(path).toLowerCase();
+    return (/\\windows\\(system32|syswow64|sysnative)\\/.test(lower) ||
+        lower.includes("\\microsoft\\windowsapps\\"));
+}
+/** Permitted Git for Windows bash candidates, most specific first. */
+export function windowsBashCandidates(env) {
+    const candidates = [];
+    if (env.JEV_TOOLS_BASH?.trim())
+        candidates.push(env.JEV_TOOLS_BASH.trim());
+    const pathEntries = (env.PATH ?? env.Path ?? "")
+        .split(win32.delimiter)
+        .filter(Boolean);
+    for (const entry of pathEntries) {
+        candidates.push(win32.join(entry, "bash.exe"));
+        // Git\cmd\git.exe or Git\bin\git.exe on PATH implies Git\bin\bash.exe.
+        if (/[\\/](cmd|bin)$/i.test(entry))
+            candidates.push(win32.join(win32.dirname(entry), "bin", "bash.exe"));
+    }
+    for (const root of [
+        env.ProgramFiles,
+        env["ProgramFiles(x86)"],
+        env.LOCALAPPDATA && win32.join(env.LOCALAPPDATA, "Programs"),
+    ])
+        if (root)
+            candidates.push(win32.join(root, "Git", "bin", "bash.exe"));
+    // Filter every source, so no candidate can reintroduce a WSL launcher.
+    return [...new Set(candidates)].filter((candidate) => win32.isAbsolute(candidate) && !isWslLauncher(candidate));
+}
+const UNAVAILABLE = "No permitted bash found: install Git for Windows or set JEV_TOOLS_BASH to the full path of a bash that is not the WSL launcher.";
+/** Never handed to command children: the Jev API key stays with the extension. */
+export const API_KEY_VARIABLE = "JEV_TOOLS_API_KEY";
+/** Copy of `env` without the Jev API key (any case, for Windows). */
+export function withoutApiKey(env) {
+    const copy = { ...env };
+    for (const key of Object.keys(copy))
+        if (key.toUpperCase() === API_KEY_VARIABLE)
+            delete copy[key];
+    return copy;
+}
+let cached;
+/**
+ * POSIX hosts run `env -u JEV_TOOLS_API_KEY CI=1 bash -c`. Windows has no
+ * `env` and its default `bash` is the WSL launcher, so resolve Git for Windows
+ * bash (or JEV_TOOLS_BASH) to an absolute, permitted path, and unset the key
+ * and export CI inside the script. When none is found this fails closed: no
+ * bare name is returned, because spawning one would search PATH again without
+ * the WSL exclusion.
+ */
+export function resolveShell(platform = process.platform, env = process.env, isExecutable = executable) {
+    if (platform !== "win32")
+        return {
+            ok: true,
+            executable: "env",
+            prefix: ["-u", API_KEY_VARIABLE, "CI=1", "bash"],
+            scriptPrefix: "",
+        };
+    const useCache = isExecutable === executable && env === process.env;
+    if (useCache && cached)
+        return cached;
+    const found = windowsBashCandidates(env).find((path) => isExecutable(path));
+    const resolved = found
+        ? {
+            ok: true,
+            executable: found,
+            prefix: [],
+            scriptPrefix: `unset ${API_KEY_VARIABLE}; export CI=1; `,
+        }
+        : { ok: false, error: UNAVAILABLE };
+    if (useCache && found)
+        cached = resolved;
+    return resolved;
+}

package/dist/adapters/syntax.js

@@ -0,0 +1,187 @@
+let parserPromise;
+/** Optional grammars resolve from this extension, not the repository under review. */
+export function loadSyntaxParser() {
+    parserPromise ??= createParser();
+    return parserPromise;
+}
+/** Raw AST access shares grammar availability and registration with declaration extraction. */
+export function loadSyntaxRootParser() {
+    parserPromise ??= createParser();
+    return parserPromise;
+}
+async function createParser() {
+    try {
+        const napi = await import("@ast-grep/napi");
+        let python = false;
+        try {
+            const language = await import("@ast-grep/lang-python");
+            napi.registerDynamicLanguage({ python: language.default });
+            python = true;
+        }
+        catch {
+            /* buildUnits reports the missing grammar for each affected file. */
+        }
+        const parser = {
+            supports: (path) => /\.[cm]?[jt]sx?$/.test(path) || (python && path.endsWith(".py")),
+            parseRaw(path, text) {
+                try {
+                    const language = path.endsWith(".py")
+                        ? "python"
+                        : /\.[cm]?tsx?$/.test(path)
+                            ? path.endsWith("tsx")
+                                ? napi.Lang.Tsx
+                                : napi.Lang.TypeScript
+                            : path.endsWith(".jsx")
+                                ? "jsx"
+                                : napi.Lang.JavaScript;
+                    const root = napi.parse(language, text).root();
+                    return { ok: true, root };
+                }
+                catch {
+                    return { ok: false, error: "Source parser unavailable" };
+                }
+            },
+            parse(path, text) {
+                const parsed = this.parseRaw(path, text);
+                if (!parsed.ok)
+                    return parsed;
+                return parsed.root.find({ rule: { kind: "ERROR" } })
+                    ? { ok: false, error: "Source syntax incomplete" }
+                    : parsed;
+            },
+            declarations(path, text, options) {
+                const isPython = path.endsWith(".py");
+                const parsed = this.parseRaw(path, text);
+                if (!parsed.ok)
+                    return { declarations: [], limits: [{ kind: "parse_failed" }] };
+                const root = parsed.root;
+                const result = [];
+                const limits = [];
+                const errors = root.findAll({ rule: { kind: "ERROR" } });
+                const declarationKind = /^(?:function_declaration|generator_function_declaration|method_definition|function_definition|lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration|class_declaration|class_definition)$/;
+                if (errors.some((error) => !error
+                    .ancestors()
+                    .some((node) => declarationKind.test(String(node.kind()))) &&
+                    (error
+                        .findAll({ rule: { regex: ".*" } })
+                        .some((node) => declarationKind.test(String(node.kind()))) ||
+                        /^(?:export\s+)?(?:function|const|let|var|class)\b/.test(error.text().trim()))))
+                    return { declarations: [], limits: [{ kind: "parse_failed" }] };
+                const attributedErrors = new Set();
+                const source = text.split("\n");
+                const visit = (node) => {
+                    const kind = String(node.kind());
+                    // Most AST nodes cannot yield a declaration; avoid constructing their ancestor chains.
+                    if (!/^(?:function_declaration|generator_function_declaration|method_definition|function_definition|lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration|expression_statement|class_declaration|class_definition)$/.test(kind)) {
+                        for (const child of node.children())
+                            visit(child);
+                        return;
+                    }
+                    const ancestors = node.ancestors();
+                    const functionNode = /^(?:function_declaration|generator_function_declaration|method_definition|function_definition)$/.test(kind);
+                    const variable = /^(?:lexical_declaration|variable_declaration|type_alias_declaration|interface_declaration|enum_declaration)$/.test(kind) &&
+                        ancestors.every((a) => !/function|method|statement_block/.test(String(a.kind())));
+                    const callableVariable = variable &&
+                        node.find({
+                            rule: {
+                                any: [
+                                    { kind: "arrow_function" },
+                                    { kind: "function_expression" },
+                                ],
+                            },
+                        }) !== null;
+                    const assignment = isPython &&
+                        kind === "expression_statement" &&
+                        node.parent()?.kind() === "module" &&
+                        node.children().some((child) => child.kind() === "assignment");
+                    const classNode = options?.descendAbove !== undefined &&
+                        /^(?:class_declaration|class_definition)$/.test(kind);
+                    if (functionNode || variable || assignment || classNode) {
+                        let envelope = node;
+                        if (node.parent()?.kind() === "decorated_definition" ||
+                            node.parent()?.kind() === "export_statement")
+                            envelope = node.parent() ?? node;
+                        const named = node.field("name") ?? node.find({ rule: { kind: "identifier" } });
+                        const owner = ancestors
+                            .filter((a) => /^(?:class_definition|class_declaration|internal_module|module)$/.test(String(a.kind())))
+                            .reverse()
+                            .map((a) => a.field("name")?.text())
+                            .filter(Boolean);
+                        let name = [...owner, named?.text() ?? "declaration"].join(".");
+                        if (assignment)
+                            name = node.text().split(/\s*[:=]/, 1)[0] ?? "declaration";
+                        let start = envelope.range().start.line;
+                        const body = node.field("body") ??
+                            (callableVariable
+                                ? node
+                                    .find({
+                                    rule: {
+                                        any: [
+                                            { kind: "arrow_function" },
+                                            { kind: "function_expression" },
+                                        ],
+                                    },
+                                })
+                                    ?.field("body")
+                                : null);
+                        const tokens = (part) => {
+                            const children = part.children();
+                            if (!children.length ||
+                                /string|comment/.test(String(part.kind())))
+                                return part.kind() === "comment" ? [] : [part.text()];
+                            return children.flatMap(tokens);
+                        };
+                        const accessor = kind === "method_definition"
+                            ? node
+                                .children()
+                                .find((child) => /^(get|set)$/.test(String(child.kind())))
+                                ?.kind()
+                            : undefined;
+                        const end = envelope.range().end;
+                        // Include the immediately preceding comment block without swallowing another declaration.
+                        while (start > 0 &&
+                            /^\s*(?:\/\/|\/\*|\*|\*\/|#)/.test(source[start - 1] ?? ""))
+                            start--;
+                        result.push({
+                            kind: functionNode || callableVariable ? "function" : "declaration",
+                            name,
+                            type: accessor ? `${kind}:${accessor}` : kind,
+                            signatureEnd: body
+                                ? body.range().start.line + (isPython ? 0 : 1)
+                                : undefined,
+                            body: body ? JSON.stringify(tokens(body)) : undefined,
+                            exported: isPython
+                                ? !name.split(".").some((part) => part.startsWith("_"))
+                                : ancestors.some((a) => a.kind() === "export_statement") ||
+                                    envelope.kind() === "export_statement",
+                            start: start + 1,
+                            end: end.line + (end.column === 0 ? 0 : 1),
+                        });
+                        const declarationErrors = envelope.findAll({
+                            rule: { kind: "ERROR" },
+                        });
+                        if (declarationErrors.length) {
+                            limits.push({ kind: "parse_partial", declaration: name });
+                            for (const error of declarationErrors)
+                                attributedErrors.add(error.id());
+                        }
+                        if (options?.descendAbove === undefined ||
+                            end.line + (end.column === 0 ? 0 : 1) - start <=
+                                options.descendAbove)
+                            return;
+                    }
+                    for (const child of node.children())
+                        visit(child);
+                };
+                visit(root);
+                if (errors.some((error) => !attributedErrors.has(error.id())))
+                    limits.push({ kind: "parse_partial" });
+                return { declarations: result, limits };
+            },
+        };
+        return parser;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/test-inventory.js

@@ -0,0 +1,139 @@
+import { lstat } from "node:fs/promises";
+import { TEST_SOURCE_MAX_BYTES, TIMEOUT_MS } from "../constants.js";
+import { isSecretPath } from "../core/secret-path.js";
+import { checkFileAdmission, openRepoFile, resolveInsideRepo, } from "./files.js";
+import { decodeUtf8 } from "./utf8.js";
+export async function collectTestInventory(exec, cwd, signal) {
+    const root = await exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd,
+        timeout: TIMEOUT_MS,
+        signal,
+    });
+    if (root.code !== 0 || root.killed)
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: root.stderr || "Cannot identify repository root.",
+        };
+    cwd = root.stdout.replace(/\n$/, "");
+    const listed = await exec("git", [
+        "ls-files",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+        "--full-name",
+        "-z",
+    ], { cwd, timeout: TIMEOUT_MS, signal });
+    if (listed.code !== 0 || listed.killed)
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: listed.stderr || "Cannot inventory repository files.",
+        };
+    const ignored = await exec("git", ["ls-files", "--cached", "--ignored", "--exclude-standard", "-z"], { cwd, timeout: TIMEOUT_MS, signal });
+    if (ignored.code !== 0 || ignored.killed)
+        return {
+            ok: false,
+            cause: signal?.aborted ? "cancelled" : "git_failure",
+            error: ignored.stderr || "Cannot identify ignored tracked files.",
+        };
+    const excluded = new Set(ignored.stdout.split("\0").filter(Boolean));
+    const listedPaths = listed.stdout
+        .split("\0")
+        .filter((path) => path &&
+        (!excluded.has(path) ||
+            /(?:^|\/)(?:package|tsconfig[^/]*)\.json$/.test(path)));
+    // Secret-named files are named exclusions, never inventory members to read.
+    const paths = listedPaths.filter((path) => !isSecretPath(path));
+    const admitted = new Set(paths);
+    const limits = listedPaths
+        .filter(isSecretPath)
+        .map((path) => ({ path, kind: "secret_pattern" }));
+    const cache = new Map();
+    for (let offset = 0; offset < paths.length; offset += 16) {
+        const inspected = await Promise.all(paths.slice(offset, offset + 16).map(async (path) => {
+            try {
+                signal?.throwIfAborted();
+                const admission = await checkFileAdmission(cwd, path, exec, signal, admitted);
+                if (!admission.ok)
+                    return "unreadable";
+                const resolved = await resolveInsideRepo(cwd, path);
+                if (!resolved.ok)
+                    return "unreadable";
+                const stat = await lstat(resolved.abs);
+                if (!stat.isFile())
+                    return "unreadable";
+                return stat.size > TEST_SOURCE_MAX_BYTES
+                    ? "too_large"
+                    : undefined;
+            }
+            catch {
+                return "unreadable";
+            }
+        }));
+        for (const [index, kind] of inspected.entries()) {
+            if (!kind)
+                continue;
+            const path = paths[offset + index];
+            if (path === undefined || cache.has(path))
+                continue;
+            limits.push({ path, kind });
+            cache.set(path, Promise.resolve(undefined));
+        }
+    }
+    const read = (path) => {
+        const cached = cache.get(path);
+        if (cached)
+            return cached;
+        const pending = (async () => {
+            let handle;
+            try {
+                signal?.throwIfAborted();
+                const opened = await openRepoFile(cwd, path, {
+                    exec,
+                    signal,
+                    inventory: admitted,
+                });
+                if (!opened.ok)
+                    return { path, kind: "unreadable" };
+                handle = opened.handle;
+                const stat = { size: opened.size };
+                if (stat.size > TEST_SOURCE_MAX_BYTES)
+                    return { path, kind: "too_large" };
+                const bytes = Buffer.alloc(Math.min(stat.size + 1, TEST_SOURCE_MAX_BYTES + 1));
+                let count = 0;
+                while (count < bytes.length) {
+                    signal?.throwIfAborted();
+                    const part = await handle.read(bytes, count, bytes.length - count, null);
+                    if (!part.bytesRead)
+                        break;
+                    count += part.bytesRead;
+                }
+                if (count === bytes.length)
+                    return { path, kind: "too_large" };
+                if (bytes.subarray(0, count).includes(0))
+                    return { path, text: "" };
+                const decoded = decodeUtf8(bytes.subarray(0, count));
+                if (!decoded.ok)
+                    return { path, kind: "not UTF-8 text" };
+                const text = decoded.text;
+                return { path, text };
+            }
+            catch {
+                return { path, kind: "unreadable" };
+            }
+            finally {
+                await handle?.close();
+            }
+        })().then((file) => {
+            if (file.kind) {
+                limits.push({ path: file.path, kind: file.kind });
+                return undefined;
+            }
+            return { path: file.path, text: file.text };
+        });
+        cache.set(path, pending);
+        return pending;
+    };
+    return { ok: true, cwd, paths, read, limits };
+}

package/dist/adapters/usage.js

@@ -0,0 +1,20 @@
+export function hostUsage(isOmp, usage) {
+    if (isOmp || !usage)
+        return {};
+    return {
+        usage: {
+            input: usage.inputTokens,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: usage.inputTokens,
+            cost: {
+                input: usage.costUsd,
+                output: 0,
+                cacheRead: 0,
+                cacheWrite: 0,
+                total: usage.costUsd,
+            },
+        },
+    };
+}

package/dist/adapters/utf8.js

@@ -0,0 +1,47 @@
+import { isUtf8 } from "node:buffer";
+import { createHash } from "node:crypto";
+/** Callers enforce byte budgets before decoding. BOM and legitimate controls are preserved. */
+export function decodeUtf8(bytes) {
+    return isUtf8(bytes)
+        ? {
+            ok: true,
+            text: Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("utf8"),
+        }
+        : { ok: false, error: "not UTF-8 text" };
+}
+/** Keep incomplete code points between chunks, but reject them at EOF. */
+export function createUtf8Decoder() {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+    return (bytes) => {
+        try {
+            return {
+                ok: true,
+                text: decoder.decode(bytes, { stream: bytes !== undefined }),
+            };
+        }
+        catch {
+            return { ok: false, error: "not UTF-8 text" };
+        }
+    };
+}
+/** Verify host-decoded text against the raw Git object; replacement cannot silently become evidence. */
+export function verifyGitUtf8(text, id, size) {
+    const bytes = Buffer.from(text, "utf8");
+    if (size !== undefined && bytes.length !== size)
+        return { ok: false, error: "not UTF-8 text" };
+    if (id && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(id)) {
+        const actual = createHash(id.length === 64 ? "sha256" : "sha1")
+            .update(`blob ${bytes.length}\0`)
+            .update(bytes)
+            .digest("hex");
+        if (actual !== id)
+            return { ok: false, error: "not UTF-8 text" };
+    }
+    else if (text.includes("\uFFFD")) {
+        return {
+            ok: false,
+            error: "not verifiable as UTF-8 text (contains U+FFFD after host decoding)",
+        };
+    }
+    return decodeUtf8(bytes);
+}