pi-fovea 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-fovea contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# 👁️ pi-fovea
+
+**A foveated repo-mapping extension for [Pi](https://github.com/earendil-works/pi-coding-agent)**
+
+_Survey, focus, dwell, impact — a budget-capped field of view instead of a folder dump._
+
+<p>
+  <img src="https://raw.githubusercontent.com/monotykamary/pi-fovea/main/media/cover.svg" alt="pi-fovea: a code graph seen through a fovea — hot at the center, collapsed at the rim" width="1100">
+</p>
+
+[![npm version](https://img.shields.io/npm/v/pi-fovea?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/pi-fovea)
+[![checks](https://img.shields.io/github/actions/workflow/status/monotykamary/pi-fovea/test.yml?branch=main&style=for-the-badge&label=checks)](https://github.com/monotykamary/pi-fovea/actions/workflows/test.yml)
+[![pi extension](https://img.shields.io/badge/pi-extension-8b5cf6?style=for-the-badge)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-f4c430?style=for-the-badge)](LICENSE)
+
+</div>
+
+---
+
+Large models have small context. pi-fovea turns a repository into a **heat field** over a cross-language code graph — symbols, files, route anchors — and hands the model exactly `maxTokens` of it at a time, sharp where you look and whole-picture-but-cheap everywhere else. After every edit it silently re-syncs, and only speaks up when the change didn't stay local.
+
+## Why Fovea?
+
+|     | Capability | What it unlocks |
+| :-: | ---------- | --------------- |
+| 🔭 | **Survey** | `fovea_sketch` renders the whole repo as a low-acuity silhouette — feature anchors and basins by mass, never raw file lists. |
+| 🎯 | **Focus** | `fovea_focus` centers on a symbol, route, or env key: hot nodes as signatures, warm nodes as one-liners, periphery collapsed. |
+| ⏱️ | **Dwell** | `fovea_dwell` diffuses longer and returns only the delta. Chebyshev vectors are cached — a new timescale is coefficient recombination, not a re-walk. |
+| 🌡️ | **Impact** | `fovea_impact` predicts the co-change cascade across languages — what a file, symbol, or PR base warms up. |
+| 🩸 | **Turn sync** | After every edit turn the graph re-syncs for free. Anchor shifts and unwatched warmings surface as red flags; stable turns stay silent. |
+| 🪙 | **Token truth** | Budgets are hard caps, not hopes: the renderer fits a monotonic prefix and never exceeds `maxTokens`. |
+
+## How it works
+
+The repo compiles to a typed graph whose edges carry **conductance**: imports are bridges, calls are solid, and shared literals — route paths, env keys — are the cross-language welds, weighted by specificity. Your interest is a heat source `s`; the map the model receives is the heat kernel run for time `t` over the graph Laplacian:
+
+```text
+v(t) = e^{−tL} · s
+```
+
+- **sketch** — large `t`, hub + anchor seeds: the whole repo in one blurry-but-valid silhouette.
+- **focus** — small `t`, your query as the seed: the fovea on exactly that feature.
+- **dwell** — `t` ×2 per call; only newly-luminous nodes are returned.
+- **impact** — changed files as the seed; warmth = predicted blast radius.
+
+Lineage: spectral-graph heat kernels (SGWT evaluated by shared Chebyshev recurrence), progressive image coding (budget as bitrate over significance-sorted coefficients), foveated rendering. Nanobridge: aider's PageRank repo map is the fixed-timescale special case.
+
+## Install
+
+Requires Node.js 20+ and [ast-grep](https://ast-grep.github.io/) on PATH (`brew install ast-grep`, `npm i -g @ast-grep/cli`, or set `FOVEA_AST_GREP=/path/to/sg`).
+
+```sh
+pi install npm:pi-fovea
+```
+
+<details>
+<summary>Other install methods</summary>
+
+From GitHub:
+
+```sh
+pi install git:github.com/monotykamary/pi-fovea
+```
+
+From a local checkout:
+
+```sh
+pnpm install
+pi install /absolute/path/to/pi-fovea
+```
+
+</details>
+
+Then, in any repo session, the model gets the four `fovea_*` tools; you get:
+
+- `/fovea status` — graph stats, sync on/off
+- `/fovea settings` — an overlay built from the same SettingsList idiom as pi-fabric's `/fabric settings`
+
+### CLI
+
+The same ops, stateless and pipe-friendly — for agent shells, CI, and `llmc`-style uses:
+
+```sh
+fovea sketch /path/to/repo 900
+fovea focus /path/to/repo "/v1/messages" 800
+fovea impact /path/to/repo --base main 1200
+fovea status /path/to/repo
+```
+
+(`fovea` bins to `cli.ts` via `tsx`; install `tsx` globally or use `pnpm fovea` from a checkout.)
+
+## Turn-sync (default on)
+
+After every assistant turn, fovea re-syncs the graph — guaranteed incremental by content hash — no edits means zero work. The verdict:
+
+- **green** → silent in the model's context (a UI toast only if `sync.ackClean` is on).
+- **red** → a capped custom message: route anchors that appeared/disappeared, plus files the edit cascade warmed that the model hasn't focused yet.
+
+The first sync establishes the baseline; the first drift after it calibrates the warm neighborhood rather than alarming, so a steady feature cone doesn't page the model every edit.
+
+Opt out per-repo or globally: `/fovea settings` → "Turn sync → false", or
+
+```sh
+FOVEA_TURN_SYNC=off pi
+```
+
+## Configuration
+
+Global `~/.pi/agent/fovea.json`; project override `<repo>/.pi/fovea.json` when trusted — the same two-scope model as pi-fabric's `fabric.json`.
+
+| Key | Default | Meaning |
+| --- | :-----: | ------- |
+| `sync.enabled` | `true` | the turn-sync loop |
+| `sync.budget` | `1024` | tokens for the red model-visible report |
+| `sync.ackClean` | `false` | toast on clean structural turns (no model tokens either way) |
+| `sync.warmFileThreshold` | `2` | newly-warm undisclosed files that justify red |
+| `tools.defaultBudget` | `2000` | fallback maxTokens for fovea_* tool calls |
+
+## Repo rule packs
+
+Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-ins (express/orval chains, NestJS decorators, Flask/FastAPI decorators, Go chi/mux, axum):
+
+```json
+{
+  "rules": [
+    { "id": "fiber", "langs": ["Go"], "pattern": "$R.$M(\"$P\", $$H)", "methods": "^(get|post)$", "kind": "route" }
+  ]
+}
+```
+
+Changing the rules file invalidates **only** the anchor extraction cache — green-node reuse one level up.
+
+## How the graph is joined
+
+- **imports / contains / inherits / tests** — outline-derived; call edges specificity-tiered, with language builtins and log/test entry points warded off
+- **literal joins** — route paths, env keys, OpenAPI operation paths; document-frequency-gated cliques so rare literals bridge strongly and ubiquitous ones don't become gravity wells
+- **co-change** — mined from recent git history (Jaccard-tilted, per-file capped, cached by HEAD), so files that commute together warm each other even without a static edge
+- **feature hubs** — route declarations and every client call of the same normalized path collapse to ONE anchor node: where client, server, and spec meet
+- **basins** — where there are no routes at all (CLIs, kernels), sketch infers implicit features as conductance-cut regions around triangle-dense seeds
+
+## Language matrix
+
+Full symbol + call extraction: **TypeScript/TSX · JavaScript · Python · Go · Rust**.
+Outline-based symbols with heuristic naming: **Elixir · Ruby · C · C++ · Java · Kotlin · Lua · PHP · Swift · Scala · Haskell · Bash**.
+Config joins through literals: **YAML · JSON · TOML · env · Markdown · OpenAPI**.
+
+## Development
+
+```sh
+pnpm install
+pnpm run check        # typecheck + full vitest suite
+pnpm run bench        # rate–distortion bench against ../pi-fabric
+```
+
+pi loads the extension straight from `src/` via jiti — **there is no build step**. Per-repo caches live in `$TMPDIR` (content sha1 per file; only dirty files re-run ast-grep). Bump `CACHE_VERSION` in `src/core/build.ts` when extractor semantics change.
+
+[MIT](LICENSE).

package/cli.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env tsx
+// pi-fovea CLI — the extension without pi, for agent shells and pipes:
+//   fovea status [root]
+//   fovea sketch [root] [budget]
+//   fovea focus [root] <query> [budget]
+//   fovea dwell [root] [factor] [budget]     (deepens the in-process focus)
+//   fovea impact [root] [--files a,b] [--symbols x,y] [--base ref] [--no-uncommitted] [budget]
+//
+// The CLI is stateless across invocations (dwell needs a prior focus in the
+// same process — combine ops inside pi, where sessions persist); stdout is
+// the rendered field, nothing else, so it composes with head/grep/$().
+
+import { sketch, focus, dwell, impact } from "./src/core/ops.js";
+
+const [, , cmd = "status", ...argv] = process.argv;
+
+const VALUE_FLAGS = new Set(["files", "symbols", "base"]);
+const flags = new Map<string, string | true>();
+const pos: string[] = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i]!;
+  if (a.startsWith("--")) {
+    const name = a.slice(2);
+    if (VALUE_FLAGS.has(name)) flags.set(name, argv[++i] ?? "");
+    else flags.set(name, true);
+  } else {
+    pos.push(a);
+  }
+}
+const str = (name: string): string | undefined => {
+  const v = flags.get(name);
+  return typeof v === "string" ? v : undefined;
+};
+const numAt = (i: number): number | undefined => {
+  const n = Number(pos[i]);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+};
+// Root is the first positional that names a path; everything else is arg data.
+const rootAt = (i: number): string => {
+  const p = pos[i];
+  return p !== undefined && (p.includes("/") || p === ".") ? p : ".";
+};
+
+try {
+  let out = "";
+  if (cmd === "status") {
+    const s = sketch(rootAt(0), 256);
+    out = `${s.details.files} files, ${s.details.nodes} nodes, ${s.details.anchors} anchors`;
+  } else if (cmd === "sketch") {
+    const root = rootAt(0);
+    const B = numAt(pos[0] === root && pos.length > 1 ? 1 : 0) ?? 1400;
+    out = sketch(root, B).text;
+  } else if (cmd === "focus") {
+    const root = rootAt(0);
+    const q = pos[0] !== root ? pos[0] : pos[1];
+    if (!q) { console.error("fovea focus <query>"); process.exit(2); }
+    let bi = pos.indexOf(q) + 1;
+    out = focus(root, q, numAt(bi) ?? 2000).text;
+  } else if (cmd === "dwell") {
+    const root = rootAt(0);
+    const factor = numAt(pos[0] === root ? 1 : 0) ?? 2;
+    const B = numAt(pos[0] === root ? 2 : 1) ?? 2000;
+    out = dwell(root, factor, B).text;
+  } else if (cmd === "impact") {
+    const root = rootAt(0);
+    const B = pos[0] === root ? numAt(1) : numAt(0);
+    out = impact(root, {
+      files: str("files")?.split(",").filter(Boolean),
+      symbols: str("symbols")?.split(",").filter(Boolean),
+      base: str("base"),
+      includeUncommitted: !flags.has("no-uncommitted"),
+      budget: B ?? 2000,
+    }).text;
+  } else {
+    console.error(`unknown command: ${cmd}`);
+    process.exit(2);
+  }
+  console.log(out);
+} catch (e) {
+  console.error(String(e instanceof Error ? e.message : e));
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pi-fovea",
+  "version": "0.1.0",
+  "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
+  "type": "module",
+  "license": "MIT",
+  "engines": { "node": ">=20" },
+  "pi": { "extensions": ["./src/index.ts"] },
+  "exports": { "./ops": "./src/core/ops.ts" },
+  "files": ["src", "cli.ts", "README.md", "LICENSE"],
+  "bin": { "fovea": "cli.ts" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "bench": "tsx scripts/bench.ts",
+    "fovea": "tsx cli.ts",
+    "check": "pnpm run typecheck && pnpm run test"
+  },
+  "dependencies": {
+    "typebox": "^1.0.76"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.6",
+    "@earendil-works/pi-tui": ">=0.80.6"
+  }
+}

package/src/core/anchors.ts

@@ -0,0 +1,159 @@
+// Feature anchors: where a feature touches the outside world. Anchors are
+// extracted by a declarative rule pack (ast-grep patterns + metadata), so new
+// frameworks are added as data. A route registration is the canonical anchor:
+// one pattern shape covers express/koa (TS), gin/echo/chi (Go), flask/fastapi
+// decorators (Python), and axum-style chains (Rust).
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join as joinPath } from "node:path";
+import { groupByLang, patternRun } from "./astgrep.js";
+import { PATH_TOKEN_RE } from "./extract.js";
+import { classifyLiteral, normalizeLiteral } from "./join.js";
+import type { Anchor } from "./types.js";
+
+export interface AnchorRule {
+  id: string;
+  langs: string[];
+  pattern: string;
+  methods: string; // regex tested against the captured method metavar
+  kind: string;
+}
+
+const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\})$/;
+
+export const DEFAULT_PACK: AnchorRule[] = [
+  {
+    id: "http-route-call",
+    langs: ["TypeScript", "Tsx", "JavaScript", "Go"],
+    pattern: '$R.$M("$P", $$$H)',
+    methods: "^(?i:get|post|put|delete|patch|head|options|all|use|any|handle|handlefunc|route|group)$",
+    kind: "route",
+  },
+  {
+    // Single-arg verb call: axios.get("/me") — client call sites only become
+    // feature hubs when they reference a real path (validated below).
+    id: "http-verb-single-arg",
+    langs: ["TypeScript", "Tsx", "JavaScript"],
+    pattern: '$R.$M("$P")',
+    methods: "^(?i:get|post|put|delete|patch)$",
+    kind: "route",
+  },
+  {
+    id: "http-route-call-singlequote",
+    langs: ["TypeScript", "Tsx", "JavaScript"],
+    pattern: "$R.$M('$P', $$$H)",
+    methods: "^(?i:get|post|put|delete|patch|all|use|handle|route)$",
+    kind: "route",
+  },
+  {
+    // NestJS / decorator shape: @Get("/users/:id") on a controller method.
+    id: "ts-http-decorator",
+    langs: ["TypeScript", "Tsx"],
+    pattern: '@$M("$P")',
+    methods: "^(?i:get|post|put|delete|patch|options|head)$",
+    kind: "route",
+  },
+  {
+    id: "python-decorator-route",
+    langs: ["Python"],
+    pattern: '@$R.$M("$P")',
+    methods: "^(get|post|put|delete|patch|route|websocket)$",
+    kind: "route",
+  },
+  {
+    id: "python-decorator-route-singlequote",
+    langs: ["Python"],
+    pattern: "@$R.$M('$P')",
+    methods: "^(get|post|put|delete|patch|route|websocket)$",
+    kind: "route",
+  },
+  {
+    id: "flask-add-url-rule",
+    langs: ["Python"],
+    pattern: '$R.add_url_rule("$P", $$$H)',
+    methods: "^add_url_rule$",
+    kind: "route",
+  },
+  {
+    id: "rust-router-chain",
+    langs: ["Rust"],
+    pattern: '$R.route("$P", $$$H)',
+    methods: "^route$",
+    kind: "route",
+  },
+];
+
+export interface AnchorDraft extends Anchor {}
+
+export const extractAnchors = (
+  files: string[],
+  cwd: string,
+  resolveEnclosing: (file: string, line: number) => string | undefined,
+  pack: AnchorRule[] = DEFAULT_PACK,
+): AnchorDraft[] => {
+  const byLang = groupByLang(files);
+  const out: AnchorDraft[] = [];
+  for (const rule of pack) {
+    const methodRe = new RegExp(rule.methods);
+    for (const lang of rule.langs) {
+      const langFiles = byLang.get(lang);
+      if (!langFiles?.length) continue;
+      for (const m of patternRun(rule.pattern, lang, langFiles, cwd)) {
+        const method = m.single.M;
+        const path = m.single.P;
+        if (!method || !path || !methodRe.test(method)) continue;
+        const raw = path.trim();
+        // $R.$M(...) also matches Map.get("key")-style data access; only real
+        // paths (or router-relative placeholders like ":id") may anchor.
+        if (!PATH_TOKEN_RE.test(raw) && !PLACEHOLDER_ONLY.test(raw)) continue;
+        const norm = normalizeLiteral(path, "path");
+        const httpMethod = method.toUpperCase() === "ROUTE" || method.toLowerCase() === "route" || method.toLowerCase() === "use" || method.toLowerCase() === "any"
+          ? method.toUpperCase()
+          : method.toUpperCase();
+        const label = `${httpMethod} ${norm}`;
+        const enclosing = resolveEnclosing(m.file, m.line);
+        out.push({
+          id: label,
+          kind: rule.kind,
+          label,
+          nodeId: enclosing ?? `file:${m.file}`,
+          file: m.file,
+          line: m.line,
+        });
+      }
+    }
+  }
+  // Dedupe identical anchors at the same site (overlapping rules).
+  const seen = new Set<string>();
+  return out.filter((a) => {
+    const k = `${a.id}|${a.file}|${a.line}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+};
+
+// Re-export so callers can classify an anchor path like any literal.
+export const anchorClassify = classifyLiteral;
+
+// Repo-local overrides: .fovea/rules.json = { "rules": AnchorRule[] }.
+// Merged after the default pack; the content hash invalidates the fact cache
+// so changing rules rebuilds anchors only.
+export const loadRepoRules = (root: string): { pack: AnchorRule[]; sha: string } => {
+  let raw = "";
+  try {
+    raw = readFileSync(joinPath(root, ".fovea", "rules.json"), "utf8");
+  } catch {
+    return { pack: DEFAULT_PACK, sha: "" };
+  }
+  try {
+    const parsed = JSON.parse(raw) as { rules?: AnchorRule[] };
+    const rules = (parsed.rules ?? []).filter(
+      (r) => r && typeof r.pattern === "string" && typeof r.methods === "string" && Array.isArray(r.langs),
+    );
+    return { pack: [...DEFAULT_PACK, ...rules], sha: createHash("sha1").update(raw).digest("hex") };
+  } catch {
+    return { pack: DEFAULT_PACK, sha: createHash("sha1").update(raw).digest("hex") };
+  }
+};

package/src/core/astgrep.ts

@@ -0,0 +1,156 @@
+// Thin runner over the ast-grep CLI. All extraction goes through here.
+// Resolution: FOVEA_AST_GREP env var, then `ast-grep` on PATH.
+
+import { spawnSync } from "node:child_process";
+
+export const LANG_BY_EXT: Record<string, string> = {
+  ts: "TypeScript", tsx: "Tsx", mts: "TypeScript", cts: "TypeScript",
+  js: "JavaScript", jsx: "Tsx", mjs: "JavaScript", cjs: "JavaScript",
+  py: "Python",
+  go: "Go",
+  rs: "Rust",
+  // Second tier: symbols via ast-grep outline; name derivation is heuristic.
+  ex: "Elixir", exs: "Elixir",
+  rb: "Ruby",
+  c: "C", h: "C",
+  cc: "C++", cpp: "C++", cxx: "C++", hpp: "C++", hh: "C++",
+  java: "Java",
+  kt: "Kotlin", kts: "Kotlin",
+  lua: "Lua",
+  php: "Php",
+  swift: "Swift",
+  scala: "Scala",
+  hs: "Haskell",
+  sh: "Bash",
+};
+
+// Compiled artifacts masquerading as source extensions.
+const BINARY_EXTS = new Set(["beam", "pyc", "o", "obj", "so", "a", "d"]);
+export const isBinaryExt = (file: string): boolean =>
+  BINARY_EXTS.has(file.split(".").pop()?.toLowerCase() ?? "");
+
+// Non-code files: literals are regex-extracted so config/spec files can join.
+export const CONFIG_EXTS = new Set(["yaml", "yml", "json", "toml", "env", "tf", "hcl", "md"]);
+
+export interface AgMatch {
+  file: string;                    // as passed to ast-grep (repo-relative)
+  line: number;                    // 1-indexed
+  text: string;                    // full matched node text
+  single: Record<string, string>;  // $VAR -> text (single metavars)
+  multi: Record<string, string[]>; // $$$VAR -> texts
+}
+
+const binary = (): string => process.env.FOVEA_AST_GREP ?? "ast-grep";
+
+export const hasAstGrep = (): boolean => {
+  const r = spawnSync(binary(), ["--version"], { encoding: "utf8" });
+  return !r.error && r.status === 0;
+};
+
+const CHUNK = 160;
+
+const run = (args: string[], cwd: string): string => {
+  const res = spawnSync(binary(), args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 120_000,
+    maxBuffer: 128 * 1024 * 1024,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  if (res.error || res.status !== 0) return "";
+  return res.stdout ?? "";
+};
+
+export const langOf = (file: string): string | undefined => {
+  const ext = file.split(".").pop()?.toLowerCase() ?? "";
+  return LANG_BY_EXT[ext];
+};
+
+export const isConfigFile = (file: string): boolean => {
+  const ext = file.split(".").pop()?.toLowerCase() ?? "";
+  return CONFIG_EXTS.has(ext);
+};
+
+export const groupByLang = (files: string[]): Map<string, string[]> => {
+  const m = new Map<string, string[]>();
+  for (const f of files) {
+    const lang = langOf(f);
+    if (!lang) continue;
+    const arr = m.get(lang) ?? [];
+    arr.push(f);
+    m.set(lang, arr);
+  }
+  return m;
+};
+
+// `ast-grep outline` — uniform symbol source across languages. Text format:
+//   <file>
+//   <line>: <signature source line>
+//        <kind>: <name>        (children: methods/fields, indented)
+export const outline = (files: string[], lang: string, cwd: string): string => {
+  let out = "";
+  for (let i = 0; i < files.length; i += CHUNK) {
+    out += run(["outline", ...files.slice(i, i + CHUNK)], cwd);
+  }
+  void lang;
+  return out;
+};
+
+interface RawMatch {
+  text: string;
+  range: { start: { line: number; column: number } };
+  file: string;
+  metaVariables?: {
+    single?: Record<string, { text: string }>;
+    multi?: Record<string, Array<{ text: string }>>;
+  };
+}
+
+// `ast-grep run --pattern` with JSON output for a set of files of one language.
+export const patternRun = (
+  pattern: string,
+  lang: string,
+  files: string[],
+  cwd: string,
+): AgMatch[] => {
+  const out: AgMatch[] = [];
+  for (let i = 0; i < files.length; i += CHUNK) {
+    const stdout = run(
+      ["run", "--pattern", pattern, "--lang", lang, "--json=compact", ...files.slice(i, i + CHUNK)],
+      cwd,
+    );
+    if (!stdout.trim()) continue;
+    let parsed: RawMatch[];
+    try {
+      parsed = JSON.parse(stdout) as RawMatch[];
+    } catch {
+      continue;
+    }
+    if (!Array.isArray(parsed)) continue;
+    for (const m of parsed) {
+      const single: Record<string, string> = {};
+      const multi: Record<string, string[]> = {};
+      for (const [k, v] of Object.entries(m.metaVariables?.single ?? {})) single[k] = v.text;
+      for (const [k, v] of Object.entries(m.metaVariables?.multi ?? {})) multi[k] = v.map((x) => x.text);
+      out.push({ file: m.file, line: m.range.start.line + 1, text: m.text, single, multi });
+    }
+  }
+  return out;
+};
+
+// First match of any of the patterns, per language/file set, concatenated.
+// Spread-pushing big match arrays overflows the argument-list limit, so
+// concatenate manually.
+const pushAll = <T>(out: T[], more: T[]): void => { for (const x of more) out.push(x); };
+
+// First match of any of the patterns, per language/file set, concatenated.
+export const patternRunAll = (
+  patterns: string[],
+  lang: string,
+  files: string[],
+  cwd: string,
+): AgMatch[] => {
+  const out: AgMatch[] = [];
+  for (const p of patterns) pushAll(out, patternRun(p, lang, files, cwd));
+  return out;
+};