@alucard_24/pi-codeindex 0.0.0-stage → 1.0.0

package/src/present.js

@@ -0,0 +1,177 @@
+// Formattazione per l'agente: funzioni pure, nessun accesso a pi o al disco.
+// Stanno qui, e non in extension.js, perché sono l'unica parte dell'integrazione
+// che vale la pena testare con `node --test` (l'adapter resta sottile).
+
+import path from 'node:path';
+
+export const OUTLINE_MIN_LINES = 300;
+export const OUTLINE_MIN_SYMBOLS = 5;
+export const OUTLINE_MAX_SYMBOLS = 40;
+// Limite di default di `read` (DEFAULT_MAX_LINES): un `limit` a questo valore è
+// una read completa esplicita, non una lettura mirata.
+const FULL_READ_LIMIT = 2000;
+const MAX_PREVIEW_LINES = 2;
+const MAX_PREVIEW_CHARS = 160;
+
+/** 1234 -> "1.2k"; 5230 -> "5.2k". Sotto il migliaio resta il numero esatto. */
+export function fmtK(n) {
+  if (!Number.isFinite(n) || n < 0) return '?';
+  if (n < 1000) return String(Math.round(n));
+  const k = n / 1000;
+  return `${k < 10 ? k.toFixed(1) : Math.round(k)}k`;
+}
+
+/**
+ * Riga di stato per il footer. `undefined` = nessuna riga (nessun repo git).
+ * @param {{repo?: string|null, enabled?: boolean, indexing?: boolean,
+ *          progress?: {done: number, total: number}|null, chunks?: number}} s
+ */
+export function statusLine(s) {
+  if (!s?.repo) return undefined;
+  if (s.enabled === false) return 'codeindex: off';
+  if (s.indexing) {
+    const p = s.progress;
+    return p && p.total > 0
+      ? `codeindex: ${fmtK(p.done)}/${fmtK(p.total)}`
+      : 'codeindex: indicizzazione…';
+  }
+  if (s.chunks > 0) return `codeindex: ${fmtK(s.chunks)} chunk`;
+  return 'codeindex: nessun indice';
+}
+
+/**
+ * Bundle (Fase 4.5): hit + import + importatori + chiamanti euristici dei primi
+ * risultati. Formato compatto: ogni fatto è una riga, il resto è contesto.
+ */
+export function formatBundle(query, res, { contexts = 3 } = {}) {
+  const lines = [formatHitsHead(res), ''];
+  const results = res?.results ?? [];
+  results.forEach((r, i) => {
+    lines.push(`${(r.score ?? 0).toFixed(3)}  ${r.path}:${r.start}-${r.end}  [${r.kind}${r.symbols?.length ? ` · ${r.symbols[0]}` : ''}]${r.stale ? '  STALE' : ''}`);
+    const p = String(r.preview ?? '').split('\n').slice(0, MAX_PREVIEW_LINES);
+    for (const l of p) if (l.trim()) lines.push(`       ${oneLine(l)}`);
+    if (i >= contexts) return;
+    const c = r.context;
+    if (c?.imports?.length) lines.push(`       imports: ${c.imports.join(', ')}`);
+    if (c?.importers?.length) lines.push(`       imported by: ${c.importers.join(', ')}`);
+    for (const caller of c?.callers ?? []) {
+      lines.push(`       caller (heuristic): ${caller.path}:${caller.line} in ${caller.container ?? 'top level'}`);
+    }
+    if (c?.callersTruncated) lines.push('       … more callers not shown');
+  });
+  if (!results.length) {
+    lines.push('No semantic match. Try different wording, or grep for an exact identifier.');
+  } else {
+    if (results.some((r) => r.stale)) {
+      lines.push('STALE = file changed after indexing: re-read it, line numbers may have moved.');
+    }
+    lines.push('Callers are heuristic (identifier scan), not a call graph. Verify before editing.');
+  }
+  return lines.join('\n');
+}
+
+function formatHitsHead(res) {
+  const n = res?.results?.length ?? 0;
+  return `${n} result${n === 1 ? '' : 's'} in ${Math.round(res?.tookMs ?? 0)} ms` +
+    `${res?.chunks ? ` · ${fmtK(res.chunks)} chunks indexed` : ''}`;
+}
+
+/**
+ * Riga iniettata nel system prompt: rende `search_code` scopribile senza
+ * contare le query già presenti nelle dichiarazioni dei tool.
+ * Il conteggio è arrotondato perché il testo resti stabile (prompt cache).
+ */
+export function promptLine(chunks) {
+  if (!chunks || chunks < 100) return null;
+  return (
+    `Code index: ${fmtK(chunks)} chunks of this repository are embedded locally ` +
+    '(search_code). Prefer it to localize code before grep/read; grep stays best for exact strings.'
+  );
+}
+
+const oneLine = (s, n = MAX_PREVIEW_CHARS) => String(s ?? '').replace(/\s+/g, ' ').trim().slice(0, n);
+
+/** Risultati di ricerca in forma compatta: una riga per hit + anteprima breve. */
+export function formatHits(query, res) {
+  const n = res?.results?.length ?? 0;
+  const lines = [formatHitsHead(res)];
+  for (const r of res?.results ?? []) {
+    const sym = r.symbols?.length ? ` · ${r.symbols.slice(0, 3).join(', ')}` : '';
+    const stale = r.stale ? '  STALE' : '';
+    lines.push(
+      `${(r.score ?? 0).toFixed(3)}  ${r.path}:${r.start}-${r.end}  [${r.kind}${sym}]` +
+        `  cos ${(r.cos ?? 0).toFixed(3)} lex ${(r.lex ?? 0).toFixed(2)}${stale}`,
+    );
+    const preview = String(r.preview ?? '').split('\n').slice(0, MAX_PREVIEW_LINES);
+    for (const l of preview) if (l.trim()) lines.push(`       ${oneLine(l)}`);
+  }
+  if (n === 0) {
+    lines.push(
+      'No semantic match. Try a different wording, or grep for an exact identifier — ' +
+        'the index finds concepts, not literal strings.',
+    );
+  } else {
+    if (res?.results?.some((r) => r.stale)) {
+      lines.push('STALE = file changed after indexing: re-read it, line numbers may have moved.');
+    }
+    lines.push('Read the hits you need (read with offset/limit for large files); grep for exact strings.');
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Outline di un file dall'indice: solo simboli, nessun contenuto.
+ * @returns {string|null} null se il file non ha abbastanza simboli indicizzati.
+ */
+export function outlineText(relPath, lineCount, chunks, {
+  minLines = OUTLINE_MIN_LINES,
+  minSymbols = OUTLINE_MIN_SYMBOLS,
+  maxSymbols = OUTLINE_MAX_SYMBOLS,
+} = {}) {
+  if (!(lineCount > minLines)) return null;
+  const mine = (chunks ?? [])
+    .filter((c) => c.path === relPath && c.symbol && c.kind !== 'preamble')
+    .sort((a, b) => a.start - b.start);
+  const seen = new Set();
+  const picked = [];
+  for (const c of mine) {
+    if (seen.has(c.symbol)) continue;
+    seen.add(c.symbol);
+    picked.push(c);
+  }
+  if (picked.length < minSymbols) return null;
+  const shown = picked.slice(0, maxSymbols);
+  const lines = [
+    `[outline from code index · ${relPath} · ${lineCount} lines · ${picked.length} symbols]`,
+  ];
+  for (const c of shown) {
+    const range = `${c.start}-${c.end}`.padEnd(12);
+    lines.push(`${range}${c.kind.padEnd(10)}${c.symbol}`);
+  }
+  if (picked.length > shown.length) lines.push(`… ${picked.length - shown.length} more (search_code for details)`);
+  lines.push('[full file content follows]');
+  return lines.join('\n');
+}
+
+/**
+ * Decide se annotare una `read`. L'outline serve a chi legge un file intero:
+ * una read mirata (offset/limit espliciti) non lo riceve.
+ * `offset: 1`/`limit: 2000` sono la read completa scritta in modo esplicito.
+ */
+export function shouldAnnotateRead(input, lineCount, { minLines = OUTLINE_MIN_LINES } = {}) {
+  if (!(lineCount > minLines)) return false;
+  const offset = input?.offset;
+  if (offset !== undefined && offset !== null && offset > 1) return false;
+  const limit = input?.limit;
+  if (limit !== undefined && limit !== null && limit < FULL_READ_LIMIT) return false;
+  return true;
+}
+
+/** Path assoluto -> relativo al repo, o null se esce dal repo. */
+export function toRepoRel(repo, absPath) {
+  if (!repo || !absPath) return null;
+  const abs = path.resolve(absPath);
+  const rel = path.relative(repo, abs);
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return rel.split(path.sep).join('/');
+}

package/src/probe.js

@@ -0,0 +1,20 @@
+// Entry point interno, eseguito solo da doctor --probe in un processo isolato.
+import { embed, cosine, getEmbeddingProfile, embeddingStatus, getEmbedder } from './embed.js';
+
+let result;
+try {
+  const t0 = performance.now();
+  const same = 'title: args.ts | text: export function parseArgs(argv) { return argv.slice(2); }';
+  const other = 'title: math.py | text: def factorial(n): return 1 if n < 2 else n * factorial(n - 1)';
+  const [a, b, c] = await embed([same, same, other]);
+  const cosSame = cosine(a, b);
+  const cosOther = cosine(a, c);
+  if (cosSame < 0.999 || cosOther > 0.9999) throw new Error(`smoke test discriminazione fallito: stesso=${cosSame}, diverso=${cosOther}`);
+  result = { ok: true, profile: await getEmbeddingProfile(), elapsedMs: Math.round(performance.now() - t0),
+    cosSame, cosOther, attempts: embeddingStatus().attempts };
+  await (await getEmbedder()).dispose();
+} catch (e) {
+  result = { ok: false, error: String(e.message ?? e), attempts: embeddingStatus().attempts };
+}
+if (process.send) process.send(result, () => process.exit(result.ok ? 0 : 1));
+else { console.log(JSON.stringify(result)); process.exitCode = result.ok ? 0 : 1; }

package/src/search.js

@@ -0,0 +1,189 @@
+// Ricerca ibrida: coseno sui vettori + overlap lessicale su path/simboli/preview.
+// Due stadi: il lessico viene valutato solo sui migliori candidati del coseno
+// (200 su 30k), così una query resta < 300 ms senza un indice invertito.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { embedQuery, getEmbeddingProfile } from './embed.js';
+import { assertCompatibleIndex } from './backend.js';
+import { indexDir, indexPaths, loadIndex } from './store.js';
+import { repoRoot, sha1 } from './util.js';
+
+export const WEIGHT_COS = 0.75;
+export const WEIGHT_LEX = 0.25;
+const CANDIDATES = 200;
+const PREVIEW_LINES = 3;
+
+const STOPWORDS = new Set([
+  'the', 'and', 'for', 'with', 'from', 'into', 'this', 'that', 'are', 'was',
+  'how', 'what', 'where', 'when', 'which', 'does', 'used', 'use', 'using',
+  'di', 'del', 'della', 'dei', 'delle', 'che', 'chi', 'cui', 'per', 'con',
+  'una', 'uno', 'gli', 'nel', 'nella', 'nei', 'come', 'dove', 'quando',
+  'viene', 'vengono', 'sono', 'essere', 'alla', 'allo', 'agli', 'sul', 'sui',
+  'la', 'le', 'lo', 'il', 'un', 'uno', 'si', 'non', 'più', 'dei', 'delle',
+]);
+
+/** camelCase/snake_case/kebab -> token minuscoli, stopword rimosse. */
+export function tokenize(text) {
+  return String(text ?? '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((t) => t.length >= 2 && !STOPWORDS.has(t));
+}
+
+export function lexicalOverlap(queryTokens, chunk) {
+  if (queryTokens.size === 0) return 0;
+  // Path e simboli sono segnali forti; la preview (200 char) è un segnale debole:
+  // un documento lungo che parla dell'argomento non deve battere il file che lo implementa.
+  const strong = new Set(tokenize([chunk.path, chunk.symbol ?? '', ...(chunk.symbols ?? [])].join(' ')));
+  const weak = new Set(tokenize(chunk.preview ?? ''));
+  let score = 0;
+  for (const t of queryTokens) score += strong.has(t) ? 1 : weak.has(t) ? 0.5 : 0;
+  return score / queryTokens.size;
+}
+
+function dot(a, aOff, b) {
+  let s = 0;
+  for (let i = 0; i < b.length; i++) s += a[aOff + i] * b[i];
+  return s;
+}
+
+// Cache in-process: un indice da 30k chunk pesa ~100 MB di JSON + 92 MB di vettori.
+// Rileggerlo a ogni query costerebbe centinaia di ms; lo stat di due file costa ~0,1 ms.
+// La chiave d'invalidazione è la coppia (size, mtime) dei due file dell'indice, quindi
+// anche un reindex fatto da un altro processo viene visto.
+const _cache = new Map();
+const MAX_CACHED = 2;
+
+async function stampOf(repo) {
+  const { json, bin } = indexPaths(indexDir(repo));
+  try {
+    const [a, b] = await Promise.all([fs.stat(json), fs.stat(bin)]);
+    return `${a.size}:${a.mtimeMs}:${b.size}:${b.mtimeMs}`;
+  } catch {
+    return null;
+  }
+}
+
+/** Butta via l'indice in memoria (dopo un reindex, o alla chiusura della sessione). */
+export function invalidateSearcher(root) {
+  if (root) _cache.delete(path.resolve(root));
+  else _cache.clear();
+}
+
+export async function loadSearcher(root, { refresh = false } = {}) {
+  const repo = path.resolve(root ?? repoRoot(process.cwd()) ?? process.cwd());
+  const stamp = await stampOf(repo);
+  const hit = _cache.get(repo);
+  if (!refresh && hit && stamp && hit.stamp === stamp) return hit.value;
+
+  const { index, vectors } = await loadIndex(repo);
+  if (!index || !vectors || vectors.length === 0) {
+    throw new Error(`nessun indice per ${repo}: esegui "index" prima`);
+  }
+  const value = { repo, index, vectors };
+  if (stamp) {
+    _cache.delete(repo);
+    _cache.set(repo, { stamp, value });
+    while (_cache.size > MAX_CACHED) _cache.delete(_cache.keys().next().value);
+  }
+  return value;
+}
+
+/**
+ * L1 — provenienza: confronta l'hash su disco con quello indicizzato.
+ * Costa una lettura per file distinto (≤ k file, cap 1 MB): non dipende dal
+ * watcher, quindi è vero anche se la sessione non ha visto la modifica.
+ */
+async function markStale(repo, results) {
+  const seen = new Map();
+  for (const r of results) {
+    if (seen.has(r.path)) {
+      r.stale = seen.get(r.path);
+      continue;
+    }
+    let stale = true;
+    try {
+      const buf = await fs.readFile(path.resolve(repo, r.path));
+      stale = sha1(buf) !== r.fileHash;
+    } catch {
+      stale = true; // file sparito: non fidarsi del risultato
+    }
+    seen.set(r.path, stale);
+    r.stale = stale;
+  }
+}
+
+export async function previewOf(repo, chunk) {
+  try {
+    const abs = path.resolve(repo, chunk.path);
+    if (!abs.startsWith(repo + path.sep)) return null; // niente path fuori dal repo
+    const text = await fs.readFile(abs, 'utf8');
+    const lines = text.split('\n').slice(chunk.start - 1, Math.min(chunk.end, chunk.start - 1 + PREVIEW_LINES));
+    return lines.map((l) => l.trimEnd()).filter((l, i, arr) => l !== '' || i < arr.length - 1).join('\n');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @returns {Promise<{results:Array, tookMs:number, candidates:number}>}
+ */
+export async function search(query, { root, k = 8, pathPrefix = null, maxPerFile = 2, checkStale = false } = {}) {
+  const t0 = performance.now();
+  const { repo, index, vectors } = await loadSearcher(root);
+  assertCompatibleIndex(index, await getEmbeddingProfile());
+  const qVec = await embedQuery(query);
+  const qTokens = new Set(tokenize(query));
+  const dims = index.dims;
+
+  const scored = [];
+  for (let i = 0; i < index.chunks.length; i++) {
+    const c = index.chunks[i];
+    if (pathPrefix && !c.path.startsWith(pathPrefix)) continue;
+    scored.push({ i, cos: dot(vectors, i * dims, qVec[0]) });
+  }
+  scored.sort((a, b) => b.cos - a.cos);
+  const top = scored.slice(0, Math.min(CANDIDATES, scored.length));
+
+  const results = top.map(({ i, cos }) => {
+    const c = index.chunks[i];
+    const lex = lexicalOverlap(qTokens, c);
+    return {
+      path: c.path,
+      start: c.start,
+      end: c.end,
+      symbol: c.symbol,
+      symbols: c.symbols ?? (c.symbol ? [c.symbol] : []),
+      kind: c.kind,
+      fileHash: c.fileHash,
+      score: WEIGHT_COS * cos + WEIGHT_LEX * lex,
+      cos,
+      lex,
+    };
+  });
+  results.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.start - b.start);
+  // Diversità: senza cap, un piano di 300 KB occupa tutti gli slot e nasconde il codice.
+  const perFile = new Map();
+  const final = [];
+  for (const r of results) {
+    const n = perFile.get(r.path) ?? 0;
+    if (n >= maxPerFile) continue;
+    perFile.set(r.path, n + 1);
+    final.push(r);
+    if (final.length >= k) break;
+  }
+  for (const r of final) r.preview = await previewOf(repo, r);
+  if (checkStale && final.length) await markStale(repo, final);
+
+  return {
+    repo,
+    results: final,
+    tookMs: Math.round((performance.now() - t0) * 10) / 10,
+    candidates: top.length,
+    chunks: index.chunks.length,
+    stale: final.some((r) => r.stale),
+  };
+}

package/src/store.js

@@ -0,0 +1,142 @@
+// Storage a due file: index.json (metadati + chunk senza testo) e vectors.bin.
+// Niente database, niente dipendenze. Salvataggio atomico (tmp + rename).
+
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { sha1 } from './util.js';
+
+export const STORE_VERSION = 2;
+
+export function cacheRoot() {
+  return path.join(os.homedir(), '.cache', 'pi-codeindex');
+}
+
+export function indexDir(repoRoot) {
+  return path.join(cacheRoot(), sha1(path.resolve(repoRoot)));
+}
+
+export function indexPaths(dir) {
+  return {
+    dir,
+    json: path.join(dir, 'index.json'),
+    bin: path.join(dir, 'vectors.bin'),
+    cache: path.join(dir, 'embed-cache.json'), // ripresa dopo interruzione
+  };
+}
+
+export async function loadIndex(repoRoot) {
+  const { json, bin } = indexPaths(indexDir(repoRoot));
+  try {
+    const raw = await fs.readFile(json, 'utf8');
+    const index = JSON.parse(raw);
+    let vectors = null;
+    try {
+      const buf = await fs.readFile(bin);
+      const expected = index.chunks.length * index.dims;
+      vectors = unpackVectors(buf, index.dims, index.chunks.length);
+      // Due rename non sono una transazione: il digest lega il manifest ai
+      // vettori anche durante scritture concorrenti con profili differenti.
+      if (vectors.length !== expected || !index.vectorsHash ||
+          createHash('sha256').update(buf).digest('hex') !== index.vectorsHash) vectors = null;
+    } catch {
+      vectors = null; // indice senza vettori: si ricostruisce
+    }
+    return { index, vectors };
+  } catch {
+    return { index: null, vectors: null };
+  }
+}
+
+export async function saveIndex(repoRoot, index, vectors) {
+  const paths = indexPaths(indexDir(repoRoot));
+  await fs.mkdir(paths.dir, { recursive: true });
+  const token = randomUUID();
+  const binTmp = `${paths.bin}.${token}.tmp`;
+  const jsonTmp = `${paths.json}.${token}.tmp`;
+  const packed = packVectors(vectors, index.dims);
+  const vectorsHash = createHash('sha256').update(packed).digest('hex');
+  try {
+    await fs.writeFile(binTmp, packed);
+    await fs.writeFile(jsonTmp, JSON.stringify({ ...index, vectorsHash }));
+    await fs.rename(binTmp, paths.bin);
+    await fs.rename(jsonTmp, paths.json);
+  } finally {
+    await Promise.all([fs.rm(binTmp, { force: true }), fs.rm(jsonTmp, { force: true })]);
+  }
+  return paths;
+}
+
+/** righe (Float32Array[] | Float32Array) -> Buffer contiguo little-endian. */
+export function packVectors(vectors, dims) {
+  const rows = vectors instanceof Float32Array ? vectors.length / dims : vectors.length;
+  const out = new Float32Array(rows * dims);
+  if (vectors instanceof Float32Array) {
+    out.set(vectors);
+  } else {
+    for (let i = 0; i < rows; i++) out.set(vectors[i], i * dims);
+  }
+  return Buffer.from(out.buffer, out.byteOffset, out.byteLength);
+}
+
+export function unpackVectors(buf, dims, expectedRows) {
+  if (!buf || buf.length === 0) return new Float32Array(0);
+  const bytes = expectedRows ? Math.min(buf.length, expectedRows * dims * 4) : buf.length;
+  if (buf.byteOffset % 4 === 0) {
+    return new Float32Array(buf.buffer, buf.byteOffset, bytes / 4);
+  }
+  const copy = new Uint8Array(bytes);
+  copy.set(buf.subarray(0, bytes));
+  return new Float32Array(copy.buffer, 0, bytes / 4);
+}
+
+/** Cache di ripresa: identità chunk -> vettore. Sopravvive a un run interrotto. */
+export async function loadEmbedCache(repoRoot) {
+  const { cache } = indexPaths(indexDir(repoRoot));
+  try {
+    const obj = JSON.parse(await fs.readFile(cache, 'utf8'));
+    const out = new Map();
+    for (const [hash, b64] of Object.entries(obj)) {
+      const buf = Buffer.from(b64, 'base64');
+      if (buf.length === 768 * 4) out.set(hash, new Float32Array(buf.buffer, buf.byteOffset, 768));
+    }
+    return out;
+  } catch {
+    return new Map();
+  }
+}
+
+export async function saveEmbedCache(repoRoot, map) {
+  if (map.size === 0) return;
+  const { dir, cache } = indexPaths(indexDir(repoRoot));
+  await fs.mkdir(dir, { recursive: true });
+  const obj = {};
+  for (const [hash, vec] of map) obj[hash] = Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength).toString('base64');
+  const tmp = `${cache}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(obj));
+  await fs.rename(tmp, cache);
+}
+
+export async function clearEmbedCache(repoRoot) {
+  const { cache } = indexPaths(indexDir(repoRoot));
+  await fs.rm(cache, { force: true });
+}
+
+export async function removeIndex(repoRoot) {
+  const { dir } = indexPaths(indexDir(repoRoot));
+  await fs.rm(dir, { recursive: true, force: true });
+}
+
+export async function indexSize(repoRoot) {
+  const paths = indexPaths(indexDir(repoRoot));
+  let total = 0;
+  for (const p of [paths.json, paths.bin]) {
+    try {
+      total += (await fs.stat(p)).size;
+    } catch {
+      /* file assente */
+    }
+  }
+  return total;
+}

package/src/sync.js

@@ -0,0 +1,106 @@
+// Sincronizzazione: quali file meritano una riconciliazione.
+//
+// Non facciamo re-index per singolo path: `indexRepo` è già incrementale
+// (hash per file → riuso dei vettori) e su un repo da 2.872 file costa ~0,7 s.
+// Quindi la politica è: raccogli i path sporchi, attendi un debounce, riconcilia
+// tutto una volta. Meno codice, nessun indice parziale da mantenere coerente.
+
+import path from 'node:path';
+import { LANG_BY_EXT } from './chunker.js';
+
+/** Directory che il watcher non deve nemmeno guardare (oltre a quelle di git). */
+export const IGNORED_DIRS = new Set([
+  '.git', 'node_modules', '.venv', 'venv', '__pycache__', 'dist', 'build', 'out',
+  'target', 'vendor', '.next', '.nuxt', '.cache', '.openlore', '.pi', 'coverage',
+]);
+
+const extOf = (p) => {
+  const m = /\.[^./]+$/.exec(p);
+  return m ? m[0].toLowerCase() : '';
+};
+
+/** Path relativo al repo -> normalizzato con '/', o null se non è indicizzabile. */
+export function watchablePath(rel, root) {
+  if (!rel) return null;
+  let p = String(rel).replace(/\\/g, '/');
+  if (path.isAbsolute(p)) {
+    if (!root) return null;
+    const r = path.relative(root, p).replace(/\\/g, '/');
+    if (!r || r.startsWith('..') || path.isAbsolute(r)) return null;
+    p = r;
+  }
+  const segments = path.posix.normalize(p).split('/').filter(Boolean);
+  if (segments.length === 0 || segments[0] === '..') return null;
+  p = segments.join('/');
+  if (segments.some((s) => IGNORED_DIRS.has(s))) return null;
+  if (!(extOf(p) in LANG_BY_EXT)) return null;
+  return segments.join('/');
+}
+
+/** Filtra e deduplica una lista di path (watcher, hook dei tool, git status). */
+export function filterDirty(paths, root) {
+  const out = new Set();
+  for (const p of paths ?? []) {
+    const w = watchablePath(p, root);
+    if (w) out.add(w);
+  }
+  return out;
+}
+
+/**
+ * `git status --porcelain -z`: `XY path\0`, con `R`/`C` seguiti dal path
+ * originale come record successivo. Restituisce entrambi i lati del rename:
+ * un file rinominato va re-embedato (il path fa parte dell'identità).
+ */
+export function parsePorcelainStatus(z) {
+  const parts = String(z ?? '').split('\0');
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    const rec = parts[i];
+    if (!rec || rec.length < 4) continue;
+    const xy = rec.slice(0, 2);
+    out.push(rec.slice(3));
+    if (xy[0] === 'R' || xy[0] === 'C') {
+      const from = parts[++i];
+      if (from) out.push(from);
+    }
+  }
+  return out;
+}
+
+/**
+ * Coda con debounce: gli eventi ravvicinati diventano una sola riconciliazione.
+ * `onFlush` riceve il Set dei path accumulati. Restituisce {add, cancel, pending}.
+ */
+export function createDebouncedQueue(onFlush, {
+  delayMs = 800,
+  setTimeout: setTimer = setTimeout,
+  clearTimeout: clearTimer = clearTimeout,
+} = {}) {
+  let timer = null;
+  let dirty = new Set();
+
+  const flush = () => {
+    timer = null;
+    const batch = dirty;
+    dirty = new Set();
+    if (batch.size > 0) onFlush(batch);
+  };
+
+  return {
+    add(paths) {
+      for (const p of paths ?? []) dirty.add(p);
+      if (dirty.size === 0) return;
+      if (timer) clearTimer(timer);
+      timer = setTimer(flush, delayMs);
+    },
+    cancel() {
+      if (timer) clearTimer(timer);
+      timer = null;
+      dirty = new Set();
+    },
+    get pending() {
+      return dirty.size;
+    },
+  };
+}