@mrdrmccoy/xerj-opencode-plugin 0.0.0-stage → 0.4.1

package/src/rpc.ts

@@ -0,0 +1,250 @@
+// Typed contract shared by the server part, the TUI part, and any client.
+// Everything crosses a JSON boundary, so the schemas are JSON Schema objects
+// rather than TypeScript-only shapes. The casts are unavoidable: JSON Schema
+// values are structurally `unknown` in the plugin's type surface.
+
+import { Rpc } from "@opencode/plugin/rpc";
+
+export interface NodeStatus {
+  readonly phase: "starting" | "ready" | "error" | "disabled";
+  readonly baseUrl: string | null;
+  readonly serverVersion: string | null;
+  readonly spawned: boolean;
+  readonly error: string | null;
+}
+
+export interface BinaryStatus {
+  readonly version: string | null;
+  readonly path: string | null;
+  readonly upgraded: boolean;
+  readonly target: string | null;
+}
+
+export interface DatasetStatus {
+  readonly name: string;
+  readonly docs: number;
+  readonly bytes: number;
+}
+
+export interface BrainStatus {
+  readonly name: string;
+  readonly prefix: string;
+  readonly docs: number;
+  readonly edges: number;
+  readonly lastRunAt: number | null;
+  readonly error: string | null;
+}
+
+export interface MemoryStatus {
+  readonly namespace: string;
+  readonly count: number;
+}
+
+export interface CitedFileStatus {
+  readonly path: string;
+  readonly citations: number;
+  readonly bytes: number;
+}
+
+export interface IndexStatus {
+  readonly prefix: string;
+  readonly docs: number;
+  readonly bytes: number;
+  readonly indices: number;
+  readonly state: "disabled" | "starting" | "watching" | "idle" | "error";
+  readonly lastRunAt: number | null;
+  readonly lastGeneration: number | null;
+  readonly lastRecords: number | null;
+  readonly restarts: number;
+  readonly lastError: string | null;
+  readonly datasets: ReadonlyArray<DatasetStatus>;
+}
+
+export interface UsageStatus {
+  readonly queries: number;
+  readonly hits: number;
+  readonly hitRate: number;
+  readonly bytesReturned: number;
+  readonly bytesRead: number;
+  readonly baselineBytes: number;
+  readonly savedBytes: number;
+  readonly tokensSaved: number;
+  readonly topFiles: ReadonlyArray<CitedFileStatus>;
+}
+
+export interface CounterStatus {
+  readonly rpcCalls: number;
+  readonly injectedTurns: number;
+  readonly nodeSpawns: number;
+  readonly http429: number;
+  readonly indexRuns: number;
+}
+
+export interface ConfigStatus {
+  readonly indexRoot: string;
+  readonly brain: ReadonlyArray<string>;
+  readonly watch: boolean;
+  readonly contextEnabled: boolean;
+}
+
+export interface StatusSnapshot {
+  readonly pluginVersion: string;
+  readonly updatedAt: number;
+  readonly node: NodeStatus;
+  readonly binary: BinaryStatus;
+  readonly index: IndexStatus;
+  readonly config: ConfigStatus;
+  readonly usage: UsageStatus;
+  readonly memory: MemoryStatus;
+  readonly brains: ReadonlyArray<BrainStatus>;
+  readonly counters: CounterStatus;
+  readonly recent: ReadonlyArray<string>;
+  readonly warnings: ReadonlyArray<string>;
+  readonly errors: ReadonlyArray<string>;
+}
+
+type ValueSchema = Rpc.PortableValueSchema;
+type EventSchema = Rpc.PortableEventDefinition["schema"];
+
+function object(properties: Record<string, unknown>): Record<string, unknown> {
+  return {
+    type: "object",
+    properties,
+    required: Object.keys(properties),
+    additionalProperties: false,
+  };
+}
+
+function valueSchema(properties: Record<string, unknown>): ValueSchema {
+  return object(properties) as unknown as ValueSchema;
+}
+
+function eventSchema(properties: Record<string, unknown>): EventSchema {
+  return object(properties) as unknown as EventSchema;
+}
+
+const definition = {
+  id: "xerj",
+  methods: {
+    status: {
+      input: valueSchema({}),
+      output: valueSchema({
+        pluginVersion: { type: "string" },
+        updatedAt: { type: "number" },
+        node: object({
+          phase: { type: "string", enum: ["starting", "ready", "error", "disabled"] },
+          baseUrl: { type: ["string", "null"] },
+          serverVersion: { type: ["string", "null"] },
+          spawned: { type: "boolean" },
+          error: { type: ["string", "null"] },
+        }),
+        binary: object({
+          version: { type: ["string", "null"] },
+          path: { type: ["string", "null"] },
+          upgraded: { type: "boolean" },
+          target: { type: ["string", "null"] },
+        }),
+        index: object({
+          prefix: { type: "string" },
+          docs: { type: "number" },
+          bytes: { type: "number" },
+          indices: { type: "number" },
+          state: {
+            type: "string",
+            enum: ["disabled", "starting", "watching", "idle", "error"],
+          },
+          lastRunAt: { type: ["number", "null"] },
+          lastGeneration: { type: ["number", "null"] },
+          lastRecords: { type: ["number", "null"] },
+          restarts: { type: "number" },
+          lastError: { type: ["string", "null"] },
+          datasets: {
+            type: "array",
+            items: object({
+              name: { type: "string" },
+              docs: { type: "number" },
+              bytes: { type: "number" },
+            }),
+          },
+        }),
+        config: object({
+          indexRoot: { type: "string" },
+          brain: { type: "array", items: { type: "string" } },
+          watch: { type: "boolean" },
+          contextEnabled: { type: "boolean" },
+        }),
+        usage: object({
+          queries: { type: "number" },
+          hits: { type: "number" },
+          hitRate: { type: "number" },
+          bytesReturned: { type: "number" },
+          bytesRead: { type: "number" },
+          baselineBytes: { type: "number" },
+          savedBytes: { type: "number" },
+          tokensSaved: { type: "number" },
+          topFiles: {
+            type: "array",
+            items: object({
+              path: { type: "string" },
+              citations: { type: "number" },
+              bytes: { type: "number" },
+            }),
+          },
+        }),
+        memory: object({
+          namespace: { type: "string" },
+          count: { type: "number" },
+        }),
+        brains: {
+          type: "array",
+          items: object({
+            name: { type: "string" },
+            prefix: { type: "string" },
+            docs: { type: "number" },
+            edges: { type: "number" },
+            lastRunAt: { type: ["number", "null"] },
+            error: { type: ["string", "null"] },
+          }),
+        },
+        counters: object({
+          rpcCalls: { type: "number" },
+          injectedTurns: { type: "number" },
+          nodeSpawns: { type: "number" },
+          http429: { type: "number" },
+          indexRuns: { type: "number" },
+        }),
+        recent: { type: "array", items: { type: "string" } },
+        warnings: { type: "array", items: { type: "string" } },
+        errors: { type: "array", items: { type: "string" } },
+      }),
+    },
+    reindex: {
+      input: valueSchema({}),
+      output: valueSchema({ queued: { type: "boolean" } }),
+    },
+    remember: {
+      input: valueSchema({ text: { type: "string" } }),
+      output: valueSchema({
+        id: { type: "string" },
+        created: { type: "boolean" },
+      }),
+    },
+    search: {
+      input: valueSchema({ query: { type: "string" } }),
+      output: valueSchema({
+        text: { type: "string" },
+        hits: { type: "number" },
+        bytes: { type: "number" },
+      }),
+    },
+  },
+  events: {
+    updated: {
+      schema: eventSchema({ updatedAt: { type: "number" } }),
+    },
+  },
+} satisfies Rpc.PortableDefinition;
+
+export const XerjRpc = Rpc.define(definition);
+
+export const PLUGIN_VERSION = "0.4.1";

