@semacode/cli 1.5.14 → 1.5.16

package/src/docs.ts

@@ -0,0 +1,535 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+const LIMITE_CONTEUDO_DOC = 16_000;
+
+type TipoDocumentoMudanca = "raiz" | "documentacao" | "runbook" | "pacote" | "contrato";
+
+interface DocumentoPlanejado {
+  relativo: string;
+  tipo: TipoDocumentoMudanca;
+  motivo: string;
+  permitirCriacao: boolean;
+}
+
+export interface DocumentoObrigatorioMudanca {
+  caminho: string;
+  relativo: string;
+  tipo: TipoDocumentoMudanca;
+  motivo: string;
+  existe: boolean;
+  criado: boolean;
+  obrigatorio: boolean;
+  conteudo?: string;
+  truncado?: boolean;
+  template?: string;
+}
+
+export interface BloqueioDocumentacaoMudanca {
+  tipo: "documentacao_ausente" | "leitura_obrigatoria_nao_comprovada";
+  severidade: 4 | 5;
+  caminho: string;
+  mensagem: string;
+}
+
+export interface ResultadoDocumentacaoObrigatoria {
+  sucesso: boolean;
+  baseProjeto: string;
+  intencao: string;
+  categorias: string[];
+  arquivosAlvo: string[];
+  leituraObrigatoria: DocumentoObrigatorioMudanca[];
+  docsAusentes: DocumentoObrigatorioMudanca[];
+  docsCriadas: DocumentoObrigatorioMudanca[];
+  bloqueios: BloqueioDocumentacaoMudanca[];
+  instrucoes: string[];
+}
+
+export interface ResultadoVerificacaoDocumentacaoMudanca {
+  sucesso: boolean;
+  baseProjeto: string;
+  intencao: string;
+  categorias: string[];
+  docsLidas: string[];
+  leituraObrigatoria: DocumentoObrigatorioMudanca[];
+  docsNaoLidas: DocumentoObrigatorioMudanca[];
+  docsAusentes: DocumentoObrigatorioMudanca[];
+  diagnosticos: BloqueioDocumentacaoMudanca[];
+  instrucoes: string[];
+}
+
+interface RegraDocumentacao {
+  categoria: string;
+  padroes: RegExp[];
+  docs: DocumentoPlanejado[];
+}
+
+function normalizarTexto(valor: string): string {
+  return valor
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase();
+}
+
+function normalizarRelativo(valor: string): string {
+  return valor.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function tituloDeRelativo(relativo: string): string {
+  const base = path.basename(relativo, path.extname(relativo));
+  return base
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((parte) => `${parte.charAt(0).toUpperCase()}${parte.slice(1)}`)
+    .join(" ");
+}
+
+async function caminhoExiste(caminho: string): Promise<boolean> {
+  try {
+    await stat(caminho);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function caminhoEstaDentro(base: string, alvo: string): boolean {
+  const relativo = path.relative(base, alvo);
+  return relativo === "" || (!relativo.startsWith("..") && !path.isAbsolute(relativo));
+}
+
+async function listarArquivosRecursivo(base: string, limite = 80): Promise<string[]> {
+  const encontrados: string[] = [];
+
+  async function visitar(pasta: string): Promise<void> {
+    if (encontrados.length >= limite || !(await caminhoExiste(pasta))) {
+      return;
+    }
+
+    const entradas = await readdir(pasta, { withFileTypes: true });
+    for (const entrada of entradas.sort((a, b) => a.name.localeCompare(b.name, "pt-BR"))) {
+      if (encontrados.length >= limite) {
+        return;
+      }
+      const caminho = path.join(pasta, entrada.name);
+      if (entrada.isDirectory()) {
+        if (!["node_modules", ".git", ".tmp", "dist"].includes(entrada.name)) {
+          await visitar(caminho);
+        }
+        continue;
+      }
+      encontrados.push(caminho);
+    }
+  }
+
+  await visitar(base);
+  return encontrados;
+}
+
+const REGRAS_DOCUMENTACAO: RegraDocumentacao[] = [
+  {
+    categoria: "deploy",
+    padroes: [/deploy/, /publicar/, /producao/, /release/, /pipeline/, /\bci\b/, /\bcd\b/, /vercel/, /cloudflare/, /docker/],
+    docs: [
+      { relativo: "docs/deploy.md", tipo: "runbook", motivo: "runbook de deploy antes de publicar ou alterar pipeline", permitirCriacao: true },
+      { relativo: "docs/env.md", tipo: "runbook", motivo: "variaveis, secrets e ambientes usados no deploy", permitirCriacao: true },
+      { relativo: "docs/rollback.md", tipo: "runbook", motivo: "plano de rollback obrigatorio antes de deploy", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "api",
+    padroes: [/rota/, /endpoint/, /\bapi\b/, /controller/, /webhook/, /http/],
+    docs: [
+      { relativo: "docs/api.md", tipo: "documentacao", motivo: "contrato operacional de rotas e endpoints", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "auth",
+    padroes: [/auth/, /login/, /permiss/, /autoriz/, /token/, /oauth/, /seguranca/],
+    docs: [
+      { relativo: "docs/auth.md", tipo: "documentacao", motivo: "regras de autenticacao, autorizacao e tokens", permitirCriacao: true },
+      { relativo: "docs/seguranca.md", tipo: "documentacao", motivo: "politicas de seguranca afetadas pela mudanca", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "persistencia",
+    padroes: [/banco/, /database/, /persist/, /migration/, /migracao/, /prisma/, /postgres/, /redis/, /mongodb/],
+    docs: [
+      { relativo: "docs/persistencia-vendor-first.md", tipo: "documentacao", motivo: "regras de persistencia vendor-first", permitirCriacao: false },
+      { relativo: "docs/database.md", tipo: "runbook", motivo: "operacao de banco, migracoes e validacao de dados", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "mcp",
+    padroes: [/\bmcp\b/, /tool/, /ferramenta/, /server/, /stdio/],
+    docs: [
+      { relativo: "pacotes/mcp/README.md", tipo: "pacote", motivo: "documentacao publica do pacote MCP", permitirCriacao: false },
+      { relativo: "docs/integracao-com-ia.md", tipo: "documentacao", motivo: "integracao do Sema com agentes IA", permitirCriacao: false },
+      { relativo: "docs/mcp.md", tipo: "documentacao", motivo: "runbook especifico de ferramentas MCP", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "cli",
+    padroes: [/\bcli\b/, /comando/, /terminal/],
+    docs: [
+      { relativo: "pacotes/cli/README.md", tipo: "pacote", motivo: "documentacao publica da CLI", permitirCriacao: false },
+      { relativo: "docs/cli.md", tipo: "documentacao", motivo: "guia operacional dos comandos da CLI", permitirCriacao: false },
+    ],
+  },
+  {
+    categoria: "extensao",
+    padroes: [/vscode/, /extension/, /extensao/, /editor/, /\blsp\b/, /language server/],
+    docs: [
+      { relativo: "pacotes/editor-vscode/README.md", tipo: "pacote", motivo: "documentacao publica da extensao VS Code", permitirCriacao: false },
+      { relativo: "docs/extensao-vscode.md", tipo: "documentacao", motivo: "runbook da extensao VS Code", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "contrato",
+    padroes: [/contrato/, /\.sema/, /semant/, /\bsema\b/, /drift/, /governanca/],
+    docs: [
+      { relativo: "docs/sintaxe.md", tipo: "documentacao", motivo: "sintaxe e blocos de contrato Sema", permitirCriacao: false },
+      { relativo: "docs/fluxo-pratico-ia-sema.md", tipo: "documentacao", motivo: "fluxo IA-first antes de editar contratos", permitirCriacao: false },
+    ],
+  },
+  {
+    categoria: "frontend",
+    padroes: [/frontend/, /\bui\b/, /react/, /vite/, /next/, /css/, /html/, /pagina/],
+    docs: [
+      { relativo: "docs/frontend.md", tipo: "documentacao", motivo: "decisoes e validacoes de interface", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "testes",
+    padroes: [/teste/, /testar/, /qa/, /validacao/, /regressao/],
+    docs: [
+      { relativo: "docs/testes.md", tipo: "runbook", motivo: "estrategia de testes e regressao", permitirCriacao: true },
+    ],
+  },
+  {
+    categoria: "documentacao",
+    padroes: [/doc/, /readme/, /manual/, /runbook/, /onboarding/],
+    docs: [
+      { relativo: "docs/README.md", tipo: "documentacao", motivo: "indice de documentacao do projeto", permitirCriacao: false },
+      { relativo: "docs/documentacao.md", tipo: "documentacao", motivo: "politica de atualizacao documental", permitirCriacao: true },
+    ],
+  },
+];
+
+function inferirCategorias(intencao: string, arquivosAlvo: string[]): string[] {
+  const texto = normalizarTexto(`${intencao} ${arquivosAlvo.join(" ")}`);
+  const categorias = REGRAS_DOCUMENTACAO
+    .filter((regra) => regra.padroes.some((padrao) => padrao.test(texto)))
+    .map((regra) => regra.categoria);
+  return categorias.length > 0 ? [...new Set(categorias)] : ["mudanca"];
+}
+
+function criarTemplateDoc(doc: DocumentoPlanejado, intencao: string, categorias: string[], arquivosAlvo: string[]): string {
+  const titulo = tituloDeRelativo(doc.relativo);
+  const linhas = [
+    `# ${titulo}`,
+    "",
+    "Documento criado pelo Sema porque uma IA declarou uma intencao que exige leitura operacional antes de agir.",
+    "",
+    "## Intencao",
+    "",
+    intencao || "Descrever a intencao operacional antes de executar a mudanca.",
+    "",
+    "## Escopo",
+    "",
+    arquivosAlvo.length > 0
+      ? arquivosAlvo.map((arquivo) => `- ${arquivo}`).join("\n")
+      : "- Declarar os arquivos, servicos ou contratos afetados.",
+    "",
+    "## Leitura obrigatoria antes de agir",
+    "",
+    "- Ler este documento inteiro.",
+    "- Ler contratos .sema relacionados antes de editar codigo.",
+    "- Ler README, runbooks e docs de pacote envolvidos.",
+    "",
+    "## Procedimento",
+    "",
+    "- Descrever os comandos ou passos seguros.",
+    "- Declarar pre-condicoes, variaveis e dependencias.",
+    "- Registrar como validar sucesso.",
+    "",
+    "## Validacao",
+    "",
+    "- Listar comandos de build, teste, verificacao ou smoke test.",
+    "- Registrar evidencias esperadas.",
+    "",
+    "## Rollback",
+    "",
+    "- Descrever como desfazer a mudanca.",
+    "- Declarar sinais que exigem rollback.",
+    "",
+    "## Atualizacao documental",
+    "",
+    "- Atualizar este arquivo quando o fluxo operacional mudar.",
+    "- Atualizar docs e contratos relacionados na mesma mudanca.",
+    "",
+    `Categorias inferidas: ${categorias.join(", ")}`,
+    "",
+  ];
+
+  return `${linhas.join("\n")}\n`;
+}
+
+function resumoConteudo(conteudo: string): { conteudo: string; truncado: boolean } {
+  if (conteudo.length <= LIMITE_CONTEUDO_DOC) {
+    return { conteudo, truncado: false };
+  }
+
+  return {
+    conteudo: `${conteudo.slice(0, LIMITE_CONTEUDO_DOC)}\n\n[TRUNCADO PELO SEMA: leia o arquivo completo antes de agir.]`,
+    truncado: true,
+  };
+}
+
+async function adicionarDocsRaizExistentes(baseProjeto: string, registrar: (doc: DocumentoPlanejado) => void): Promise<void> {
+  const docsRaiz = [
+    { relativo: "AGENTS.md", tipo: "raiz" as const, motivo: "regras obrigatorias do agente no projeto" },
+    { relativo: "SEMA_INDEX.json", tipo: "raiz" as const, motivo: "indice IA-first do projeto" },
+    { relativo: "README.md", tipo: "raiz" as const, motivo: "visao geral publica do projeto" },
+    { relativo: "docs/README.md", tipo: "documentacao" as const, motivo: "indice de documentacao" },
+  ];
+
+  for (const doc of docsRaiz) {
+    if (await caminhoExiste(path.join(baseProjeto, doc.relativo))) {
+      registrar({ ...doc, permitirCriacao: false });
+    }
+  }
+}
+
+async function adicionarReadmesDeArquivos(
+  baseProjeto: string,
+  arquivosAlvo: string[],
+  registrar: (doc: DocumentoPlanejado) => void,
+): Promise<void> {
+  for (const arquivo of arquivosAlvo) {
+    const absoluto = path.resolve(baseProjeto, arquivo);
+    if (!caminhoEstaDentro(baseProjeto, absoluto)) {
+      continue;
+    }
+
+    let pasta = (await caminhoExiste(absoluto)) && (await stat(absoluto)).isDirectory()
+      ? absoluto
+      : path.dirname(absoluto);
+
+    while (caminhoEstaDentro(baseProjeto, pasta)) {
+      const readme = path.join(pasta, "README.md");
+      if (await caminhoExiste(readme)) {
+        registrar({
+          relativo: normalizarRelativo(path.relative(baseProjeto, readme)),
+          tipo: "pacote",
+          motivo: `README mais proximo de ${normalizarRelativo(arquivo)}`,
+          permitirCriacao: false,
+        });
+        break;
+      }
+
+      const proxima = path.dirname(pasta);
+      if (proxima === pasta) {
+        break;
+      }
+      pasta = proxima;
+    }
+  }
+}
+
+async function adicionarContratosRelacionados(
+  baseProjeto: string,
+  categorias: string[],
+  intencao: string,
+  arquivosAlvo: string[],
+  registrar: (doc: DocumentoPlanejado) => void,
+): Promise<void> {
+  const pastaContratos = path.join(baseProjeto, "contratos");
+  if (!(await caminhoExiste(pastaContratos))) {
+    return;
+  }
+
+  const texto = normalizarTexto(`${intencao} ${arquivosAlvo.join(" ")} ${categorias.join(" ")}`);
+  const arquivos = (await listarArquivosRecursivo(pastaContratos)).filter((arquivo) => arquivo.endsWith(".sema"));
+
+  for (const arquivo of arquivos) {
+    const relativo = normalizarRelativo(path.relative(baseProjeto, arquivo));
+    const nome = normalizarTexto(relativo);
+    const relacionado =
+      texto.split(/\W+/).filter((parte) => parte.length >= 4).some((parte) => nome.includes(parte))
+      || (categorias.some((categoria) => ["mcp", "cli", "documentacao", "contrato"].includes(categoria)) && nome.includes("governanca_ia"));
+
+    if (relacionado) {
+      registrar({
+        relativo,
+        tipo: "contrato",
+        motivo: "contrato Sema relacionado a intencao declarada",
+        permitirCriacao: false,
+      });
+    }
+  }
+}
+
+function criarRegistrador(baseProjeto: string): {
+  docs: DocumentoPlanejado[];
+  registrar: (doc: DocumentoPlanejado) => void;
+} {
+  const docs: DocumentoPlanejado[] = [];
+  const vistos = new Set<string>();
+
+  return {
+    docs,
+    registrar(doc) {
+      const relativo = normalizarRelativo(doc.relativo);
+      const absoluto = path.resolve(baseProjeto, relativo);
+      if (!caminhoEstaDentro(baseProjeto, absoluto) || vistos.has(relativo)) {
+        return;
+      }
+      vistos.add(relativo);
+      docs.push({ ...doc, relativo });
+    },
+  };
+}
+
+export async function resolverDocumentacaoObrigatoria(opcoes: {
+  baseProjeto?: string;
+  intencao: string;
+  arquivosAlvo?: string[];
+  criarAusentes?: boolean;
+}): Promise<ResultadoDocumentacaoObrigatoria> {
+  const baseProjeto = path.resolve(opcoes.baseProjeto ?? process.cwd());
+  const intencao = opcoes.intencao.trim();
+  const arquivosAlvo = [...new Set((opcoes.arquivosAlvo ?? []).map(normalizarRelativo).filter(Boolean))];
+  const categorias = inferirCategorias(intencao, arquivosAlvo);
+  const { docs, registrar } = criarRegistrador(baseProjeto);
+
+  await adicionarDocsRaizExistentes(baseProjeto, registrar);
+
+  for (const regra of REGRAS_DOCUMENTACAO.filter((item) => categorias.includes(item.categoria))) {
+    for (const doc of regra.docs) {
+      registrar(doc);
+    }
+  }
+
+  await adicionarReadmesDeArquivos(baseProjeto, arquivosAlvo, registrar);
+  await adicionarContratosRelacionados(baseProjeto, categorias, intencao, arquivosAlvo, registrar);
+
+  const leituraObrigatoria: DocumentoObrigatorioMudanca[] = [];
+
+  for (const doc of docs) {
+    const caminho = path.resolve(baseProjeto, doc.relativo);
+    let existe = await caminhoExiste(caminho);
+    let criado = false;
+    const template = criarTemplateDoc(doc, intencao, categorias, arquivosAlvo);
+
+    if (!existe && opcoes.criarAusentes && doc.permitirCriacao) {
+      await mkdir(path.dirname(caminho), { recursive: true });
+      await writeFile(caminho, template, "utf8");
+      existe = true;
+      criado = true;
+    }
+
+    const item: DocumentoObrigatorioMudanca = {
+      caminho,
+      relativo: doc.relativo,
+      tipo: doc.tipo,
+      motivo: doc.motivo,
+      existe,
+      criado,
+      obrigatorio: true,
+      template: existe ? undefined : template,
+    };
+
+    if (existe) {
+      const conteudo = resumoConteudo(await readFile(caminho, "utf8"));
+      item.conteudo = conteudo.conteudo;
+      item.truncado = conteudo.truncado;
+    }
+
+    leituraObrigatoria.push(item);
+  }
+
+  const docsAusentes = leituraObrigatoria.filter((doc) => !doc.existe);
+  const docsCriadas = leituraObrigatoria.filter((doc) => doc.criado);
+  const bloqueios = docsAusentes.map((doc): BloqueioDocumentacaoMudanca => ({
+    tipo: "documentacao_ausente",
+    severidade: 4,
+    caminho: doc.relativo,
+    mensagem: `Documento obrigatorio ausente: ${doc.relativo}. Crie ou rode com --criar-ausentes antes de agir.`,
+  }));
+
+  return {
+    sucesso: bloqueios.length === 0,
+    baseProjeto,
+    intencao,
+    categorias,
+    arquivosAlvo,
+    leituraObrigatoria,
+    docsAusentes,
+    docsCriadas,
+    bloqueios,
+    instrucoes: [
+      "A IA deve ler todos os itens de leituraObrigatoria antes de executar a mudanca.",
+      "Se docsAusentes nao estiver vazio, crie ou preencha os documentos antes de editar codigo, contrato, deploy ou configuracao.",
+      "Antes de concluir, rode sema finalizar-mudanca informando as docs lidas.",
+    ],
+  };
+}
+
+function normalizarDocLida(baseProjeto: string, valor: string): string {
+  const semEspaco = valor.trim();
+  if (!semEspaco) {
+    return "";
+  }
+  const absoluto = path.isAbsolute(semEspaco) ? semEspaco : path.resolve(baseProjeto, semEspaco);
+  return normalizarRelativo(path.relative(baseProjeto, absoluto));
+}
+
+export async function verificarDocumentacaoMudanca(opcoes: {
+  baseProjeto?: string;
+  intencao: string;
+  arquivosAlvo?: string[];
+  docsLidas?: string[];
+}): Promise<ResultadoVerificacaoDocumentacaoMudanca> {
+  const baseProjeto = path.resolve(opcoes.baseProjeto ?? process.cwd());
+  const impacto = await resolverDocumentacaoObrigatoria({
+    baseProjeto,
+    intencao: opcoes.intencao,
+    arquivosAlvo: opcoes.arquivosAlvo,
+    criarAusentes: false,
+  });
+
+  const docsLidas = [...new Set((opcoes.docsLidas ?? []).map((doc) => normalizarDocLida(baseProjeto, doc)).filter(Boolean))];
+  const setDocsLidas = new Set(docsLidas);
+  const docsNaoLidas = impacto.leituraObrigatoria.filter((doc) => doc.existe && !setDocsLidas.has(doc.relativo));
+
+  const diagnosticos: BloqueioDocumentacaoMudanca[] = [
+    ...impacto.docsAusentes.map((doc): BloqueioDocumentacaoMudanca => ({
+      tipo: "documentacao_ausente",
+      severidade: 4,
+      caminho: doc.relativo,
+      mensagem: `Documento obrigatorio ausente: ${doc.relativo}.`,
+    })),
+    ...docsNaoLidas.map((doc): BloqueioDocumentacaoMudanca => ({
+      tipo: "leitura_obrigatoria_nao_comprovada",
+      severidade: 4,
+      caminho: doc.relativo,
+      mensagem: `Leitura obrigatoria nao comprovada: ${doc.relativo}.`,
+    })),
+  ];
+
+  return {
+    sucesso: diagnosticos.length === 0,
+    baseProjeto,
+    intencao: opcoes.intencao,
+    categorias: impacto.categorias,
+    docsLidas,
+    leituraObrigatoria: impacto.leituraObrigatoria,
+    docsNaoLidas,
+    docsAusentes: impacto.docsAusentes,
+    diagnosticos,
+    instrucoes: diagnosticos.length === 0
+      ? ["Leitura documental comprovada. Continue com validar, drift e testes conforme a mudanca."]
+      : ["Nao conclua a mudanca enquanto houver diagnosticos de severidade 4+."],
+  };
+}