pi-ast-sgrep 1.3.2 → 1.4.0

package/README.md

@@ -1,48 +1,212 @@
 # pi-ast-sgrep
 
-[![ast-sgrep for Pi](assets/preview.png)](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/pi-package.md)
+Native Code Mode, structural, graph, and semantic code search for [Pi](https://github.com/earendil-works/pi).
 
-Native intent, structural, definition, caller, chain, and semantic code search for Pi.
+[![pi-ast-sgrep: native code search inside Pi](https://cdn.jsdelivr.net/npm/pi-ast-sgrep/assets/preview.png)](https://pi.dev/packages/pi-ast-sgrep?name=pi-ast-sgrep)
+
+`pi-ast-sgrep` gives Pi a warm, project-aware search engine for understanding code. It finds behavior by intent, resolves definitions and callers, traces relationships, matches syntax-aware patterns, and searches local semantic embeddings. The primary `asgrep_codemode` tool lets Pi compose several searches in one JavaScript program instead of spending one model round trip per lookup.
+
+## Install
 
 ```bash
 pi install npm:pi-ast-sgrep
 ```
 
-Requires Node.js `>=22.19.0`, Pi `>=0.80.6 <1`, and a packaged host: macOS arm64/x64, glibc Linux arm64/x64, or Windows x64. The extension, `ast-sgrep` launcher, and selected native package manifests are exact-version matched at `1.3.2`; the embedded CLI compatibility identity is `1.3.2`. Alpine/musl, Windows arm64, and other hosts fail with an actionable unsupported-platform error; there is no source build or runtime download fallback.
+Restart Pi if the current session does not load newly installed package resources. For a project-local installation, add `-l`:
+
+```bash
+pi install -l npm:pi-ast-sgrep
+```
+
+No Rust toolchain or separate MCP server is required. The npm package selects the native binary and in-process addon for the current supported platform.
+
+## What this package adds
+
+| Resource | Purpose |
+|---|---|
+| `asgrep_codemode` | Primary tool. Run a bounded JavaScript program that composes typed `asgrep.*` calls. |
+| `asgrep_search` | Run one natural, structural, symbol, graph, semantic, word, literal, or regex lookup. |
+| `asgrep_index` | Create, refresh, or explicitly rebuild the current project index. |
+| `asgrep_status` | Inspect the selected root, index, backend, counts, and capabilities. |
+| `ast-sgrep` skill | Teach Pi when and how to use Code Mode, direct search, or exact-text search. |
 
-## First use
+The package also registers `/asgrep-doctor`, `/asgrep-status`, `/asgrep-index`, and `/asgrep-reindex`.
 
-The package registers:
+## Start with Code Mode
 
-- `asgrep_search`, `asgrep_index`, and `asgrep_status` tools;
-- `/asgrep-doctor`, `/asgrep-status`, `/asgrep-index`, and `/asgrep-reindex` commands;
-- the `ast-sgrep` skill.
+Ask Pi:
 
-Open Pi in a project and search. The first search lazily creates `.asgrep/`. Examples for `asgrep_search`:
+> Use ast-sgrep Code Mode to find where access tokens are refreshed, trace the top result's callers, and return only the relevant files, symbols, and lines.
+
+Pi can make one `asgrep_codemode` call like this:
 
 ```json
-{"query":"auth_refresh","mode":"defs"}
-{"query":"auth_refresh","mode":"callers"}
-{"query":"where are credentials renewed?","mode":"semantic"}
+{
+  "code": "async () => {\n  const seed = await asgrep.search({ query: 'where are access tokens refreshed?', limit: 5 });\n  const symbol = seed.hits?.[0]?.symbol;\n  if (!symbol) return { seed };\n  const [defs, callers] = await Promise.all([\n    asgrep.defs({ symbol, limit: 5 }),\n    asgrep.callers({ symbol, limit: 10 }),\n  ]);\n  return { symbol, defs: defs.hits, callers: callers.hits };\n}"
+}
+```
+
+This workflow narrows the first result, runs independent follow-up searches together, and returns a small shaped value to the model.
+
+### Code Mode API
+
+The sandbox exposes these asynchronous methods:
+
+| Method | Use |
+|---|---|
+| `asgrep.search({ query, limit?, excerptLines? })` | Search by intent, symbol, or a prefixed structural query. |
+| `asgrep.semantic({ query, limit?, excerptLines? })` | Search local semantic embeddings directly. |
+| `asgrep.defs({ symbol, limit? })` | Find definitions for one symbol. |
+| `asgrep.callers({ symbol, limit? })` | Find call sites for one symbol. |
+| `asgrep.imports({ module, limit? })` | Find imports of one module. |
+| `asgrep.chain({ query, limit? })` | Trace related symbols and graph edges. |
+| `asgrep.indexStatus()` | Read index and backend state. |
+| `asgrep.indexRepo({ force? })` | Create, refresh, or rebuild the index. |
+| `asgrep.catalogSearch({ query })` | Discover less common ast-sgrep operations. |
+| `asgrep.catalogDescribe({ name })` | Read the schema for a discovered operation. |
+
+Use `Promise.all` for independent calls. Filter, map, sort, and slice intermediate values in JavaScript. Return only the evidence needed for the next reasoning step.
+
+Code Mode includes `Promise`, `JSON`, arrays, objects, `Map`, `Set`, and `Math`. It does not expose `require`, `process`, `fetch`, or filesystem APIs. This is a capability boundary for generated code, not an OS sandbox for the installed Pi package.
+
+## Direct one-shot search
+
+Use `asgrep_search` when one lookup is enough:
+
+```json
+{"query":"auth_refresh","mode":"defs","limit":8}
+{"query":"auth_refresh","mode":"callers","limit":8}
+{"query":"where are credentials renewed?","mode":"semantic","limit":8}
+{"query":"$CLIENT.post($URL)","mode":"pattern","limit":8}
+```
+
+Available modes:
+
+| Mode | Best for |
+|---|---|
+| `natural` | Intent or mixed code-language queries when exact spelling is unknown. |
+| `pattern` | Syntax-aware ast-sgrep patterns with metavariables. |
+| `defs`, `callers`, `imports` | Symbol and module navigation. |
+| `chain` | Multi-hop relationship tracing. |
+| `semantic` | Meaning-based local vector search. |
+| `word`, `literal`, `regex` | Explicit text-oriented matching. |
+
+`limit` accepts 1–100 and defaults to 8. Excerpts are disabled by default; set `excerptLines` only after narrowing the result set.
+
+## Why Code Mode is fast
+
+Official platform packages include `ast-sgrep-codemode.node`. The extension loads an in-process native `CodeModeSession` and keeps one warm Searcher per project root for Code Mode, direct tools, and freshness checks. Normal searches do not spawn a CLI process.
+
+Independent calls created in the same JavaScript turn are coalesced into a batch. `Promise.all` can therefore fan out several lookups while the model makes one tool call. If the native addon is unavailable, the bundled CLI service is a degraded fallback; `/asgrep-doctor` reports the active backend.
+
+Code Mode and `ast-sgrep-mcp` are separate front ends over the same Rust search core. Pi uses Code Mode directly and does not use an MCP adapter.
+
+## Indexing and freshness
+
+Start Pi in the repository you want to search. The first search validates the index and lazily creates `<project-root>/.asgrep/` when needed. Run `/asgrep-index` if you want to build it before searching.
+
+After a successful Pi `write` or `edit`, the extension marks the affected path dirty and refreshes it before the next search. Concurrent searches for the same root share one in-flight refresh. Use `/asgrep-reindex` only for an incompatible or corrupt index, or when you explicitly need a full rebuild.
+
+The package never edits `.gitignore`. Add this entry yourself if index data must stay untracked:
+
+```gitignore
+.asgrep/
 ```
 
-Run `/asgrep-doctor` to diagnose the runtime, binary, protocol, index, or configuration; run `/asgrep-status` to inspect the current project. The extension refreshes successful Pi write/edit changes before the next search and coalesces concurrent refreshes.
+## Commands
+
+| Command | Action |
+|---|---|
+| `/asgrep-doctor` | Check package versions, native runtime, protocol, index, and project settings. |
+| `/asgrep-status` | Show the current root and index state. |
+| `/asgrep-index` | Create or incrementally refresh the index. |
+| `/asgrep-reindex` | Build and atomically replace the index from scratch. |
+
+These commands take no arguments.
+
+## Requirements
+
+- Node.js `>=22.19.0`.
+- Pi currently tested with `@earendil-works/pi-coding-agent >=0.80.6 <1`.
+- macOS arm64 or x64, glibc Linux arm64 or x64, or Windows x64.
+
+Alpine/musl Linux, Windows arm64, and other hosts are not packaged. The package does not compile Rust, search `PATH`, or download executables at runtime. On an unsupported host, run `/asgrep-doctor` for the exact platform error.
+
+The extension, `ast-sgrep` launcher, platform package, native addon, and embedded CLI are exact-version matched. Update or reinstall the complete package if doctor reports a version or protocol mismatch.
+
+## Typed Code Mode API
+
+Import the search-only programmatic surface from `pi-ast-sgrep/code-mode` and execute related lookups in one typed plan:
+
+```ts
+import { AstSgrepRuntime } from "pi-ast-sgrep/runtime";
+import { createSgrepCodeMode } from "pi-ast-sgrep/code-mode";
+
+const mode = createSgrepCodeMode(new AstSgrepRuntime(pi), { cwd: process.cwd() });
+const result = await mode.execute(async (sgrep) => {
+  const [text, ast, semantic] = await Promise.all([
+    sgrep.keywordSearch("refresh token"),
+    sgrep.astSearch("function_declaration"),
+    sgrep.semanticSearch("credential renewal"),
+  ]);
+  const bodies = await sgrep.codeRead(text.hits.slice(0, 3), { contextLines: 2 });
+  return { text, ast, semantic, bodies };
+});
+```
+
+- `keywordSearch` runs lexical retrieval only.
+- `astSearch` runs `pattern:` structural search only.
+- `semanticSearch` runs embedding retrieval only.
+- `codeRead` streams bounded `file#Lx-Ly` refs inside the project, including adjacent context, symlink containment, strict UTF-8 validation, cancellation, and an aggregate output budget.
+- `find`, `astFind`, `semantic`, and `read` remain typed aliases for the four methods above.
+
+The agent chooses the retrieval granularity; these methods never auto-fuse channels. One-shot CLI search retains fusion for human/direct engine use. The API exposes no rewrite or mutation operation. Structural rewrites remain delegated to ast-grep. Search responses retain signal, contributor, score, and margin provenance.
 
 ## Local by default
 
-Local semantic indexing/search works offline with no credential, telemetry, first-use model download, executable download, PATH lookup, or MCP adapter. Optional external embedding providers are opt-in and may receive the source text and queries needed to create embeddings.
+The default semantic backend works offline. It needs no credential, sends no telemetry, and downloads no model on first use. Search data stays under the project's `.asgrep/` directory.
+
+External cloud, Ollama, and neural embedding providers are optional. If you enable one, source text and queries needed for embeddings can be sent to that provider. Its credential, retention, and privacy rules then apply.
+
+Pi packages are trusted code. Installation grants this JavaScript extension and its native code the permissions of the OS user running Pi. Project-root confinement is a package policy, not an operating-system security boundary.
+
+## Configuration
+
+Defaults are a 30-second operation timeout, 4 MiB output limit, and 30-second freshness interval. Supported environment settings are:
+
+| Setting | Purpose |
+|---|---|
+| `ASGREP_ROOT` | Select the project root. |
+| `ASGREP_TIMEOUT_MS` | Set the native operation timeout. |
+| `ASGREP_MAX_OUTPUT_BYTES` | Bound native output. |
+| `ASGREP_REFRESH_INTERVAL_MS` | Set the idle freshness-check interval. |
+| `ASGREP_BIN` | Override the packaged binary for development. |
 
-Indexing writes database, embedding, metadata, and lock/rebuild files under the project's `.asgrep/`. The package never edits `.gitignore`; add `.asgrep/` yourself if you do not want it committed. Pi packages run with the OS user's full access and are not sandboxed.
+Explicit project configuration can opt into `allowOutsideProject`; global settings and environment variables cannot relax the default project boundary. See the [complete package guide](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/pi-package.md) for schema and precedence details.
 
-## Update or remove
+## Update, rollback, or remove
 
 ```bash
 pi update npm:pi-ast-sgrep
 pi remove npm:pi-ast-sgrep
 ```
 
-Removal preserves every project's `.asgrep` data for reinstall or rollback. Delete that directory separately and explicitly only when you no longer need it. Compatible updates reuse validated data; incompatible formats rebuild atomically and preserve recoverable prior data on failure. Roll back by removing the package and installing `npm:pi-ast-sgrep@<previous-version>`, then run `/asgrep-doctor`.
+Removal preserves each project's `.asgrep/` data for reinstall or rollback. Delete that directory separately only when you no longer need the index.
+
+To roll back, install one prior version as a matched unit:
+
+```bash
+pi remove npm:pi-ast-sgrep
+pi install npm:pi-ast-sgrep@<previous-version>
+```
+
+Then run `/asgrep-doctor`. Compatible updates reuse validated data. Incompatible formats rebuild atomically and preserve recoverable prior data when a rebuild fails.
+
+## More documentation
 
-Read the [complete install, configuration, security, recovery, and uninstall guide](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/pi-package.md). Release provenance and package order are documented in [RELEASING.md](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/RELEASING.md).
+- [Complete Pi package guide](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/pi-package.md)
+- [Code Mode architecture and performance](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/codemode.md)
+- [Query grammar](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/QUERY_GRAMMAR.md)
+- [Release provenance](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/RELEASING.md)
 
 MIT

package/dist/code-mode.d.ts

@@ -0,0 +1,81 @@
+import { type AstSgrepRuntime, type MachineEnvelope, type RunOptions, type RuntimeContext } from "./runtime.js";
+export type SgrepKind = "asgrep" | "def" | "caller" | "graph" | "anchor" | "import" | "pattern" | "embed";
+export type SgrepSignal = "exact" | "structural" | "semantic";
+export type SgrepRef = `${string}#L${number}-L${number}`;
+export interface SgrepHit {
+    kind: SgrepKind;
+    signal: SgrepSignal;
+    contributors: SgrepKind[];
+    score: number;
+    margin: number;
+    file: string;
+    lines: {
+        start: number;
+        end: number;
+    };
+    ref: SgrepRef;
+    preview: string;
+    symbol?: string | null;
+    caller?: string | null;
+    callee?: string | null;
+    language?: string | null;
+    excerpt?: string;
+}
+export interface SgrepSearchResponse extends MachineEnvelope {
+    hits: SgrepHit[];
+    query?: string;
+    hit_count?: number;
+}
+export interface SgrepSearchOptions extends RunOptions {
+    limit?: number;
+    excerptLines?: number;
+}
+export interface SgrepReadOptions {
+    contextLines?: number;
+    /** Aggregate character budget across all refs. */
+    maxChars?: number;
+    signal?: AbortSignal;
+}
+export interface SgrepReadResult {
+    ref: SgrepRef;
+    file: string;
+    lines: {
+        start: number;
+        end: number;
+    };
+    content: string;
+    truncated: boolean;
+}
+export interface SgrepApi {
+    keywordSearch(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    astSearch(pattern: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    semanticSearch(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    codeRead(ids: SgrepRef | Pick<SgrepHit, "ref"> | readonly (SgrepRef | Pick<SgrepHit, "ref">)[], options?: SgrepReadOptions): Promise<SgrepReadResult[]>;
+    /** Alias for keywordSearch. */
+    find(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    /** Alias for astSearch. */
+    astFind(pattern: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    /** Alias for semanticSearch. */
+    semantic(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    /** Alias for codeRead. */
+    read(ids: SgrepRef | Pick<SgrepHit, "ref"> | readonly (SgrepRef | Pick<SgrepHit, "ref">)[], options?: SgrepReadOptions): Promise<SgrepReadResult[]>;
+}
+export type SgrepPlan<T> = (sgrep: Readonly<SgrepApi>) => T | Promise<T>;
+type RuntimeLike = Pick<AstSgrepRuntime, "run" | "resolveRoot">;
+export declare class SgrepCodeMode implements SgrepApi {
+    #private;
+    private readonly runtime;
+    private readonly context;
+    constructor(runtime: RuntimeLike, context: RuntimeContext);
+    execute<T>(plan: SgrepPlan<T>): Promise<T>;
+    keywordSearch(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    astSearch(pattern: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    semanticSearch(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    find(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    astFind(pattern: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    semantic(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
+    codeRead(ids: SgrepRef | Pick<SgrepHit, "ref"> | readonly (SgrepRef | Pick<SgrepHit, "ref">)[], options?: SgrepReadOptions): Promise<SgrepReadResult[]>;
+    read(ids: SgrepRef | Pick<SgrepHit, "ref"> | readonly (SgrepRef | Pick<SgrepHit, "ref">)[], options?: SgrepReadOptions): Promise<SgrepReadResult[]>;
+}
+export declare function createSgrepCodeMode(runtime: RuntimeLike, context: RuntimeContext): SgrepCodeMode;
+export {};

package/dist/code-mode.js

@@ -0,0 +1,348 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { RuntimeError } from "./runtime.js";
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const MAX_EXCERPT_LINES = 100;
+const DEFAULT_MAX_READ_CHARS = 100_000;
+const MAX_READ_CHARS = 1_000_000;
+const MAX_READ_REFS = 20;
+const MAX_SCAN_BYTES = 64 * 1024 * 1024;
+const MAX_LINE_NUMBER = 0xffff_ffff;
+const REF_PATTERN = /^(.+?)#L([1-9]\d*)-L([1-9]\d*)$/;
+const KINDS = new Set(["asgrep", "def", "caller", "graph", "anchor", "import", "pattern", "embed"]);
+const SIGNALS = new Set(["exact", "structural", "semantic"]);
+function boundedInteger(value, fallback, minimum, maximum, name) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+        throw new RuntimeError("INVALID_ARGUMENT", `${name} must be an integer from ${minimum} to ${maximum}`);
+    }
+    return value;
+}
+function requiredText(value, name) {
+    if (typeof value !== "string" || value.trim().length === 0 || value.length > 4_096) {
+        throw new RuntimeError("INVALID_ARGUMENT", `${name} must contain 1 to 4096 characters`);
+    }
+    return value.trim();
+}
+function outputArgs(options) {
+    return [
+        "--json",
+        "--format",
+        "agent-capsule",
+        "--limit",
+        String(boundedInteger(options.limit, DEFAULT_LIMIT, 1, MAX_LIMIT, "limit")),
+        "--excerpt-lines",
+        String(boundedInteger(options.excerptLines, 0, 0, MAX_EXCERPT_LINES, "excerptLines")),
+    ];
+}
+function asSearchResponse(value) {
+    if (value.ok !== true || !Array.isArray(value.hits)) {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response is missing hits");
+    }
+    if (value.query !== undefined && typeof value.query !== "string") {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response has an invalid query");
+    }
+    if (value.hit_count !== undefined
+        && (typeof value.hit_count !== "number" || !Number.isSafeInteger(value.hit_count)
+            || value.hit_count < 0 || value.hit_count !== value.hits.length)) {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response has an invalid hit_count");
+    }
+    const optionalText = (field) => field === undefined || field === null || typeof field === "string";
+    for (const candidate of value.hits) {
+        if (!candidate || typeof candidate !== "object") {
+            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+        }
+        const hit = candidate;
+        const lines = hit.lines;
+        const validLines = !!lines && typeof lines === "object"
+            && Number.isSafeInteger(lines.start)
+            && Number.isSafeInteger(lines.end)
+            && Number(lines.start) > 0
+            && Number(lines.end) >= Number(lines.start);
+        const valid = typeof hit.kind === "string" && KINDS.has(hit.kind)
+            && typeof hit.signal === "string" && SIGNALS.has(hit.signal)
+            && Array.isArray(hit.contributors) && hit.contributors.length > 0
+            && hit.contributors.every((kind) => typeof kind === "string" && KINDS.has(kind))
+            && typeof hit.score === "number" && Number.isFinite(hit.score)
+            && typeof hit.margin === "number" && Number.isFinite(hit.margin) && hit.margin >= 0
+            && typeof hit.file === "string" && hit.file.length > 0 && !isAbsolute(hit.file)
+            && validLines
+            && typeof hit.ref === "string"
+            && typeof hit.preview === "string"
+            && optionalText(hit.symbol) && optionalText(hit.caller) && optionalText(hit.callee)
+            && optionalText(hit.language) && optionalText(hit.excerpt);
+        if (!valid)
+            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+        const parsed = parseRef(hit.ref);
+        const hitLines = lines;
+        if (parsed.file !== hit.file || parsed.start !== hitLines.start || parsed.end !== hitLines.end) {
+            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep hit ref does not match its file and lines");
+        }
+    }
+    return value;
+}
+function refValue(value) {
+    return typeof value === "string" ? value : value.ref;
+}
+function parseRef(ref) {
+    const match = REF_PATTERN.exec(ref);
+    if (!match)
+        throw new RuntimeError("INVALID_REF", `Invalid ast-sgrep ref: ${ref}`);
+    const file = match[1];
+    const start = Number(match[2]);
+    const end = Number(match[3]);
+    if (isAbsolute(file) || !Number.isSafeInteger(start) || !Number.isSafeInteger(end)
+        || start > MAX_LINE_NUMBER || end > MAX_LINE_NUMBER || end < start) {
+        throw new RuntimeError("INVALID_REF", `Invalid ast-sgrep ref: ${ref}`);
+    }
+    return { file, start, end };
+}
+function inside(root, path) {
+    const rel = relative(root, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function checkAbort(signal) {
+    if (signal?.aborted)
+        throw new RuntimeError("CANCELLED", "ast-sgrep read was cancelled");
+}
+function boundedPrefix(value, maxChars) {
+    let chars = 0;
+    let end = 0;
+    for (const codePoint of value) {
+        if (chars >= maxChars)
+            return { text: value.slice(0, end), chars, truncated: true };
+        end += codePoint.length;
+        chars += 1;
+    }
+    return { text: value, chars, truncated: false };
+}
+async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
+    const stat = await handle.stat();
+    if (!stat.isFile())
+        throw new RuntimeError("READ_FAILED", `${parsed.file} is not a regular file`);
+    const wantedStart = Math.max(1, parsed.start - contextLines);
+    const wantedEnd = Math.min(MAX_LINE_NUMBER, parsed.end + contextLines);
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const stream = handle.createReadStream({
+        autoClose: false,
+        highWaterMark: 64 * 1024,
+        ...(signal ? { signal } : {}),
+    });
+    let pending = "";
+    let lineNumber = 1;
+    let selectedStart;
+    let selectedEnd;
+    let selectedLines = 0;
+    let content = "";
+    let contentChars = 0;
+    let truncated = false;
+    let rangeComplete = false;
+    let scannedBytes = 0;
+    const consumeLine = (line) => {
+        if (lineNumber >= wantedStart && lineNumber <= wantedEnd) {
+            selectedStart ??= lineNumber;
+            selectedEnd = lineNumber;
+            if (!truncated) {
+                const addition = `${selectedLines > 0 ? "\n" : ""}${line.endsWith("\r") ? line.slice(0, -1) : line}`;
+                const bounded = boundedPrefix(addition, maxChars - contentChars);
+                content += bounded.text;
+                contentChars += bounded.chars;
+                truncated = bounded.truncated;
+            }
+            selectedLines += 1;
+        }
+        if (lineNumber >= wantedEnd)
+            rangeComplete = true;
+        lineNumber += 1;
+    };
+    try {
+        for await (const chunk of stream) {
+            checkAbort(signal);
+            const bytes = chunk;
+            const remainingScan = MAX_SCAN_BYTES - scannedBytes;
+            const scanned = bytes.length > remainingScan + 1
+                ? bytes.subarray(0, remainingScan + 1)
+                : bytes;
+            scannedBytes += scanned.length;
+            try {
+                pending += decoder.decode(scanned, { stream: true });
+            }
+            catch {
+                throw new RuntimeError("BINARY_FILE", `${parsed.file} is not valid UTF-8 text`);
+            }
+            let newline = pending.indexOf("\n");
+            while (newline >= 0) {
+                consumeLine(pending.slice(0, newline));
+                pending = pending.slice(newline + 1);
+                if (rangeComplete)
+                    break;
+                newline = pending.indexOf("\n");
+            }
+            if (rangeComplete)
+                break;
+            if (scannedBytes > MAX_SCAN_BYTES || scanned.length < bytes.length) {
+                throw new RuntimeError("READ_SCAN_LIMIT", `${parsed.file} exceeds the ${MAX_SCAN_BYTES}-byte scan limit`);
+            }
+            if (newline < 0 && lineNumber < wantedStart)
+                pending = "";
+        }
+        if (!rangeComplete) {
+            try {
+                pending += decoder.decode();
+            }
+            catch {
+                throw new RuntimeError("BINARY_FILE", `${parsed.file} is not valid UTF-8 text`);
+            }
+            if (pending.length > 0 || lineNumber === 1)
+                consumeLine(pending);
+        }
+    }
+    catch (cause) {
+        if (signal?.aborted)
+            throw new RuntimeError("CANCELLED", "ast-sgrep read was cancelled");
+        throw cause;
+    }
+    finally {
+        stream.destroy();
+    }
+    checkAbort(signal);
+    if (parsed.start >= lineNumber || parsed.end >= lineNumber) {
+        throw new RuntimeError("RANGE_OUT_OF_BOUNDS", `${parsed.file} has fewer than ${parsed.end} lines`);
+    }
+    return {
+        file: parsed.file,
+        lines: { start: selectedStart ?? wantedStart, end: selectedEnd ?? Math.max(wantedStart, lineNumber - 1) },
+        content,
+        truncated,
+    };
+}
+async function runSearch(runtime, context, command, query, options) {
+    const value = await runtime.run([...outputArgs(options), ...command, "--", query, "."], context, options);
+    return asSearchResponse(value);
+}
+async function resolveReadableFile(root, ref, parsed) {
+    const unresolved = resolve(root, parsed.file);
+    if (!inside(root, unresolved))
+        throw new RuntimeError("PATH_OUTSIDE_ROOT", `Ref escapes the project root: ${ref}`);
+    let filePath;
+    let expectedStat;
+    try {
+        filePath = await realpath(unresolved);
+        expectedStat = await lstat(filePath);
+    }
+    catch (cause) {
+        throw new RuntimeError("READ_FAILED", `Unable to resolve ${parsed.file}`, {
+            ref,
+            cause: cause instanceof Error ? cause.message : String(cause),
+        });
+    }
+    if (!inside(root, filePath))
+        throw new RuntimeError("PATH_OUTSIDE_ROOT", `Ref escapes the project root: ${ref}`);
+    if (!expectedStat.isFile())
+        throw new RuntimeError("READ_FAILED", `${parsed.file} is not a regular file`);
+    return { unresolved, filePath, expectedStat };
+}
+async function openStableHandle(root, ref, fileLabel, unresolved, filePath, expectedStat) {
+    let handle;
+    try {
+        const noFollow = typeof constants.O_NOFOLLOW === "number" ? constants.O_NOFOLLOW : 0;
+        handle = await open(filePath, constants.O_RDONLY | noFollow);
+    }
+    catch (cause) {
+        throw new RuntimeError("READ_FAILED", `Unable to open ${fileLabel}`, {
+            ref,
+            cause: cause instanceof Error ? cause.message : String(cause),
+        });
+    }
+    try {
+        const [actualStat, openedPath] = await Promise.all([handle.stat(), realpath(unresolved)]);
+        if (!inside(root, openedPath) || openedPath !== filePath
+            || actualStat.dev !== expectedStat.dev || actualStat.ino !== expectedStat.ino) {
+            throw new RuntimeError("PATH_CHANGED", `Ref changed while opening: ${ref}`);
+        }
+        return handle;
+    }
+    catch (cause) {
+        await handle.close();
+        throw cause;
+    }
+}
+export class SgrepCodeMode {
+    runtime;
+    context;
+    #api;
+    constructor(runtime, context) {
+        this.runtime = runtime;
+        this.context = context;
+        this.#api = Object.freeze({
+            keywordSearch: this.keywordSearch.bind(this),
+            astSearch: this.astSearch.bind(this),
+            semanticSearch: this.semanticSearch.bind(this),
+            codeRead: this.codeRead.bind(this),
+            find: this.find.bind(this),
+            astFind: this.astFind.bind(this),
+            semantic: this.semantic.bind(this),
+            read: this.read.bind(this),
+        });
+    }
+    async execute(plan) {
+        if (typeof plan !== "function")
+            throw new RuntimeError("INVALID_PLAN", "Code Mode plan must be a function");
+        return await plan(this.#api);
+    }
+    async keywordSearch(query, options = {}) {
+        return runSearch(this.runtime, this.context, ["keyword"], requiredText(query, "query"), options);
+    }
+    async astSearch(pattern, options = {}) {
+        return runSearch(this.runtime, this.context, [], `pattern: ${requiredText(pattern, "pattern")}`, options);
+    }
+    async semanticSearch(query, options = {}) {
+        return runSearch(this.runtime, this.context, ["semantic"], requiredText(query, "query"), options);
+    }
+    async find(query, options) {
+        return this.keywordSearch(query, options);
+    }
+    async astFind(pattern, options) {
+        return this.astSearch(pattern, options);
+    }
+    async semantic(query, options) {
+        return this.semanticSearch(query, options);
+    }
+    async codeRead(ids, options = {}) {
+        const values = Array.isArray(ids) ? ids : [ids];
+        if (values.length === 0 || values.length > MAX_READ_REFS) {
+            throw new RuntimeError("INVALID_ARGUMENT", `read requires 1 to ${MAX_READ_REFS} refs`);
+        }
+        const contextLines = boundedInteger(options.contextLines, 0, 0, 100, "contextLines");
+        const maxChars = boundedInteger(options.maxChars, DEFAULT_MAX_READ_CHARS, 1, MAX_READ_CHARS, "maxChars");
+        const perRefChars = Math.floor(maxChars / values.length);
+        const remainder = maxChars % values.length;
+        checkAbort(options.signal);
+        const root = await realpath(await this.runtime.resolveRoot(this.context));
+        const results = [];
+        for (const [index, value] of values.entries()) {
+            checkAbort(options.signal);
+            const ref = refValue(value);
+            const parsed = parseRef(ref);
+            const { unresolved, filePath, expectedStat } = await resolveReadableFile(root, ref, parsed);
+            const handle = await openStableHandle(root, ref, parsed.file, unresolved, filePath, expectedStat);
+            try {
+                const budget = perRefChars + (index < remainder ? 1 : 0);
+                results.push({ ref, ...await readLineWindow(handle, parsed, contextLines, budget, options.signal) });
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        return results;
+    }
+    async read(ids, options) {
+        return await this.codeRead(ids, options);
+    }
+}
+export function createSgrepCodeMode(runtime, context) {
+    return new SgrepCodeMode(runtime, context);
+}