@codexa/cli 8.6.0 → 8.6.9

package/gates/validator.ts

@@ -1,441 +1,441 @@
-import { getDb } from "../db/connection";
-import { existsSync, readFileSync, statSync } from "fs";
-import { extname } from "path";
-import { validateAgainstStandards, printValidationResult } from "./standards-validator";
-import { extractUtilitiesFromFile } from "../commands/patterns";
-import { findDuplicateUtilities } from "../db/schema";
-
-export interface GateResult {
-  passed: boolean;
-  reason?: string;
-  resolution?: string;
-}
-
-interface GateCheck {
-  check: string;
-  message: string;
-  resolution: string;
-}
-
-const GATES: Record<string, GateCheck[]> = {
-  "check-request": [
-    {
-      check: "plan-exists",
-      message: "Plano nao existe no SQLite",
-      resolution: "Execute: plan start 'descricao'",
-    },
-    {
-      check: "has-tasks",
-      message: "Nenhuma task definida",
-      resolution: "Execute: plan task-add para adicionar tasks",
-    },
-  ],
-  "check-approve": [
-    {
-      check: "phase-is-checking",
-      message: "Fase atual nao e 'checking'",
-      resolution: "Execute: check request primeiro",
-    },
-  ],
-  "task-start": [
-    {
-      check: "spec-approved",
-      message: "Plano nao aprovado",
-      resolution: "Execute: check approve",
-    },
-    {
-      check: "dependencies-done",
-      message: "Dependencias pendentes",
-      resolution: "Complete as tasks dependentes primeiro",
-    },
-  ],
-  "task-done": [
-    {
-      check: "task-is-running",
-      message: "Task nao esta em execucao",
-      resolution: "Execute: task start <id> primeiro",
-    },
-    {
-      check: "checkpoint-filled",
-      message: "Checkpoint obrigatorio",
-      resolution: "Forneca --checkpoint 'resumo do que foi feito'",
-    },
-    {
-      check: "files-exist",
-      message: "Arquivos esperados nao encontrados",
-      resolution: "Crie os arquivos declarados em --files antes de completar a task",
-    },
-    {
-      check: "standards-follow",
-      message: "Codigo viola standards obrigatorios",
-      resolution: "Corrija as violacoes listadas ou use --force para bypass (sera registrado)",
-    },
-    {
-      check: "dry-check",
-      message: "Duplicacao de utilities detectada (DRY)",
-      resolution: "Importe do arquivo existente ou use --force --force-reason para bypass",
-    },
-  ],
-  "review-start": [
-    {
-      check: "all-tasks-done",
-      message: "Tasks pendentes",
-      resolution: "Complete todas as tasks primeiro",
-    },
-  ],
-  "review-approve": [
-    {
-      check: "review-exists",
-      message: "Review nao iniciado",
-      resolution: "Execute: review start primeiro",
-    },
-  ],
-};
-
-function getActiveSpec(): any {
-  const db = getDb();
-  return db.query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1").get();
-}
-
-function executeCheck(check: string, context: any): { passed: boolean; details?: string } {
-  const db = getDb();
-
-  switch (check) {
-    case "plan-exists": {
-      const spec = getActiveSpec();
-      return { passed: spec !== null };
-    }
-
-    case "has-tasks": {
-      const spec = getActiveSpec();
-      if (!spec) return { passed: false };
-      const count = db.query("SELECT COUNT(*) as c FROM tasks WHERE spec_id = ?").get(spec.id) as any;
-      return { passed: count.c > 0 };
-    }
-
-    case "phase-is-checking": {
-      const spec = getActiveSpec();
-      return { passed: spec?.phase === "checking" };
-    }
-
-    case "spec-approved": {
-      const spec = getActiveSpec();
-      return { passed: spec?.approved_at !== null };
-    }
-
-    case "dependencies-done": {
-      if (!context.taskId) return { passed: true };
-      const task = db.query("SELECT * FROM tasks WHERE id = ?").get(context.taskId) as any;
-      if (!task || !task.depends_on) return { passed: true };
-
-      const deps = JSON.parse(task.depends_on) as number[];
-      const pending = deps.filter((depNum) => {
-        // Buscar por number (não id) - depends_on armazena números de tasks
-        const depTask = db.query("SELECT status FROM tasks WHERE spec_id = ? AND number = ?").get(task.spec_id, depNum) as any;
-        return depTask?.status !== "done";
-      });
-
-      return {
-        passed: pending.length === 0,
-        details: pending.join(", "),
-      };
-    }
-
-    case "task-is-running": {
-      if (!context.taskId) return { passed: false };
-      const task = db.query("SELECT status FROM tasks WHERE id = ?").get(context.taskId) as any;
-      return { passed: task?.status === "running" };
-    }
-
-    case "checkpoint-filled": {
-      return {
-        passed: !!context.checkpoint && context.checkpoint.length >= 10,
-      };
-    }
-
-    case "all-tasks-done": {
-      const spec = getActiveSpec();
-      if (!spec) return { passed: false };
-      const pending = db.query(
-        "SELECT number FROM tasks WHERE spec_id = ? AND status != 'done'"
-      ).all(spec.id) as any[];
-      return {
-        passed: pending.length === 0,
-        details: pending.map((t) => `#${t.number}`).join(", "),
-      };
-    }
-
-    case "review-exists": {
-      const spec = getActiveSpec();
-      if (!spec) return { passed: false };
-      const review = db.query("SELECT * FROM review WHERE spec_id = ?").get(spec.id);
-      return { passed: review !== null };
-    }
-
-    case "files-exist": {
-      if (!context.files || context.files.length === 0) return { passed: true };
-
-      // v8.0: Validar não apenas existência, mas conteúdo mínimo
-      const issues: string[] = [];
-
-      for (const file of context.files) {
-        const validation = validateFileContent(file);
-        if (!validation.valid) {
-          issues.push(`${file}: ${validation.reason}`);
-        }
-      }
-
-      return {
-        passed: issues.length === 0,
-        details: issues.join("\n"),
-      };
-    }
-
-    case "standards-follow": {
-      // Se --force foi passado, registrar bypass e passar
-      if (context.force) {
-        logGateBypass(context.taskId, "standards-follow", context.forceReason);
-        return { passed: true };
-      }
-
-      // Se nenhum arquivo, passar
-      if (!context.files || context.files.length === 0) return { passed: true };
-
-      // Obter agente da task
-      const task = db.query("SELECT * FROM tasks WHERE id = ?").get(context.taskId) as any;
-      const agentDomain = task?.agent?.split("-")[0] || "all";
-
-      // Validar arquivos contra standards
-      const result = validateAgainstStandards(context.files, agentDomain);
-
-      // Mostrar resultado se houver violacoes
-      if (!result.passed || result.warnings.length > 0) {
-        printValidationResult(result);
-      }
-
-      return {
-        passed: result.passed,
-        details: result.violations.map(
-          (v) => `[${v.enforcement}] ${v.file}: ${v.rule}${v.detail ? ` (${v.detail})` : ""}`
-        ).join("\n"),
-      };
-    }
-
-    case "dry-check": {
-      // v8.5: Verificar se arquivos criados exportam utilities que ja existem
-      if (context.force) {
-        logGateBypass(context.taskId, "dry-check", context.forceReason);
-        return { passed: true };
-      }
-
-      if (!context.files || context.files.length === 0) return { passed: true };
-
-      const duplicates: string[] = [];
-
-      for (const file of context.files) {
-        if (!existsSync(file)) continue;
-        const utilities = extractUtilitiesFromFile(file);
-
-        for (const util of utilities) {
-          const existing = findDuplicateUtilities(util.name, file);
-          if (existing.length > 0) {
-            duplicates.push(
-              `"${util.name}" (${util.type}) em ${file} -- ja existe em: ${existing.map((e: any) => e.file_path).join(", ")}`
-            );
-          }
-        }
-      }
-
-      if (duplicates.length > 0) {
-        // Apenas function/const/class bloqueiam; interface/type so avisam
-        const blockingDupes = duplicates.filter(d =>
-          d.includes("(function)") || d.includes("(const)") || d.includes("(class)")
-        );
-
-        if (blockingDupes.length > 0) {
-          console.warn("\n[DRY] Possiveis duplicacoes detectadas:\n");
-          for (const d of duplicates) {
-            console.warn(`  - ${d}`);
-          }
-          console.warn("\nImporte do arquivo existente ou use --force --force-reason 'motivo' para bypass.\n");
-          return {
-            passed: false,
-            details: blockingDupes.join("\n"),
-          };
-        } else {
-          // Types/interfaces: aviso nao-bloqueante
-          console.warn("\n[DRY] Aviso: nomes de tipo duplicados (nao bloqueante):");
-          for (const d of duplicates) {
-            console.warn(`  - ${d}`);
-          }
-          return { passed: true };
-        }
-      }
-
-      return { passed: true };
-    }
-
-    default:
-      return { passed: true };
-  }
-}
-
-function logGateBypass(taskId: number, gateName: string, reason?: string): void {
-  const db = getDb();
-  const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
-  if (!task) return;
-
-  const now = new Date().toISOString();
-  db.run(
-    `INSERT INTO gate_bypasses (spec_id, task_id, gate_name, reason, created_at)
-     VALUES (?, ?, ?, ?, ?)`,
-    [task.spec_id, taskId, gateName, reason || "Nao informado", now]
-  );
-
-  console.warn(`\n[!] BYPASS REGISTRADO: Gate '${gateName}' foi ignorado para Task #${task.number}`);
-  if (reason) console.warn(`    Motivo: ${reason}`);
-  console.warn(`    Isso sera auditado no review.\n`);
-}
-
-export function validateGate(command: string, context: any = {}): GateResult {
-  const gates = GATES[command] || [];
-
-  for (const gate of gates) {
-    const result = executeCheck(gate.check, context);
-
-    if (!result.passed) {
-      return {
-        passed: false,
-        reason: result.details
-          ? `${gate.message}: ${result.details}`
-          : gate.message,
-        resolution: gate.resolution,
-      };
-    }
-  }
-
-  return { passed: true };
-}
-
-export function enforceGate(command: string, context: any = {}): void {
-  const result = validateGate(command, context);
-
-  if (!result.passed) {
-    console.error(`\nBLOQUEADO: ${result.reason}`);
-    console.error(`Resolva: ${result.resolution}\n`);
-    process.exit(1);
-  }
-}
-
-// v8.0: Validar conteúdo de arquivos criados (não apenas existência)
-interface FileValidationResult {
-  valid: boolean;
-  reason?: string;
-}
-
-function validateFileContent(filePath: string): FileValidationResult {
-  // 1. Verificar existência
-  if (!existsSync(filePath)) {
-    return { valid: false, reason: "arquivo nao encontrado" };
-  }
-
-  try {
-    // 2. Verificar tamanho (arquivo vazio ou muito pequeno)
-    const stats = statSync(filePath);
-    if (stats.size === 0) {
-      return { valid: false, reason: "arquivo vazio (0 bytes)" };
-    }
-
-    // 3. Ler conteúdo e verificar estrutura mínima
-    const content = readFileSync(filePath, "utf-8");
-    const trimmed = content.trim();
-
-    // Arquivo trivialmente pequeno (< 20 caracteres não é código real)
-    if (trimmed.length < 20) {
-      return { valid: false, reason: `conteudo trivial (${trimmed.length} chars)` };
-    }
-
-    // 4. Validações específicas por extensão
-    const ext = extname(filePath).toLowerCase();
-    const validation = validateByExtension(ext, content);
-    if (!validation.valid) {
-      return validation;
-    }
-
-    return { valid: true };
-  } catch (error: any) {
-    return { valid: false, reason: `erro ao ler: ${error.message}` };
-  }
-}
-
-function validateByExtension(ext: string, content: string): FileValidationResult {
-  const trimmed = content.trim();
-
-  switch (ext) {
-    case ".ts":
-    case ".tsx":
-    case ".js":
-    case ".jsx":
-      // Arquivos JS/TS devem ter pelo menos uma declaração
-      if (!hasCodeStructure(trimmed, ["export", "import", "function", "const", "let", "var", "class", "interface", "type"])) {
-        return { valid: false, reason: "sem declaracoes validas (export, function, class, etc)" };
-      }
-      // TSX/JSX devem ter JSX ou export de componente
-      if ((ext === ".tsx" || ext === ".jsx") && !trimmed.includes("<") && !trimmed.includes("export")) {
-        return { valid: false, reason: "componente sem JSX ou export" };
-      }
-      break;
-
-    case ".css":
-    case ".scss":
-    case ".sass":
-      // CSS deve ter pelo menos um seletor e propriedade
-      if (!trimmed.includes("{") || !trimmed.includes(":")) {
-        return { valid: false, reason: "CSS sem regras validas" };
-      }
-      break;
-
-    case ".json":
-      // JSON deve ser válido
-      try {
-        JSON.parse(content);
-      } catch {
-        return { valid: false, reason: "JSON invalido" };
-      }
-      break;
-
-    case ".sql":
-      // SQL deve ter statements
-      if (!hasCodeStructure(trimmed.toUpperCase(), ["SELECT", "INSERT", "UPDATE", "DELETE", "CREATE", "ALTER", "DROP"])) {
-        return { valid: false, reason: "SQL sem statements validos" };
-      }
-      break;
-
-    case ".py":
-      // Python deve ter definições
-      if (!hasCodeStructure(trimmed, ["def ", "class ", "import ", "from "])) {
-        return { valid: false, reason: "Python sem definicoes (def, class, import)" };
-      }
-      break;
-
-    case ".go":
-      // Go deve ter package
-      if (!trimmed.includes("package ")) {
-        return { valid: false, reason: "Go sem declaracao package" };
-      }
-      break;
-
-    case ".md":
-      // Markdown deve ter conteúdo mínimo
-      if (trimmed.length < 50) {
-        return { valid: false, reason: "Markdown muito curto" };
-      }
-      break;
-  }
-
-  return { valid: true };
-}
-
-function hasCodeStructure(content: string, keywords: string[]): boolean {
-  return keywords.some((keyword) => content.includes(keyword));
-}
+import { getDb } from "../db/connection";
+import { existsSync, readFileSync, statSync } from "fs";
+import { extname } from "path";
+import { validateAgainstStandards, printValidationResult } from "./standards-validator";
+import { extractUtilitiesFromFile } from "../commands/patterns";
+import { findDuplicateUtilities } from "../db/schema";
+
+export interface GateResult {
+  passed: boolean;
+  reason?: string;
+  resolution?: string;
+}
+
+interface GateCheck {
+  check: string;
+  message: string;
+  resolution: string;
+}
+
+const GATES: Record<string, GateCheck[]> = {
+  "check-request": [
+    {
+      check: "plan-exists",
+      message: "Plano nao existe no SQLite",
+      resolution: "Execute: plan start 'descricao'",
+    },
+    {
+      check: "has-tasks",
+      message: "Nenhuma task definida",
+      resolution: "Execute: plan task-add para adicionar tasks",
+    },
+  ],
+  "check-approve": [
+    {
+      check: "phase-is-checking",
+      message: "Fase atual nao e 'checking'",
+      resolution: "Execute: check request primeiro",
+    },
+  ],
+  "task-start": [
+    {
+      check: "spec-approved",
+      message: "Plano nao aprovado",
+      resolution: "Execute: check approve",
+    },
+    {
+      check: "dependencies-done",
+      message: "Dependencias pendentes",
+      resolution: "Complete as tasks dependentes primeiro",
+    },
+  ],
+  "task-done": [
+    {
+      check: "task-is-running",
+      message: "Task nao esta em execucao",
+      resolution: "Execute: task start <id> primeiro",
+    },
+    {
+      check: "checkpoint-filled",
+      message: "Checkpoint obrigatorio",
+      resolution: "Forneca --checkpoint 'resumo do que foi feito'",
+    },
+    {
+      check: "files-exist",
+      message: "Arquivos esperados nao encontrados",
+      resolution: "Crie os arquivos declarados em --files antes de completar a task",
+    },
+    {
+      check: "standards-follow",
+      message: "Codigo viola standards obrigatorios",
+      resolution: "Corrija as violacoes listadas ou use --force para bypass (sera registrado)",
+    },
+    {
+      check: "dry-check",
+      message: "Duplicacao de utilities detectada (DRY)",
+      resolution: "Importe do arquivo existente ou use --force --force-reason para bypass",
+    },
+  ],
+  "review-start": [
+    {
+      check: "all-tasks-done",
+      message: "Tasks pendentes",
+      resolution: "Complete todas as tasks primeiro",
+    },
+  ],
+  "review-approve": [
+    {
+      check: "review-exists",
+      message: "Review nao iniciado",
+      resolution: "Execute: review start primeiro",
+    },
+  ],
+};
+
+function getActiveSpec(): any {
+  const db = getDb();
+  return db.query("SELECT * FROM specs WHERE phase NOT IN ('completed', 'cancelled') ORDER BY created_at DESC LIMIT 1").get();
+}
+
+function executeCheck(check: string, context: any): { passed: boolean; details?: string } {
+  const db = getDb();
+
+  switch (check) {
+    case "plan-exists": {
+      const spec = getActiveSpec();
+      return { passed: spec !== null };
+    }
+
+    case "has-tasks": {
+      const spec = getActiveSpec();
+      if (!spec) return { passed: false };
+      const count = db.query("SELECT COUNT(*) as c FROM tasks WHERE spec_id = ?").get(spec.id) as any;
+      return { passed: count.c > 0 };
+    }
+
+    case "phase-is-checking": {
+      const spec = getActiveSpec();
+      return { passed: spec?.phase === "checking" };
+    }
+
+    case "spec-approved": {
+      const spec = getActiveSpec();
+      return { passed: spec?.approved_at !== null };
+    }
+
+    case "dependencies-done": {
+      if (!context.taskId) return { passed: true };
+      const task = db.query("SELECT * FROM tasks WHERE id = ?").get(context.taskId) as any;
+      if (!task || !task.depends_on) return { passed: true };
+
+      const deps = JSON.parse(task.depends_on) as number[];
+      const pending = deps.filter((depNum) => {
+        // Buscar por number (não id) - depends_on armazena números de tasks
+        const depTask = db.query("SELECT status FROM tasks WHERE spec_id = ? AND number = ?").get(task.spec_id, depNum) as any;
+        return depTask?.status !== "done";
+      });
+
+      return {
+        passed: pending.length === 0,
+        details: pending.join(", "),
+      };
+    }
+
+    case "task-is-running": {
+      if (!context.taskId) return { passed: false };
+      const task = db.query("SELECT status FROM tasks WHERE id = ?").get(context.taskId) as any;
+      return { passed: task?.status === "running" };
+    }
+
+    case "checkpoint-filled": {
+      return {
+        passed: !!context.checkpoint && context.checkpoint.length >= 10,
+      };
+    }
+
+    case "all-tasks-done": {
+      const spec = getActiveSpec();
+      if (!spec) return { passed: false };
+      const pending = db.query(
+        "SELECT number FROM tasks WHERE spec_id = ? AND status != 'done'"
+      ).all(spec.id) as any[];
+      return {
+        passed: pending.length === 0,
+        details: pending.map((t) => `#${t.number}`).join(", "),
+      };
+    }
+
+    case "review-exists": {
+      const spec = getActiveSpec();
+      if (!spec) return { passed: false };
+      const review = db.query("SELECT * FROM review WHERE spec_id = ?").get(spec.id);
+      return { passed: review !== null };
+    }
+
+    case "files-exist": {
+      if (!context.files || context.files.length === 0) return { passed: true };
+
+      // v8.0: Validar não apenas existência, mas conteúdo mínimo
+      const issues: string[] = [];
+
+      for (const file of context.files) {
+        const validation = validateFileContent(file);
+        if (!validation.valid) {
+          issues.push(`${file}: ${validation.reason}`);
+        }
+      }
+
+      return {
+        passed: issues.length === 0,
+        details: issues.join("\n"),
+      };
+    }
+
+    case "standards-follow": {
+      // Se --force foi passado, registrar bypass e passar
+      if (context.force) {
+        logGateBypass(context.taskId, "standards-follow", context.forceReason);
+        return { passed: true };
+      }
+
+      // Se nenhum arquivo, passar
+      if (!context.files || context.files.length === 0) return { passed: true };
+
+      // Obter agente da task
+      const task = db.query("SELECT * FROM tasks WHERE id = ?").get(context.taskId) as any;
+      const agentDomain = task?.agent?.split("-")[0] || "all";
+
+      // Validar arquivos contra standards
+      const result = validateAgainstStandards(context.files, agentDomain);
+
+      // Mostrar resultado se houver violacoes
+      if (!result.passed || result.warnings.length > 0) {
+        printValidationResult(result);
+      }
+
+      return {
+        passed: result.passed,
+        details: result.violations.map(
+          (v) => `[${v.enforcement}] ${v.file}: ${v.rule}${v.detail ? ` (${v.detail})` : ""}`
+        ).join("\n"),
+      };
+    }
+
+    case "dry-check": {
+      // v8.5: Verificar se arquivos criados exportam utilities que ja existem
+      if (context.force) {
+        logGateBypass(context.taskId, "dry-check", context.forceReason);
+        return { passed: true };
+      }
+
+      if (!context.files || context.files.length === 0) return { passed: true };
+
+      const duplicates: string[] = [];
+
+      for (const file of context.files) {
+        if (!existsSync(file)) continue;
+        const utilities = extractUtilitiesFromFile(file);
+
+        for (const util of utilities) {
+          const existing = findDuplicateUtilities(util.name, file);
+          if (existing.length > 0) {
+            duplicates.push(
+              `"${util.name}" (${util.type}) em ${file} -- ja existe em: ${existing.map((e: any) => e.file_path).join(", ")}`
+            );
+          }
+        }
+      }
+
+      if (duplicates.length > 0) {
+        // Apenas function/const/class bloqueiam; interface/type so avisam
+        const blockingDupes = duplicates.filter(d =>
+          d.includes("(function)") || d.includes("(const)") || d.includes("(class)")
+        );
+
+        if (blockingDupes.length > 0) {
+          console.warn("\n[DRY] Possiveis duplicacoes detectadas:\n");
+          for (const d of duplicates) {
+            console.warn(`  - ${d}`);
+          }
+          console.warn("\nImporte do arquivo existente ou use --force --force-reason 'motivo' para bypass.\n");
+          return {
+            passed: false,
+            details: blockingDupes.join("\n"),
+          };
+        } else {
+          // Types/interfaces: aviso nao-bloqueante
+          console.warn("\n[DRY] Aviso: nomes de tipo duplicados (nao bloqueante):");
+          for (const d of duplicates) {
+            console.warn(`  - ${d}`);
+          }
+          return { passed: true };
+        }
+      }
+
+      return { passed: true };
+    }
+
+    default:
+      return { passed: true };
+  }
+}
+
+function logGateBypass(taskId: number, gateName: string, reason?: string): void {
+  const db = getDb();
+  const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
+  if (!task) return;
+
+  const now = new Date().toISOString();
+  db.run(
+    `INSERT INTO gate_bypasses (spec_id, task_id, gate_name, reason, created_at)
+     VALUES (?, ?, ?, ?, ?)`,
+    [task.spec_id, taskId, gateName, reason || "Nao informado", now]
+  );
+
+  console.warn(`\n[!] BYPASS REGISTRADO: Gate '${gateName}' foi ignorado para Task #${task.number}`);
+  if (reason) console.warn(`    Motivo: ${reason}`);
+  console.warn(`    Isso sera auditado no review.\n`);
+}
+
+export function validateGate(command: string, context: any = {}): GateResult {
+  const gates = GATES[command] || [];
+
+  for (const gate of gates) {
+    const result = executeCheck(gate.check, context);
+
+    if (!result.passed) {
+      return {
+        passed: false,
+        reason: result.details
+          ? `${gate.message}: ${result.details}`
+          : gate.message,
+        resolution: gate.resolution,
+      };
+    }
+  }
+
+  return { passed: true };
+}
+
+export function enforceGate(command: string, context: any = {}): void {
+  const result = validateGate(command, context);
+
+  if (!result.passed) {
+    console.error(`\nBLOQUEADO: ${result.reason}`);
+    console.error(`Resolva: ${result.resolution}\n`);
+    process.exit(1);
+  }
+}
+
+// v8.0: Validar conteúdo de arquivos criados (não apenas existência)
+interface FileValidationResult {
+  valid: boolean;
+  reason?: string;
+}
+
+function validateFileContent(filePath: string): FileValidationResult {
+  // 1. Verificar existência
+  if (!existsSync(filePath)) {
+    return { valid: false, reason: "arquivo nao encontrado" };
+  }
+
+  try {
+    // 2. Verificar tamanho (arquivo vazio ou muito pequeno)
+    const stats = statSync(filePath);
+    if (stats.size === 0) {
+      return { valid: false, reason: "arquivo vazio (0 bytes)" };
+    }
+
+    // 3. Ler conteúdo e verificar estrutura mínima
+    const content = readFileSync(filePath, "utf-8");
+    const trimmed = content.trim();
+
+    // Arquivo trivialmente pequeno (< 20 caracteres não é código real)
+    if (trimmed.length < 20) {
+      return { valid: false, reason: `conteudo trivial (${trimmed.length} chars)` };
+    }
+
+    // 4. Validações específicas por extensão
+    const ext = extname(filePath).toLowerCase();
+    const validation = validateByExtension(ext, content);
+    if (!validation.valid) {
+      return validation;
+    }
+
+    return { valid: true };
+  } catch (error: any) {
+    return { valid: false, reason: `erro ao ler: ${error.message}` };
+  }
+}
+
+function validateByExtension(ext: string, content: string): FileValidationResult {
+  const trimmed = content.trim();
+
+  switch (ext) {
+    case ".ts":
+    case ".tsx":
+    case ".js":
+    case ".jsx":
+      // Arquivos JS/TS devem ter pelo menos uma declaração
+      if (!hasCodeStructure(trimmed, ["export", "import", "function", "const", "let", "var", "class", "interface", "type"])) {
+        return { valid: false, reason: "sem declaracoes validas (export, function, class, etc)" };
+      }
+      // TSX/JSX devem ter JSX ou export de componente
+      if ((ext === ".tsx" || ext === ".jsx") && !trimmed.includes("<") && !trimmed.includes("export")) {
+        return { valid: false, reason: "componente sem JSX ou export" };
+      }
+      break;
+
+    case ".css":
+    case ".scss":
+    case ".sass":
+      // CSS deve ter pelo menos um seletor e propriedade
+      if (!trimmed.includes("{") || !trimmed.includes(":")) {
+        return { valid: false, reason: "CSS sem regras validas" };
+      }
+      break;
+
+    case ".json":
+      // JSON deve ser válido
+      try {
+        JSON.parse(content);
+      } catch {
+        return { valid: false, reason: "JSON invalido" };
+      }
+      break;
+
+    case ".sql":
+      // SQL deve ter statements
+      if (!hasCodeStructure(trimmed.toUpperCase(), ["SELECT", "INSERT", "UPDATE", "DELETE", "CREATE", "ALTER", "DROP"])) {
+        return { valid: false, reason: "SQL sem statements validos" };
+      }
+      break;
+
+    case ".py":
+      // Python deve ter definições
+      if (!hasCodeStructure(trimmed, ["def ", "class ", "import ", "from "])) {
+        return { valid: false, reason: "Python sem definicoes (def, class, import)" };
+      }
+      break;
+
+    case ".go":
+      // Go deve ter package
+      if (!trimmed.includes("package ")) {
+        return { valid: false, reason: "Go sem declaracao package" };
+      }
+      break;
+
+    case ".md":
+      // Markdown deve ter conteúdo mínimo
+      if (trimmed.length < 50) {
+        return { valid: false, reason: "Markdown muito curto" };
+      }
+      break;
+  }
+
+  return { valid: true };
+}
+
+function hasCodeStructure(content: string, keywords: string[]): boolean {
+  return keywords.some((keyword) => content.includes(keyword));
+}