pi-jev-guard 0.3.3 → 0.5.0

package/src/verification.ts

@@ -0,0 +1,589 @@
+/**
+ * Verifica deterministica delle modifiche osservate nella sessione.
+ *
+ * Diversa da Jev: qui non si prova a "capire" se il codice è corretto.
+ * Si conserva soltanto un fatto osservabile: edit/write riusciti e l'esito
+ * di comandi dichiarati dal progetto. Il footer finale è costruito da questi
+ * dati, non dal testo del modello, quindi non può inventare test superati.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+export type VerificationMode = "warn" | "repair" | "hold";
+
+/** Impostazioni condivise; i comandi eseguibili restano nel manifest locale. */
+export interface VerificationSettings {
+  /** Opt-in: nessun footer, repair o comando automatico finché è false. */
+  enabled: boolean;
+  /** warn = footer; repair = un tentativo privato; hold = blocco rigoroso. */
+  mode: VerificationMode;
+  /** File JSON relativo alla root del progetto, mai un comando generato dal modello. */
+  manifestPath: string;
+  /** Rigenerazioni massime per risposta quando mancano/falliscono check. */
+  maxRepairs: number;
+  /** Timeout massimo predefinito dei check avviati da jev_verify o /jev verify. */
+  commandTimeoutMs: number;
+  /** Output massimo restituito al modello per un check fallito. */
+  outputChars: number;
+  /** Limite di check eseguibili in una richiesta `recommended`/`all`. */
+  maxCommands: number;
+}
+
+export interface VerificationCheck {
+  /** Id stabile, usato da /jev verify e dal tool jev_verify. */
+  id: string;
+  /** Comando esplicitamente approvato dal manifest del progetto. */
+  command: string;
+  /** Glob dei file a cui il check si applica; assente = tutte le modifiche. */
+  files?: string[];
+  description?: string;
+  /** Override bounded dal timeout globale del guard. */
+  timeoutMs?: number;
+}
+
+export interface VerificationManifest {
+  version: 1;
+  checks: VerificationCheck[];
+}
+
+export type LoadedVerificationManifest =
+  | { ok: true; path: string; manifest: VerificationManifest; fingerprint: string }
+  | { ok: false; path?: string; error: string };
+
+/** Manifest acquisito a inizio sessione o su comando utente esplicito. */
+export type VerificationManifestTrust =
+  | { ok: true; cwd: string; path: string; manifest: VerificationManifest; fingerprint: string }
+  | { ok: false; cwd: string; error: string };
+
+/** Un edit/write osservato con successo; non pretende di vedere modifiche via shell. */
+export interface ObservedModification {
+  path: string;
+  seq: number;
+}
+
+export interface VerificationRun {
+  id: string;
+  command: string;
+  ok: boolean;
+  /** Assente quando il tool non espone l'exit code. */
+  exitCode?: number;
+  /**
+   * Ordine di INIZIO del check. Deve essere successivo al completamento
+   * dell'edit pertinente: un test partito in parallelo prima dell'edit non
+   * diventa fresco solo perché il suo tool_result arriva dopo.
+   */
+  seq: number;
+  source: "jev_verify" | "bash" | "powershell" | "manual";
+}
+
+export interface VerificationState {
+  modifications: ObservedModification[];
+  runs: VerificationRun[];
+}
+
+export type VerificationCheckState = "passed" | "failed" | "pending";
+
+export interface VerificationCheckStatus {
+  check: VerificationCheck;
+  state: VerificationCheckState;
+  /** Ultimo run dopo l'ultima modifica pertinente, se presente. */
+  run?: VerificationRun;
+  latestRelevantEditSeq: number;
+}
+
+export interface VerificationStatus {
+  changedFiles: string[];
+  /** Errore/mancanza manifest: non è una prova negativa sul codice. */
+  manifestError?: string;
+  checks: VerificationCheckStatus[];
+  /** Esistono check dichiarati che corrispondono alle modifiche osservate. */
+  actionable: boolean;
+  hasPending: boolean;
+  hasFailed: boolean;
+  allPassed: boolean;
+}
+
+export function createVerificationState(): VerificationState {
+  return { modifications: [], runs: [] };
+}
+
+/**
+ * Trasforma un path tool in un path relativo al progetto. I path fuori root
+ * non entrano nel manifest locale: possono essere riportati dal modello, ma
+ * non diventano falsamente coperti da un check del progetto corrente.
+ */
+export function normalizeObservedPath(path: unknown, cwd: string): string | undefined {
+  if (typeof path !== "string" || !path.trim()) return undefined;
+  const root = resolve(cwd);
+  const absolute = resolve(root, path.trim());
+  const rel = relative(root, absolute);
+  if (!rel || rel === "." || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    return undefined;
+  }
+  return rel.split(sep).join("/");
+}
+
+/** Registra l'ultima modifica riuscita per path; cap conservativo della memoria. */
+export function recordObservedModification(
+  state: VerificationState,
+  path: string,
+  seq: number,
+): void {
+  const existing = state.modifications.find((entry) => entry.path === path);
+  if (existing) {
+    existing.seq = seq;
+  } else {
+    state.modifications.push({ path, seq });
+  }
+  if (state.modifications.length > 100) {
+    state.modifications.sort((a, b) => a.seq - b.seq);
+    state.modifications.splice(0, state.modifications.length - 100);
+  }
+}
+
+/** Registra un esito reale; più run dello stesso id sono mantenuti per il freshness check. */
+export function recordVerificationRun(
+  state: VerificationState,
+  run: VerificationRun,
+): void {
+  state.runs.push({ ...run });
+  if (state.runs.length > 200) state.runs.splice(0, state.runs.length - 200);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const CHECK_ID = /^[a-zA-Z][a-zA-Z0-9_-]{0,63}$/;
+
+function parseFiles(value: unknown, index: number): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.length > 100) {
+    throw new Error(`checks[${index}].files deve essere un array non vuoto (max 100)`);
+  }
+  const files = value.map((item, itemIndex) => {
+    if (typeof item !== "string" || !item.trim() || item.length > 240) {
+      throw new Error(`checks[${index}].files[${itemIndex}] non valido`);
+    }
+    const normalized = item.trim().replace(/\\/g, "/");
+    if (normalized.startsWith("/") || normalized.includes("\0")) {
+      throw new Error(`checks[${index}].files[${itemIndex}] deve essere un glob relativo`);
+    }
+    return normalized;
+  });
+  return [...new Set(files)];
+}
+
+/** Parser stretto: un manifest malformato non esegue mai comandi. */
+export function parseVerificationManifest(value: unknown): VerificationManifest {
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.checks)) {
+    throw new Error("manifest richiede { version: 1, checks: [...] }");
+  }
+  if (value.checks.length === 0 || value.checks.length > 50) {
+    throw new Error("manifest.checks deve contenere da 1 a 50 check");
+  }
+  const seen = new Set<string>();
+  const checks: VerificationCheck[] = value.checks.map((raw, index) => {
+    if (!isRecord(raw)) throw new Error(`checks[${index}] non è un oggetto`);
+    const id = raw.id;
+    const command = raw.command;
+    if (typeof id !== "string" || !CHECK_ID.test(id)) {
+      throw new Error(`checks[${index}].id non valido`);
+    }
+    if (seen.has(id)) throw new Error(`id check duplicato: ${id}`);
+    seen.add(id);
+    if (
+      typeof command !== "string" ||
+      !command.trim() ||
+      command.length > 2000 ||
+      command.includes("\0") ||
+      /[\r\n]/.test(command)
+    ) {
+      throw new Error(`checks[${index}].command non valido`);
+    }
+    const description = raw.description;
+    if (description !== undefined && (typeof description !== "string" || description.length > 300)) {
+      throw new Error(`checks[${index}].description non valida`);
+    }
+    const timeoutMs = raw.timeoutMs;
+    if (timeoutMs !== undefined && (
+      typeof timeoutMs !== "number" ||
+      !Number.isInteger(timeoutMs) ||
+      timeoutMs < 1000 ||
+      timeoutMs > 3_600_000
+    )) {
+      throw new Error(`checks[${index}].timeoutMs non valido`);
+    }
+    const files = parseFiles(raw.files, index);
+    return {
+      id,
+      command: command.trim(),
+      ...(files ? { files } : {}),
+      ...(typeof description === "string" && description ? { description } : {}),
+      ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+    };
+  });
+  return { version: 1, checks };
+}
+
+/** Risolve un manifest esclusivamente dentro la root progetto. */
+export function resolveManifestPath(cwd: string, manifestPath: string): string | undefined {
+  if (!manifestPath.trim()) return undefined;
+  const root = resolve(cwd);
+  const target = resolve(root, manifestPath.trim());
+  const rel = relative(root, target);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return undefined;
+  return target;
+}
+
+/** Il modello non può alterare la policy che autorizza i suoi comandi. */
+export function isVerificationManifestPath(
+  path: unknown,
+  cwd: string,
+  manifestPath: string,
+): boolean {
+  if (typeof path !== "string" || !path.trim()) return false;
+  const manifest = resolveManifestPath(cwd, manifestPath);
+  if (!manifest) return false;
+  return resolve(cwd, path.trim()) === manifest;
+}
+
+function fingerprintText(text: string): string {
+  // Non è una firma/autorizzazione remota: serve a rilevare con robustezza
+  // una mutazione del file dopo la snapshot locale trusted.
+  return createHash("sha256").update(text).digest("hex");
+}
+
+export function loadVerificationManifest(
+  cwd: string,
+  manifestPath: string,
+): LoadedVerificationManifest {
+  const path = resolveManifestPath(cwd, manifestPath);
+  if (!path) {
+    return { ok: false, error: "percorso manifest non valido: deve restare dentro il progetto" };
+  }
+  if (!existsSync(path)) {
+    return { ok: false, path, error: `manifest non trovato: ${manifestPath}` };
+  }
+  try {
+    const text = readFileSync(path, "utf8");
+    const parsed = JSON.parse(text);
+    return {
+      ok: true,
+      path,
+      manifest: parseVerificationManifest(parsed),
+      fingerprint: fingerprintText(text),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      path,
+      error: `manifest non valido: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+/** Acquisisce la policy di esecuzione dal disco in un punto esplicitamente utente. */
+export function trustVerificationManifest(
+  cwd: string,
+  manifestPath: string,
+): VerificationManifestTrust {
+  const loaded = loadVerificationManifest(cwd, manifestPath);
+  return loaded.ok
+    ? {
+        ok: true,
+        cwd: resolve(cwd),
+        path: loaded.path,
+        manifest: loaded.manifest,
+        fingerprint: loaded.fingerprint,
+      }
+    : { ok: false, cwd: resolve(cwd), error: loaded.error };
+}
+
+/**
+ * Ritorna il manifest acquisito, ma rifiuta mutazioni del file dopo il trust.
+ * I comandi vengono poi selezionati dall'oggetto in memoria acquisito, non
+ * dal file corrente: un agente non può scrivere un comando e farlo eseguire
+ * nella stessa sessione.
+ */
+export function trustedVerificationManifest(
+  trust: VerificationManifestTrust | undefined,
+  cwd: string,
+  manifestPath: string,
+): LoadedVerificationManifest {
+  if (!trust) return { ok: false, error: "manifest non ancora acquisito; usa /jev verification reload" };
+  if (!trust.ok) return { ok: false, error: trust.error };
+  if (trust.cwd !== resolve(cwd)) {
+    return { ok: false, error: "manifest acquisito per un'altra directory; usa /jev verification reload" };
+  }
+  const current = loadVerificationManifest(cwd, manifestPath);
+  if (!current.ok) return current;
+  if (current.path !== trust.path || current.fingerprint !== trust.fingerprint) {
+    return {
+      ok: false,
+      path: current.path,
+      error: "manifest modificato dopo l'acquisizione; controllalo e usa /jev verification reload",
+    };
+  }
+  return {
+    ok: true,
+    path: trust.path,
+    manifest: trust.manifest,
+    fingerprint: trust.fingerprint,
+  };
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let source = "^";
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === "*") {
+      if (pattern[i + 1] === "*") {
+        if (pattern[i + 2] === "/") {
+          source += "(?:.*/)?";
+          i += 2;
+        } else {
+          source += ".*";
+          i++;
+        }
+      } else {
+        source += "[^/]*";
+      }
+    } else if (char === "?") {
+      source += "[^/]";
+    } else {
+      source += char.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+/** True se il check è pertinente a un file; `files` assente significa globale. */
+export function checkMatchesPath(check: VerificationCheck, path: string): boolean {
+  if (!check.files || check.files.length === 0) return true;
+  return check.files.some((pattern) => globToRegExp(pattern).test(path));
+}
+
+function latestRunAfter(
+  state: VerificationState,
+  id: string,
+  afterSeq: number,
+): VerificationRun | undefined {
+  return state.runs
+    .filter((run) => run.id === id && run.seq > afterSeq)
+    .sort((a, b) => b.seq - a.seq)[0];
+}
+
+/** Stato derivato esclusivamente da modifiche e run osservati. */
+export function buildVerificationStatus(
+  state: VerificationState,
+  loaded: LoadedVerificationManifest,
+): VerificationStatus {
+  const modifications = [...state.modifications].sort((a, b) => a.path.localeCompare(b.path));
+  const changedFiles = modifications.map((entry) => entry.path);
+  if (changedFiles.length === 0) {
+    return {
+      changedFiles,
+      ...(loaded.ok ? {} : { manifestError: loaded.error }),
+      checks: [],
+      actionable: false,
+      hasPending: false,
+      hasFailed: false,
+      allPassed: false,
+    };
+  }
+  if (!loaded.ok) {
+    return {
+      changedFiles,
+      manifestError: loaded.error,
+      checks: [],
+      actionable: false,
+      hasPending: false,
+      hasFailed: false,
+      allPassed: false,
+    };
+  }
+  const checks: VerificationCheckStatus[] = [];
+  for (const check of loaded.manifest.checks) {
+    const relevant = modifications.filter((edit) => checkMatchesPath(check, edit.path));
+    if (relevant.length === 0) continue;
+    const latestRelevantEditSeq = Math.max(...relevant.map((edit) => edit.seq));
+    const run = latestRunAfter(state, check.id, latestRelevantEditSeq);
+    checks.push({
+      check,
+      latestRelevantEditSeq,
+      ...(run ? { run } : {}),
+      state: run ? (run.ok ? "passed" : "failed") : "pending",
+    });
+  }
+  const hasPending = checks.some((check) => check.state === "pending");
+  const hasFailed = checks.some((check) => check.state === "failed");
+  return {
+    changedFiles,
+    checks,
+    actionable: checks.length > 0,
+    hasPending,
+    hasFailed,
+    allPassed: checks.length > 0 && !hasPending && !hasFailed,
+  };
+}
+
+function code(value: string): string {
+  return `\`${value.replace(/`/g, "'")}\``;
+}
+
+function shortList(values: string[], max = 8): string {
+  const shown = values.slice(0, max).map(code).join(", ");
+  return values.length > max ? `${shown}, +${values.length - max}` : shown;
+}
+
+/** Footer trasparente, costruito dal guard e non dal modello. */
+export function verificationNotice(status: VerificationStatus): string | undefined {
+  if (status.changedFiles.length === 0) return undefined;
+  const lines = [
+    "",
+    "> [jev] verifica osservata (generata dal guard, non dal modello)",
+    `> - Modifiche osservate via edit/write: ${shortList(status.changedFiles)}`,
+  ];
+  if (status.manifestError) {
+    lines.push(`> - Stato: ${status.manifestError}; nessuna verifica configurata è stata attribuita.`);
+    return lines.join("\n");
+  }
+  if (!status.actionable) {
+    lines.push(
+      "> - Stato: nessun check del manifest corrisponde ai file modificati; correttezza non verificata.",
+    );
+    return lines.join("\n");
+  }
+  for (const item of status.checks) {
+    const label = code(item.check.id);
+    if (item.state === "passed") lines.push(`> - ${label}: superato dopo l'ultima modifica pertinente.`);
+    else if (item.state === "failed") {
+      const detail = item.run?.exitCode !== undefined ? ` (exit ${item.run.exitCode})` : "";
+      lines.push(`> - ${label}: fallito${detail}.`);
+    } else {
+      lines.push(`> - ${label}: non eseguito dopo l'ultima modifica pertinente.`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export interface VerificationDecision {
+  action: "publish" | "regenerate" | "hold";
+  notice?: string;
+  feedback?: string;
+  holdText?: string;
+}
+
+export function buildVerificationRepairFeedback(status: VerificationStatus): string {
+  const pending = status.checks.filter((item) => item.state === "pending").map((item) => item.check.id);
+  const failed = status.checks.filter((item) => item.state === "failed").map((item) => item.check.id);
+  return [
+    "Deterministic verification is incomplete or failing after observed edits.",
+    pending.length > 0 ? `Checks not run after relevant edits: ${pending.join(", ")}.` : "",
+    failed.length > 0 ? `Checks failed: ${failed.join(", ")}.` : "",
+    "Use jev_verify with check='recommended' to run only the project-approved pending checks.",
+    "If a check failed, inspect its real tool output, fix the code, then run it again.",
+    "Do not state that code compiles or tests pass unless the observed verification status says so.",
+  ].filter(Boolean).join("\n");
+}
+
+export function buildVerificationHoldText(status: VerificationStatus): string {
+  const failed = status.checks.filter((item) => item.state === "failed").map((item) => item.check.id);
+  const pending = status.checks.filter((item) => item.state === "pending").map((item) => item.check.id);
+  return [
+    "[JEV — OUTPUT NON PUBBLICATO]",
+    "",
+    "Risultato: verification-hold",
+    `Modifiche osservate: ${status.changedFiles.join(", ")}`,
+    failed.length > 0 ? `Check falliti: ${failed.join(", ")}` : "",
+    pending.length > 0 ? `Check mancanti: ${pending.join(", ")}` : "",
+    "",
+    "La risposta non viene pubblicata finché i check configurati non sono aggiornati.",
+  ].filter((line) => line !== "").join("\n");
+}
+
+/**
+ * `hold` è deliberatamente stretto: senza manifest/non pertinente non blocca.
+ * Su check mancanti permette prima una riparazione; su failure concreta trattiene.
+ */
+export function decideVerificationAction(args: {
+  status: VerificationStatus;
+  mode: VerificationMode;
+  repairsUsed: number;
+  maxRepairs: number;
+}): VerificationDecision {
+  const { status, mode, repairsUsed, maxRepairs } = args;
+  const notice = verificationNotice(status);
+  if (status.changedFiles.length === 0 || !status.actionable) {
+    return { action: "publish", ...(notice ? { notice } : {}) };
+  }
+  const needsAction = status.hasPending || status.hasFailed;
+  if (!needsAction) return { action: "publish", ...(notice ? { notice } : {}) };
+  if (mode === "warn") return { action: "publish", ...(notice ? { notice } : {}) };
+  if (mode === "hold" && status.hasFailed) {
+    return { action: "hold", holdText: buildVerificationHoldText(status) };
+  }
+  if (repairsUsed < Math.max(0, maxRepairs)) {
+    return { action: "regenerate", feedback: buildVerificationRepairFeedback(status) };
+  }
+  if (mode === "hold") {
+    return { action: "hold", holdText: buildVerificationHoldText(status) };
+  }
+  return { action: "publish", ...(notice ? { notice } : {}) };
+}
+
+export type VerificationSelection = "recommended" | "all" | string;
+
+export type SelectedChecks =
+  | { ok: true; checks: VerificationCheck[] }
+  | { ok: false; error: string };
+
+/** Seleziona soltanto id dichiarati; il modello non può passare un comando. */
+export function selectVerificationChecks(
+  loaded: LoadedVerificationManifest,
+  status: VerificationStatus,
+  selection: VerificationSelection | undefined,
+  maxCommands: number,
+): SelectedChecks {
+  if (!loaded.ok) return { ok: false, error: loaded.error };
+  const requested = (selection ?? "recommended").trim();
+  let checks: VerificationCheck[];
+  if (requested === "recommended") {
+    if (status.changedFiles.length === 0) {
+      return { ok: false, error: "nessuna modifica edit/write osservata; usa all o un id esplicito" };
+    }
+    checks = status.checks
+      .filter((item) => item.state !== "passed")
+      .map((item) => item.check);
+    if (checks.length === 0) return { ok: false, error: "tutti i check pertinenti risultano già superati" };
+  } else if (requested === "all") {
+    checks = [...loaded.manifest.checks];
+  } else {
+    const found = loaded.manifest.checks.find((check) => check.id === requested);
+    if (!found) return { ok: false, error: `check sconosciuto: ${requested}` };
+    checks = [found];
+  }
+  const numericMax = typeof maxCommands === "number" && Number.isFinite(maxCommands)
+    ? maxCommands
+    : 3;
+  const max = Math.max(1, Math.min(20, Math.floor(numericMax)));
+  if (checks.length > max) {
+    return { ok: false, error: `selezione contiene ${checks.length} check, oltre maxCommands=${max}` };
+  }
+  return { ok: true, checks };
+}
+
+/** Match conservativo per i bash nativi: solo comando identico, whitespace normalizzato. */
+export function manifestCheckForCommand(
+  manifest: VerificationManifest,
+  command: unknown,
+): VerificationCheck | undefined {
+  if (typeof command !== "string") return undefined;
+  const normalized = command.trim().replace(/\s+/g, " ");
+  if (!normalized) return undefined;
+  return manifest.checks.find(
+    (check) => check.command.replace(/\s+/g, " ") === normalized,
+  );
+}