package/src/search/brains.ts

@@ -0,0 +1,306 @@
+// One hop of second-brain neighbors for retrieved passages. The graph stores
+// edges, not text, so neighbor ids are resolved through the brain's own index.
+//
+// Only `pathcite` and `sequence` edges are used. `same_dir` says two files share
+// a folder, which is not evidence of a useful relation.
+
+import type { Logger } from "../log.ts";
+import type { XerjClient } from "../node/client.ts";
+import type { BrainSpec } from "../paths.ts";
+import type { SearchHit } from "./service.ts";
+
+export interface BrainGraphOptions {
+  readonly client: XerjClient;
+  readonly brains: ReadonlyArray<BrainSpec>;
+  readonly logger: Logger;
+}
+
+export interface NeighborRef {
+  readonly id: string;
+  readonly type: string;
+}
+
+const ALLOWED_TYPES = new Set(["pathcite", "sequence"]);
+const TYPE_PRIORITY: Record<string, number> = { pathcite: 0, sequence: 1 };
+const MAX_NEIGHBORS = 2;
+const MAX_TEXT_CHARS = 600;
+const SOURCE_FIELDS = ["path", "ax_path", "title", "start_line", "kind", "body"];
+
+export class BrainGraph {
+  constructor(private readonly options: BrainGraphOptions) {}
+
+  /** Neighbor passages for brain hits, capped at two per query. */
+  async related(
+    hits: ReadonlyArray<SearchHit>,
+    signal?: AbortSignal,
+  ): Promise<SearchHit[]> {
+    const groups = new Map<string, { spec: BrainSpec; seeds: string[] }>();
+
+    for (const hit of hits) {
+      const spec = this.specFor(hit.index);
+      if (!spec || hit.id.length === 0) continue;
+
+      const group = groups.get(spec.name) ?? { spec, seeds: [] };
+      if (!group.seeds.includes(hit.id)) group.seeds.push(hit.id);
+      groups.set(spec.name, group);
+    }
+
+    const related: SearchHit[] = [];
+    for (const group of groups.values()) {
+      if (related.length >= MAX_NEIGHBORS) break;
+      const found = await this.expand(
+        group.spec,
+        group.seeds.slice(0, 2),
+        MAX_NEIGHBORS - related.length,
+        signal,
+      );
+      related.push(...found);
+    }
+
+    return related;
+  }
+
+  private specFor(index: string): BrainSpec | undefined {
+    return this.options.brains.find((spec) => index.startsWith(`${spec.prefix}-`));
+  }
+
+  private async expand(
+    spec: BrainSpec,
+    seeds: ReadonlyArray<string>,
+    limit: number,
+    signal?: AbortSignal,
+  ): Promise<SearchHit[]> {
+    // The ego endpoint accepts one node per request; a comma-joined list
+    // answers with no edges. Query each seed and merge the edges.
+    const edges: unknown[] = [];
+    for (const seed of seeds) {
+      const path =
+        `/_graph/${encodeURIComponent(spec.name)}` +
+        `/ego?node=${encodeURIComponent(seed)}&hops=1&direction=both`;
+      const ego = await this.options.client
+        .get(path, "graph query failed", signal)
+        .catch((error: unknown) => {
+          this.options.logger.debug("brain expansion skipped", String(error));
+          return null;
+        });
+      if (!isRecord(ego) || !Array.isArray(ego.edges)) continue;
+      edges.push(...ego.edges);
+    }
+
+    const neighbors = pickNeighbors({ edges }, seeds, limit);
+    if (neighbors.length === 0) return [];
+
+    const response = await this.options.client
+      .search(
+        `${spec.prefix}-docs`,
+        {
+          size: neighbors.length,
+          _source: SOURCE_FIELDS,
+          query: { ids: { values: neighbors.map((neighbor) => neighbor.id) } },
+        },
+        signal,
+      )
+      .catch((error: unknown) => {
+        this.options.logger.debug("brain neighbor fetch skipped", String(error));
+        return null;
+      });
+
+    const direct = parseNeighbors(response, neighbors);
+
+    // A `pathcite` points at the target file's whole-file record, which has no
+    // `body`; only its section records carry text. Fetch the first section so
+    // the neighbor is usable.
+    const missing = bodylessPaths(response, neighbors, direct);
+    const sections = await this.fetchSections(spec, missing, signal);
+    return [...direct, ...sections].slice(0, limit);
+  }
+
+  private async fetchSections(
+    spec: BrainSpec,
+    missing: ReadonlyArray<{ path: string; type: string }>,
+    signal?: AbortSignal,
+  ): Promise<SearchHit[]> {
+    const found: SearchHit[] = [];
+    for (const entry of missing) {
+      if (found.length >= MAX_NEIGHBORS) break;
+      const response = await this.options.client
+        .search(
+          `${spec.prefix}-docs`,
+          {
+            size: 1,
+            sort: [{ start_line: "asc" }],
+            _source: SOURCE_FIELDS,
+            query: {
+              bool: {
+                must: [
+                  { term: { ax_path: entry.path } },
+                  { exists: { field: "body" } },
+                ],
+              },
+            },
+          },
+          signal,
+        )
+        .catch((error: unknown) => {
+          this.options.logger.debug("brain section fetch skipped", String(error));
+          return null;
+        });
+
+      const hit = firstHit(response, entry.type);
+      if (hit) found.push(hit);
+    }
+    return found;
+  }
+}
+
+/** Chooses allowed edge types, preferring explicit citations. */
+export function pickNeighbors(
+  ego: unknown,
+  seeds: ReadonlyArray<string>,
+  limit: number,
+): NeighborRef[] {
+  if (!isRecord(ego) || !Array.isArray(ego.edges)) return [];
+
+  const seedSet = new Set(seeds);
+  const candidates: Array<NeighborRef & { weight: number }> = [];
+  const seen = new Set<string>();
+
+  for (const edge of ego.edges) {
+    if (!isRecord(edge)) continue;
+    if (edge.invalid_at !== null && edge.invalid_at !== undefined) continue;
+
+    const type = typeof edge.type === "string" ? edge.type : "";
+    if (!ALLOWED_TYPES.has(type)) continue;
+
+    const src = typeof edge.src === "string" ? edge.src : "";
+    const dst = typeof edge.dst === "string" ? edge.dst : "";
+    const other = seedSet.has(src) ? dst : seedSet.has(dst) ? src : "";
+    if (other.length === 0 || seedSet.has(other) || seen.has(other)) continue;
+
+    seen.add(other);
+    candidates.push({
+      id: other,
+      type,
+      weight: typeof edge.weight === "number" ? edge.weight : 0,
+    });
+  }
+
+  return candidates
+    .sort(
+      (left, right) =>
+        (TYPE_PRIORITY[left.type] ?? 9) - (TYPE_PRIORITY[right.type] ?? 9) ||
+        right.weight - left.weight,
+    )
+    .slice(0, limit)
+    .map(({ id, type }) => ({ id, type }));
+}
+
+/** Neighbor docs that were fetched but carry no text, with their file path. */
+function bodylessPaths(
+  response: unknown,
+  neighbors: ReadonlyArray<NeighborRef>,
+  parsed: ReadonlyArray<SearchHit>,
+): Array<{ path: string; type: string }> {
+  const found = new Map<string, string>();
+  for (const hit of hitsOf(response)) {
+    if (!isRecord(hit)) continue;
+    const id = stringValue(hit._id) ?? "";
+    if (id.length === 0) continue;
+    const source = isRecord(hit._source) ? hit._source : {};
+    const path = stringValue(source.ax_path) ?? stringValue(source.path);
+    if (path !== null && path.length > 0) found.set(id, path);
+  }
+
+  const done = new Set(parsed.map((hit) => hit.id));
+  const result: Array<{ path: string; type: string }> = [];
+  for (const neighbor of neighbors) {
+    if (done.has(neighbor.id)) continue;
+    const path = found.get(neighbor.id);
+    if (path) result.push({ path, type: neighbor.type });
+  }
+  return result;
+}
+
+function firstHit(response: unknown, type: string): SearchHit | null {
+  for (const raw of hitsOf(response)) {
+    if (!isRecord(raw)) continue;
+    const source = isRecord(raw._source) ? raw._source : {};
+    const text = stringValue(source.body) ?? stringValue(source.code) ?? "";
+    if (text.trim().length === 0) continue;
+
+    return {
+      index: stringValue(raw._index) ?? "",
+      id: stringValue(raw._id) ?? "",
+      passage: 0,
+      path: stringValue(source.ax_path) ?? stringValue(source.path) ?? null,
+      line: numberValue(source.start_line),
+      title: stringValue(source.title),
+      kind: `via ${type}`,
+      score: 0,
+      text: clip(text.trim()),
+    };
+  }
+  return null;
+}
+
+function parseNeighbors(
+  response: unknown,
+  neighbors: ReadonlyArray<NeighborRef>,
+): SearchHit[] {
+  const byId = new Map(neighbors.map((neighbor) => [neighbor.id, neighbor.type]));
+  const parsed: SearchHit[] = [];
+
+  for (const raw of hitsOf(response)) {
+    if (!isRecord(raw)) continue;
+    const id = stringValue(raw._id) ?? "";
+    const via = byId.get(id);
+    if (!via) continue;
+
+    const source = isRecord(raw._source) ? raw._source : {};
+    const text = stringValue(source.body) ?? stringValue(source.code) ?? "";
+    if (text.trim().length === 0) continue;
+
+    parsed.push({
+      index: stringValue(raw._index) ?? "",
+      id,
+      passage: 0,
+      path: stringValue(source.ax_path) ?? stringValue(source.path) ?? null,
+      line: numberValue(source.start_line),
+      title: stringValue(source.title),
+      kind: `via ${via}`,
+      score: 0,
+      text: clip(text.trim()),
+    });
+  }
+
+  return parsed;
+}
+
+function hitsOf(response: unknown): unknown[] {
+  if (!isRecord(response)) return [];
+  const hits = response.hits;
+  if (!isRecord(hits) || !Array.isArray(hits.hits)) return [];
+  return hits.hits;
+}
+
+function clip(text: string): string {
+  if (text.length <= MAX_TEXT_CHARS) return text;
+
+  const cut = text.slice(0, MAX_TEXT_CHARS);
+  const lastNewline = cut.lastIndexOf("\n");
+  return lastNewline > MAX_TEXT_CHARS / 2
+    ? `${cut.slice(0, lastNewline)}\n…`
+    : `${cut}\n…`;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+function numberValue(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/search/rank.ts

@@ -0,0 +1,61 @@
+// Ranking adjustments applied after fusion. Generated files match on common
+// words and crowd out the source they came from, so they are demoted rather
+// than dropped: a query that names the file still has to find it.
+
+import { sep } from "node:path";
+import type { ParsedHit } from "./service.ts";
+
+const GENERATED_WEIGHT = 0.35;
+
+const GENERATED_NAMES = new Set([
+  "package-lock.json",
+  "npm-shrinkwrap.json",
+  "yarn.lock",
+  "pnpm-lock.yaml",
+  "bun.lock",
+  "bun.lockb",
+  "composer.lock",
+  "cargo.lock",
+  "gemfile.lock",
+  "poetry.lock",
+  "pipfile.lock",
+  "go.sum",
+  "flake.lock",
+]);
+
+const GENERATED_DIRS = ["dist/", "build/", "vendor/", "coverage/"];
+const MINIFIED_SUFFIXES = [".min.js", ".min.css", ".map"];
+
+/** True when the path looks generated rather than authored. */
+export function isGeneratedPath(path: string): boolean {
+  const normalized = path.split(sep).join("/").toLowerCase();
+  const name = normalized.slice(normalized.lastIndexOf("/") + 1);
+
+  if (GENERATED_NAMES.has(name)) return true;
+  if (MINIFIED_SUFFIXES.some((suffix) => name.endsWith(suffix))) return true;
+  return GENERATED_DIRS.some(
+    (dir) => normalized.startsWith(dir) || normalized.includes(`/${dir}`),
+  );
+}
+
+/**
+ * Re-ranks fused hits so generated files sit below authored ones. A query that
+ * names the file wins, because asking for `package-lock.json` must not demote
+ * it.
+ */
+export function demoteGenerated(
+  hits: ReadonlyArray<ParsedHit>,
+  query: string,
+): ParsedHit[] {
+  const named = query.toLowerCase();
+
+  return hits
+    .map((hit) => {
+      if (hit.path === null) return hit;
+      if (!isGeneratedPath(hit.path)) return hit;
+      const basename = hit.path.toLowerCase().split("/").pop() ?? "";
+      if (named.includes(basename)) return hit;
+      return { ...hit, score: hit.score * GENERATED_WEIGHT };
+    })
+    .sort((left, right) => right.score - left.score);
+}