@alucard_24/pi-codeindex 0.0.0-stage → 1.0.0

package/src/extension.js

@@ -0,0 +1,485 @@
+// Adapter pi (Fase 3): search_code, outline su `read`, riga di stato, /codeindex.
+//
+// Qui c'è solo colla: tutta la logica sta nei moduli puri (chunker, indexer,
+// search, present). Nessuna eccezione esce da questo file: un indice assente,
+// un modello non scaricabile o un reindex fallito degradano il tool, non la
+// sessione.
+
+import { defineTool } from '@earendil-works/pi-coding-agent';
+import { Type } from '@earendil-works/pi-ai';
+import fs from 'node:fs';
+import path from 'node:path';
+import { indexRepo } from './indexer.js';
+import { embeddingStatus } from './embed.js';
+import { formatProfile } from './backend.js';
+import { configCommand } from './config.js';
+import { configure } from './config-ui.js';
+import { doctor, formatDoctor, parseDoctorArgs } from './doctor.js';
+import { loadIndex } from './store.js';
+import { invalidateSearcher, loadSearcher, search } from './search.js';
+import { buildBundle, buildGraph } from './graph.js';
+import { createDebouncedQueue, filterDirty, parsePorcelainStatus } from './sync.js';
+import { fmtBytes, git, headCommit, repoRoot } from './util.js';
+import { formatBundle, formatHits, outlineText, promptLine, shouldAnnotateRead, statusLine, toRepoRel } from './present.js';
+
+const STATUS_KEY = 'codeindex';
+const DEFAULT_K = 8;
+const MAX_K = 30;
+const MAX_CAPS = { maxFiles: 5000, maxBytes: 200 * 1024 * 1024 };
+const CONFIG_ENTRY = 'codeindex-config';
+const DEBOUNCE_MS = 800;
+const MAX_SWEEP_PATHS = 200;
+
+let state = null; // { repo, enabled, indexing, progress, index, error, abort, queue, watcher, rerun }
+const running = new Map(); // repo -> promise (single-flight per repo)
+
+function readEnabled(ctx) {
+  try {
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === 'custom' && entry.customType === CONFIG_ENTRY) {
+        const data = entry.data ?? {};
+        if (typeof data.enabled === 'boolean') return data.enabled;
+      }
+    }
+  } catch {
+    /* nessuno stato salvato: default attivo */
+  }
+  return true;
+}
+
+function showStatus(ctx) {
+  // Spento significa spento: niente riga nel footer, come se l'estensione non ci fosse.
+  if (!state || state.enabled === false) {
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+    return;
+  }
+  const profile = embeddingStatus().profile;
+  ctx.ui.setStatus(STATUS_KEY, statusLine({
+    repo: state.repo,
+    enabled: state.enabled,
+    indexing: state.indexing,
+    progress: state.progress,
+    chunks: state.index?.chunks?.length ?? 0,
+  }) + (profile ? ` · ${formatProfile(profile)}` : ''));
+}
+
+/** Legge solo i metadati (per l'outline e la riga di stato): niente vettori. */
+async function refreshMeta() {
+  try {
+    const { index } = await loadIndex(state.repo);
+    state.index = index;
+  } catch {
+    state.index = null;
+  }
+}
+
+/**
+ * Indicizzazione in background. Riconcilia sempre (un file non committato non
+ * cambia HEAD) ma riusa i vettori: su un repo già indicizzato costa secondi.
+ * Single-flight: due session_start, un evento del watcher e un /codeindex
+ * reindex non si sovrappongono. Una richiesta arrivata durante un run viene
+ * riaccodata (`rerun`) invece di essere persa.
+ */
+function runIndex(ctx, { force = false } = {}) {
+  const st = state;
+  const repo = st?.repo;
+  if (!repo || !st.enabled) return Promise.resolve(null);
+  const inflight = running.get(repo);
+  if (inflight && !force) {
+    st.rerun = true;
+    return inflight;
+  }
+
+  const p = (async () => {
+    st.indexing = true;
+    st.rerun = false;
+    st.progress = null;
+    st.error = null;
+    showStatus(ctx);
+    try {
+      const r = await indexRepo({
+        root: repo,
+        ...MAX_CAPS,
+        force,
+        signal: st.abort.signal,
+        log: () => {}, // niente rumore su stderr dentro la TUI
+        onProgress: (p) => {
+          if (state !== st) return; // sessione sostituita: non toccarne lo stato
+          st.progress = { done: p.done, total: p.total };
+          showStatus(ctx);
+        },
+      });
+      st.index = r.index;
+      const runtime = embeddingStatus();
+      if (state === st && st.enabled && !st.backendWarning && runtime.attempts.some((a) => !a.ok)) {
+        st.backendWarning = true;
+        ctx.ui.notify(`codeindex: selezionato ${formatProfile(runtime.profile)}; tentativi falliti: ${runtime.attempts.filter((a) => !a.ok).map((a) => `${a.device}: ${a.error}`).join('; ')}`, 'warning');
+      }
+      st.graph = null; // il grafo è derivato dall'indice: va ricostruito
+      invalidateSearcher(repo);
+      return r;
+    } catch (e) {
+      if (st.abort.signal.aborted) return null;
+      st.error = e.message ?? String(e);
+      if (state === st && st.enabled && !/abort/i.test(st.error)) {
+        // Degradazione silenziosa: il tool resta disponibile e risponde con lo stato.
+        ctx.ui.notify(`codeindex: indicizzazione non riuscita (${st.error})`, 'warning');
+      }
+      return null;
+    } finally {
+      st.indexing = false;
+      st.progress = null;
+      running.delete(repo);
+      if (state === st) {
+        showStatus(ctx);
+        if (st.rerun && st.enabled && !st.abort.signal.aborted) {
+          st.rerun = false;
+          void runIndex(ctx);
+        }
+      }
+    }
+  })();
+  running.set(repo, p);
+  return p;
+}
+
+/** Grafo L2 in cache finché l'indice non cambia (costruirlo su Strata: ~120 ms). */
+async function ensureGraph(index) {
+  const stamp = `${index.updatedAt}:${index.chunks.length}`;
+  if (state.graph?.stamp === stamp) return state.graph.value;
+  const value = await buildGraph(state.repo, index);
+  state.graph = { stamp, value };
+  return value;
+}
+
+/** Spegne tutto: watcher, coda, indicizzazione in corso. Riaccendibile con enable. */
+function stopBackground() {
+  if (!state) return;
+  state.abort.abort();
+  state.queue?.cancel();
+  state.rerun = false;
+  try {
+    state.watcher?.close();
+  } catch {
+    /* già chiuso */
+  }
+  state.watcher = null;
+}
+
+/** Path toccati da watcher/hook: passa dal debounce e poi riconcilia. */
+function markDirty(paths) {
+  if (!state?.queue) return;
+  const rel = filterDirty(paths, state.repo);
+  if (rel.size === 0) return;
+  state.queue.add(rel);
+}
+
+/** `git status --porcelain -z` dopo un bash: cattura le modifiche indirette. */
+function sweepGitStatus() {
+  if (!state?.enabled || !state.repo) return;
+  // Costa ~50–100 ms su un repo grande: il watcher è il segnale primario, questo
+  // è la rete di sicurezza. Un giro ogni 1,5 s basta.
+  const now = Date.now();
+  if (now - (state.lastSweep ?? 0) < 1500) return;
+  state.lastSweep = now;
+  const out = git(state.repo, ['status', '--porcelain', '-z']);
+  if (!out) return;
+  const paths = parsePorcelainStatus(out).slice(0, MAX_SWEEP_PATHS);
+  if (paths.length) markDirty(paths);
+}
+
+/** Watcher ricorsivo; se il sistema non lo consente si degrada senza watcher. */
+function startWatcher(ctx) {
+  try {
+    const watcher = fs.watch(state.repo, { recursive: true }, (_event, filename) => {
+      if (filename) markDirty([String(filename)]);
+    });
+    watcher.on('error', () => {
+      try {
+        watcher.close();
+      } catch {
+        /* già chiuso */
+      }
+      if (state) state.watcher = null;
+    });
+    state.watcher = watcher;
+  } catch (e) {
+    state.watcher = null;
+    ctx.ui.notify(`codeindex: watcher non disponibile (${e.message})`, 'warning');
+  }
+}
+
+function unavailable(reason) {
+  return {
+    content: [{ type: 'text', text: `search_code non disponibile: ${reason}` }],
+    details: { status: 'unavailable', reason },
+  };
+}
+
+const searchCode = defineTool({
+  name: 'search_code',
+  label: 'Search code (semantic)',
+  description:
+    'Semantic search over a local embedding index of this repository. Returns the most relevant ' +
+    'code chunks as path:start-end with the enclosing symbol, score and a short preview. ' +
+    'Use it to locate code when you do not know the file or the identifiers; grep remains better ' +
+    'for exact strings and search_code does not replace it.',
+  promptSnippet: 'Semantic search over the local code index (path:lines + symbol)',
+  promptGuidelines: [
+    'Use search_code before grep when you need to find where a behavior lives and you do not know the names.',
+    'Use grep for exact identifiers, error strings and regex; search_code finds concepts, not literals.',
+    'Do not repeat the same search_code query: if the hits are wrong, rephrase or switch to grep.',
+  ],
+  parameters: Type.Object({
+    query: Type.String({ description: 'What you are looking for, in natural language (Italian or English).' }),
+    k: Type.Optional(Type.Number({
+      description: `How many chunks to return (default ${DEFAULT_K}, max ${MAX_K}).`,
+      minimum: 1,
+      maximum: MAX_K,
+    })),
+    path_prefix: Type.Optional(Type.String({
+      description: 'Restrict results to paths starting with this prefix, e.g. "src/extension/".',
+    })),
+    context: Type.Optional(Type.String({
+      description:
+        'snippets (default) = matches with previews. bundle = also imports, importers and ' +
+        'heuristic callers of the first 3 matches, in one call (slower, saves round-trips).',
+      enum: ['snippets', 'bundle'],
+    })),
+  }),
+  async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    if (!state?.repo) return unavailable('la directory corrente non è un repository git');
+    if (!state.enabled) return unavailable('indice disattivato (/codeindex enable per riattivarlo)');
+
+    const k = Math.min(MAX_K, Math.max(1, Math.round(params.k ?? DEFAULT_K)));
+    const tCall = performance.now();
+    try {
+      const res = await search(params.query, {
+        root: state.repo,
+        k,
+        pathPrefix: params.path_prefix ?? null,
+        checkStale: true, // L1: se il file è cambiato dopo l'indicizzazione, dillo
+      });
+      if (signal?.aborted) return unavailable('richiesta annullata');
+
+      const bundle = (params.context ?? 'snippets') === 'bundle';
+      if (bundle) {
+        const { index } = await loadSearcher(state.repo);
+        const graph = await ensureGraph(index);
+        await buildBundle(state.repo, index, res.results, graph, { signal });
+      }
+      const tookMsTotal = Math.round((performance.now() - tCall) * 10) / 10;
+      return {
+        content: [{ type: 'text', text: bundle ? formatBundle(params.query, res) : formatHits(params.query, res) }],
+        details: {
+          status: 'ok',
+          context: bundle ? 'bundle' : 'snippets',
+          repo: res.repo,
+          chunks: res.chunks,
+          tookMs: res.tookMs,
+          tookMsTotal,
+          graph: bundle ? state.graph?.value?.stats : undefined,
+          results: res.results,
+        },
+      };
+    } catch (e) {
+      const building = state.indexing
+        ? ` indicizzazione in corso (${state.progress?.done ?? 0}/${state.progress?.total ?? '?'} chunk)`
+        : '';
+      return unavailable(`${e.message}${building}`);
+    }
+  },
+});
+
+/** Aggiunge l'outline a una `read` completa di un file lungo. */
+async function annotateRead(event, ctx) {
+  if (!state?.enabled || !state.repo) return undefined;
+  const first = event.content?.find((c) => c.type === 'text');
+  if (!first) return undefined;
+
+  // `details.truncation.totalLines` è il conteggio vero; il testo può essere troncato a 50 KB.
+  const lineCount = event.details?.truncation?.totalLines ?? first.text.split('\n').length;
+  if (!shouldAnnotateRead(event.input, lineCount)) return undefined;
+
+  const rel = toRepoRel(state.repo, path.resolve(ctx.cwd, String(event.input.path ?? '')));
+  if (!rel) return undefined;
+
+  if (!state.index) await refreshMeta();
+  const outline = outlineText(rel, lineCount, state.index?.chunks);
+  if (!outline) return undefined;
+
+  return { content: [{ type: 'text', text: outline }, ...event.content] };
+}
+
+function statusReport() {
+  if (!state) return 'codeindex: nessun repository git nella directory corrente';
+  const i = state.index;
+  const lines = [
+    `repo        : ${state.repo}`,
+    `stato       : ${state.enabled ? 'attivo' : 'disattivato'}${state.indexing ? ' · indicizzazione in corso' : ''}`,
+  ];
+  if (state.progress) lines.push(`progresso   : ${state.progress.done}/${state.progress.total} chunk`);
+  if (i) {
+    lines.push(`file        : ${i.stats?.files ?? '?'} (${fmtBytes(i.stats?.bytes ?? 0)})`);
+    lines.push(`chunk       : ${i.chunks.length} · ${i.dims}d · ${i.model} (${i.dtype})`);
+    lines.push(`head        : ${i.head ?? '?'}`);
+    lines.push(`aggiornato  : ${i.updatedAt}`);
+  } else {
+    lines.push('indice      : assente (usa /codeindex reindex)');
+  }
+  const runtime = embeddingStatus();
+  lines.push(`runtime     : ${runtime.profile ? formatProfile(runtime.profile) : 'non caricato'}`);
+  if (i?.device) lines.push(`profilo indice: ${formatProfile(i)}`);
+  if (state.error) lines.push(`ultimo errore: ${state.error}`);
+  return lines.join('\n');
+}
+
+export default function codeindexExtension(pi) {
+  pi.registerTool(searchCode);
+
+  pi.registerCommand('codeindex', {
+    description: 'Indice e embedding locali (status|reindex|enable|disable|config|configure|doctor)',
+    handler: async (args, ctx) => {
+      const [sub = 'status', ...rest] = (args ?? '').trim().split(/\s+/).filter(Boolean);
+      // Configurazione/diagnostica funzionano anche fuori da git o con indice spento.
+      try {
+        if (sub === 'config') {
+          ctx.ui.notify(await configCommand(rest), 'info');
+          return;
+        }
+        if (sub === 'configure') {
+          const result = await configure(ctx);
+          if (result) ctx.ui.notify(result, 'info');
+          return;
+        }
+        if (sub === 'doctor') {
+          const options = parseDoctorArgs(rest);
+          if (options.probe) ctx.ui.notify('codeindex: prova isolata del modello (può scaricare i pesi, timeout 120 s per backend)…', 'info');
+          const report = await doctor(options);
+          ctx.ui.notify(options.json ? JSON.stringify(report) : formatDoctor(report), report.ok ? 'info' : 'warning');
+          return;
+        }
+      } catch (e) {
+        ctx.ui.notify(`codeindex: ${e.message}`, 'error');
+        return;
+      }
+      if (!state) {
+        ctx.ui.notify('codeindex: nessun repository git nella directory corrente', 'warning');
+        return;
+      }
+      if (sub === 'status') {
+        // La sessione può chiedere lo stato prima che il refresh in background
+        // abbia finito: meglio aspettare che mentire ("indice assente").
+        if (!state.index) await refreshMeta();
+        showStatus(ctx);
+        ctx.ui.notify(statusReport(), 'info');
+        return;
+      }
+      if (sub === 'reindex') {
+        if (state.indexing) {
+          ctx.ui.notify('codeindex: indicizzazione già in corso', 'warning');
+          return;
+        }
+        ctx.ui.notify('codeindex: reindex avviato in background', 'info');
+        void runIndex(ctx, { force: (args ?? '').includes('--force') });
+        return;
+      }
+      if (sub === 'enable' || sub === 'disable') {
+        state.enabled = sub === 'enable';
+        if (state.enabled) {
+          // Un abort precedente resta sul vecchio controller: senza rinnovarlo
+          // ogni run futuro uscirebbe subito.
+          state.abort = new AbortController();
+          state.error = null;
+          if (!state.watcher) startWatcher(ctx);
+        } else {
+          stopBackground(); // watcher, coda, run in corso e rerun pendente
+        }
+        showStatus(ctx);
+        try {
+          pi.appendEntry(CONFIG_ENTRY, { enabled: state.enabled });
+        } catch {
+          /* stato non persistito: vale per questa sessione */
+        }
+        if (state.enabled) void runIndex(ctx);
+        ctx.ui.notify(`codeindex: ${state.enabled ? 'attivo' : 'disattivato'}`, 'info');
+        return;
+      }
+      ctx.ui.notify('uso: /codeindex status|reindex [--force]|enable|disable|config [show|set CHIAVE VALORE|unset CHIAVE]|configure|doctor [--probe] [--all] [--device DEVICE] [--webgpu-backend auto|vulkan]', 'warning');
+    },
+  });
+
+  // Risorse di sessione: watcher e timer non vanno creati nel factory.
+  pi.on('session_start', async (_event, ctx) => {
+    const repo = repoRoot(ctx.cwd);
+    if (!repo) {
+      state = null;
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+    const st = {
+      repo,
+      enabled: readEnabled(ctx),
+      indexing: false,
+      progress: null,
+      index: null,
+      error: null,
+      rerun: false,
+      abort: new AbortController(),
+      queue: null,
+      watcher: null,
+      graph: null,
+    };
+    st.queue = createDebouncedQueue(() => {
+      if (state === st && st.enabled) void runIndex(ctx);
+    }, { delayMs: DEBOUNCE_MS });
+    state = st;
+    showStatus(ctx);
+    // Non bloccare l'avvio: metadati, watcher e indice corrono in background.
+    void (async () => {
+      await refreshMeta();
+      if (state !== st) return;
+      showStatus(ctx);
+      if (!st.enabled) return;
+      startWatcher(ctx);
+      void runIndex(ctx);
+    })();
+  });
+
+  pi.on('session_shutdown', async () => {
+    stopBackground();
+    invalidateSearcher();
+    state = null;
+  });
+
+  // Una riga stabile nel system prompt rende il tool scopribile; i conteggi
+  // esatti restano nel footer per non invalidare la prompt cache a ogni run.
+  pi.on('before_agent_start', async (event, ctx) => {
+    showStatus(ctx);
+    if (!state?.enabled) return undefined; // spento: nessuna riga nel prompt
+    // Un checkout può cambiare HEAD senza eventi utili del watcher.
+    if (!state.indexing && state.index?.head && headCommit(state.repo) !== state.index.head) {
+      void runIndex(ctx);
+    }
+    const line = promptLine(state?.index?.chunks?.length ?? 0);
+    if (!line) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${line}` };
+  });
+
+  // Invalidazione diretta: `write`/`edit` sanno esattamente che path hanno toccato.
+  pi.on('tool_result', async (event, ctx) => {
+    if (event.isError || !state?.enabled) return undefined;
+    try {
+      if (event.toolName === 'read') return await annotateRead(event, ctx);
+      if (event.toolName === 'write' || event.toolName === 'edit') {
+        markDirty([String(event.input?.path ?? '')]);
+        return undefined;
+      }
+      // Dopo un bash il filesystem può essere cambiato in modo invisibile agli hook.
+      if (event.toolName === 'bash') sweepGitStatus();
+    } catch {
+      return undefined; // un hook non deve mai rompere un tool
+    }
+    return undefined;
+  });
+}