dd-harness 0.3.0 → 0.5.0

package/dist/brain.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A forma do Brain no contrato `/api/v1`.
+ *
+ * So os tipos: o que o servico devolve, e o que o CLI le. Ate a fase 0 este modulo
+ * tambem transformava o payload em arquivos de disco — o `sync` materializava politica,
+ * briefing e o Brain inteiro no repositorio consumidor. Isso acabou: a politica chega
+ * pelo hook de sessao, e a memoria pela busca, na hora. Nada do dd-harness vive em disco.
+ */
+export type Ancora = {
+    tipo: string;
+    valor: string;
+    sha: string | null;
+};
+export type Memoria = {
+    pasta: string;
+    slug: string;
+    titulo: string;
+    resumo: string;
+    corpo: string;
+    status: "ativa" | "historico";
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    ancoras: Ancora[];
+    revisar_ate: string | null;
+    /** Observacoes de deriva esperando julgamento. Ausente em payload antigo. */
+    deriva_aberta?: number;
+};
+export type Brain = {
+    tenant: {
+        slug: string;
+        nome: string;
+    };
+    projeto: {
+        slug: string;
+        nome: string;
+    };
+    politica?: string | null;
+    briefing?: string | null;
+    pastas: {
+        slug: string;
+        definicao: string;
+    }[];
+    memorias: Memoria[];
+    /**
+     * Memorias que excederam as tentativas de indexacao e nao serao mais tentadas. Ficam
+     * sem embedding — somem da busca semantica — e so este numero denuncia.
+     */
+    travadas_na_fila?: number;
+    /**
+     * Memorias que so esperam o worker rodar. Voltam sozinhas assim que alguem o sobe —
+     * por isso o cliente age em cima deste numero, em vez de so avisar.
+     */
+    esperando_indexacao?: number;
+};

package/dist/brain.js

@@ -0,0 +1,9 @@
+/**
+ * A forma do Brain no contrato `/api/v1`.
+ *
+ * So os tipos: o que o servico devolve, e o que o CLI le. Ate a fase 0 este modulo
+ * tambem transformava o payload em arquivos de disco — o `sync` materializava politica,
+ * briefing e o Brain inteiro no repositorio consumidor. Isso acabou: a politica chega
+ * pelo hook de sessao, e a memoria pela busca, na hora. Nada do dd-harness vive em disco.
+ */
+export {};

package/dist/buscar.d.ts

@@ -5,16 +5,23 @@
  * esta responde "o que ja aprendemos sobre isto?", que e a pergunta de quem ainda esta
  * entendendo o problema e nem sabe qual arquivo abrir.
  *
- * Devolve endereco, nao conteudo: quem quiser o corpo abre o arquivo que o `sync` ja
- * materializou. Assim a busca continua barata e o Brain em disco continua sendo a fonte.
+ * Devolve endereco, nao conteudo: quem quiser o corpo chama `ler`. Assim a busca continua
+ * barata, e quem so queria saber "existe algo sobre isto?" nao paga por N corpos.
  */
 export type Achado = {
     endereco: string;
     titulo: string;
     resumo: string;
 };
-export declare function busca(raiz: string, consulta: string, limite?: number): Promise<{
+export type Resultado = {
     semantica: boolean;
     provedor: string | null;
     achados: Achado[];
-}>;
+    /**
+     * Memorias sem vetor no momento da busca. Maior que zero significa que PODE existir
+     * resposta melhor que nao apareceu — e quem chamou nao teria como saber, porque o
+     * resultado parece completo de qualquer forma.
+     */
+    esperandoIndexacao: number;
+};
+export declare function busca(raiz: string, consulta: string, limite?: number): Promise<Resultado>;

package/dist/buscar.js

@@ -11,5 +11,10 @@ export async function busca(raiz, consulta, limite) {
     if (!resposta.ok)
         await recusa(resposta);
     const lido = (await resposta.json());
-    return { semantica: lido.semantica, provedor: lido.provedor, achados: lido.resultados };
+    return {
+        semantica: lido.semantica,
+        provedor: lido.provedor,
+        achados: lido.resultados,
+        esperandoIndexacao: lido.esperando_indexacao ?? 0,
+    };
 }

package/dist/check.d.ts

@@ -1,5 +1,5 @@
-import { type Tocada } from "./diff.js";
-import type { Brain } from "./materializa.js";
+import { type Reancoragem, type Tocada } from "./diff.js";
+import type { Brain } from "./brain.js";
 /**
  * `dd-harness check` — resolve as âncoras contra a árvore de trabalho.
  *
@@ -24,6 +24,11 @@ export type ResultadoDoCheck = {
     fechadas: number;
     /** Memorias que falam do que o commit mudou. Vazio quando nao ha `--commit`. */
     tocadas: Tocada[];
+    /**
+     * Para onde o git sugere que cada alvo ausente foi. So com `--commit`: sem diff nao ha
+     * rename a cruzar, e a lista de ausentes continua sendo tudo o que se pode dizer.
+     */
+    reancoragens: Reancoragem[];
 };
 export type ResultadoDoStatus = {
     /**

package/dist/check.js

@@ -1,6 +1,6 @@
 import { pede } from "./api.js";
 import { leConfigDoRepo, leToken } from "./config.js";
-import { caminhosDoCommit, memoriasTocadas } from "./diff.js";
+import { caminhosDoCommit, memoriasTocadas, sugereReancoragem, } from "./diff.js";
 import { mede } from "./medir.js";
 /** Separado do IO para poder ser testado sem rede: dado um Brain, o que se mede. */
 export async function medeAsAncoras(raiz, brain) {
@@ -80,11 +80,26 @@ export async function check(raiz, commit) {
     const cabecalhos = { Authorization: `Bearer ${token}` };
     const medicoes = await medeAsAncoras(raiz, brain);
     // O cruzamento com o diff so faz sentido quando ha um commit para olhar.
-    const tocadas = commit
-        ? memoriasTocadas(brain, await caminhosDoCommit(raiz, commit))
-        : [];
+    const mudancas = commit
+        ? await caminhosDoCommit(raiz, commit)
+        : { caminhos: [], renames: [] };
+    const tocadas = commit ? memoriasTocadas(brain, mudancas.caminhos) : [];
+    // Para onde o alvo ausente foi. Sem `--commit` a lista de renames e vazia, entao isto
+    // devolve vazio sozinho — nao ha caso especial a escrever.
+    const reancoragens = sugereReancoragem(medicoes
+        .filter((m) => m.sha === null)
+        .map((m) => ({ pasta: m.pasta, memoria: m.memoria, valor: m.valor })), mudancas.renames);
     if (medicoes.length === 0) {
-        return { medidas: 0, ausentes: [], novas: 0, base: 0, jaAbertas: 0, fechadas: 0, tocadas };
+        return {
+            medidas: 0,
+            ausentes: [],
+            novas: 0,
+            base: 0,
+            jaAbertas: 0,
+            fechadas: 0,
+            tocadas,
+            reancoragens,
+        };
     }
     const envio = await pede(`${config.api}/api/v1/deriva`, {
         method: "POST",
@@ -111,5 +126,6 @@ export async function check(raiz, commit) {
         jaAbertas: julgamento.ja_abertas,
         fechadas: julgamento.fechadas ?? 0,
         tocadas,
+        reancoragens,
     };
 }

package/dist/curar.d.ts

@@ -1,3 +1,41 @@
+/**
+ * Curadoria pelo agente: ler, editar e arquivar.
+ *
+ * `gravar` sabia criar e mais nada. Uma memoria errada ficava errada, porque corrigir
+ * exigia abrir a interface — e o `CLAUDE.md` trata curadoria como obrigacao ("se
+ * encontrar uma memoria obsoleta ou errada, corrija").
+ *
+ * Editar reaproveita o mesmo markdown de `gravar`: um formato so para as duas operacoes.
+ * Ate a fase 0 o ponto de partida era o arquivo que o `sync` materializava; agora e o
+ * `le`, que busca a memoria no servico e devolve nesse mesmo formato.
+ */
+export type MemoriaDoServico = {
+    pasta: string;
+    slug: string;
+    titulo: string;
+    resumo: string;
+    corpo: string;
+    status: string;
+    dano: string;
+    invisibilidade: string;
+    externalidade: string;
+    revisar_ate: string | null;
+    ancoras: {
+        tipo: string;
+        valor: string;
+        sha: string | null;
+    }[];
+};
+/**
+ * A memoria inteira, no markdown que `gravar` e `editar` consomem.
+ *
+ * Sem materializacao, esta e a unica forma de ler o corpo: a busca devolve so endereco,
+ * titulo e resumo, e o disco nao tem mais nada. Tambem e o ponto de partida de qualquer
+ * edicao — corrigir exige ver o que esta la.
+ */
+export declare function le(raiz: string, endereco: string): Promise<string>;
+/** O formato canonico: o mesmo que `interpreta` le, para o ciclo fechar sem conversao. */
+export declare function comoMarkdown(m: MemoriaDoServico): string;
 export declare function edita(raiz: string, caminho: string): Promise<{
     endereco: string;
     ancoras: number;

package/dist/curar.js

@@ -1,37 +1,48 @@
 import { readFile } from "node:fs/promises";
-import { relative } from "node:path";
 import { cabecalhos, credencial, pede, recusa } from "./api.js";
-import { gravaManifesto, hashDe, leManifesto } from "./config.js";
 import { interpreta } from "./gravar.js";
 /**
- * Curadoria pelo agente: editar e arquivar.
+ * A memoria inteira, no markdown que `gravar` e `editar` consomem.
  *
- * `gravar` sabia criar e mais nada. Uma memoria errada ficava errada, porque corrigir
- * exigia abrir a interface — e o `CLAUDE.md` trata curadoria como obrigacao ("se
- * encontrar uma memoria obsoleta ou errada, corrija").
- *
- * Editar reaproveita o mesmo markdown de `gravar`, de proposito: o agente edita o arquivo
- * que o `sync` materializou e manda de volta. Um formato so para as duas operacoes, e o
- * que ele ja sabe ler.
- */
-/**
- * Depois que o servico aceita, o arquivo em disco deixa de ser "edicao nao enviada" — e o
- * manifesto tem que saber, senao o `sync` seguinte para com "editado a mao" e a unica saida
- * que resta e descartar o arquivo. O ciclo materializa-corrige-envia travava justamente
- * aqui, com o servico ja atualizado.
- *
- * Guarda o hash do que foi enviado, nao do que o servico devolveria: o `sync` seguinte
- * reescreve o arquivo na forma canonica quando o ETag mudar.
+ * Sem materializacao, esta e a unica forma de ler o corpo: a busca devolve so endereco,
+ * titulo e resumo, e o disco nao tem mais nada. Tambem e o ponto de partida de qualquer
+ * edicao — corrigir exige ver o que esta la.
  */
-async function marcaComoEnviado(raiz, caminho, conteudo) {
-    const chave = relative(raiz, caminho).split("\\").join("/");
-    const manifesto = await leManifesto(raiz);
-    // Arquivo de fora do repositorio (um rascunho em /tmp, por exemplo) nao esta no
-    // manifesto e nao deve entrar: o manifesto descreve o que o `sync` materializou.
-    if (!manifesto.arquivos[chave])
-        return;
-    manifesto.arquivos[chave] = hashDe(conteudo);
-    await gravaManifesto(raiz, manifesto);
+export async function le(raiz, endereco) {
+    const { config, token } = await credencial(raiz);
+    const url = new URL(`${config.api}/api/v1/memorias/${endereco}`);
+    url.searchParams.set("tenant", config.tenant);
+    url.searchParams.set("projeto", config.projeto);
+    const resposta = await pede(url, { headers: cabecalhos(token) });
+    if (!resposta.ok)
+        await recusa(resposta);
+    return comoMarkdown((await resposta.json()));
+}
+/** O formato canonico: o mesmo que `interpreta` le, para o ciclo fechar sem conversao. */
+export function comoMarkdown(m) {
+    const ancoras = m.ancoras.length
+        ? `\n## Âncoras\n\n${m.ancoras.map((a) => `- \`${a.valor}\``).join("\n")}\n`
+        : "";
+    return [
+        "---",
+        `name: ${m.slug}`,
+        `titulo: ${m.titulo}`,
+        `description: ${m.resumo}`,
+        `pasta: ${m.pasta}`,
+        ...(m.revisar_ate ? [`revisar-ate: ${m.revisar_ate.slice(0, 10)}`] : []),
+        "---",
+        "",
+        m.corpo.trim(),
+        "",
+        "## Os três filtros",
+        "",
+        `**Dano:** ${m.dano}`,
+        "",
+        `**Invisibilidade:** ${m.invisibilidade}`,
+        "",
+        `**Externalidade:** ${m.externalidade}`,
+        ancoras,
+    ].join("\n");
 }
 export async function edita(raiz, caminho) {
     const { config, token } = await credencial(raiz);
@@ -55,7 +66,6 @@ export async function edita(raiz, caminho) {
     });
     if (!resposta.ok)
         await recusa(resposta);
-    await marcaComoEnviado(raiz, caminho, cru);
     return { endereco, ancoras: memoria.ancoras.length };
 }
 export async function arquiva(raiz, endereco, opcoes) {

package/dist/diff.d.ts

@@ -1,4 +1,4 @@
-import type { Brain } from "./materializa.js";
+import type { Brain } from "./brain.js";
 /**
  * Quais memorias falam do que este commit mudou.
  *
@@ -10,14 +10,71 @@ import type { Brain } from "./materializa.js";
  * "voce acabou de mexer no que esta memoria guarda" — util mesmo quando a base ainda
  * nem foi medida, e util mesmo que a memoria continue valendo.
  */
-/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
-export declare function caminhosDoCommit(raiz: string, commit: string): Promise<string[]>;
+/** Um arquivo que saiu de um caminho e chegou noutro, com a confianca que o git deu. */
+export type Rename = {
+    de: string;
+    para: string;
+    similaridade: number;
+};
+export type MudancasDoCommit = {
+    caminhos: string[];
+    renames: Rename[];
+};
+/**
+ * O que um commit mudou: caminhos tocados e renames detectados.
+ *
+ * `-M` liga a deteccao de rename por similaridade, e e o que torna a reancoragem
+ * possivel: sem ela, mover um arquivo aparece como um apagado mais um criado, e a ancora
+ * que apontava para o antigo so tem "alvo ausente" a dizer. Com ela, o git responde para
+ * ONDE o conteudo foi, com um percentual de confianca.
+ *
+ * Vazio quando o git nao responde — nunca quebra: um aviso que nao pode ser dado nao vira
+ * erro que atrapalha o commit.
+ */
+export declare function caminhosDoCommit(raiz: string, commit: string): Promise<MudancasDoCommit>;
+/**
+ * Le a saida de `--name-status`: uma letra de status, TAB, e um ou dois caminhos.
+ *
+ * Rename vem como `R<similaridade>\t<de>\t<para>` (ex: `R094`), e conta como mudanca nos
+ * DOIS caminhos: quem tinha ancora no antigo precisa saber, e quem tem ancora no novo
+ * tambem — o conteudo chegou la.
+ */
+export declare function interpretaNameStatus(stdout: string): MudancasDoCommit;
 export type Tocada = {
     pasta: string;
     memoria: string;
     titulo: string;
     ancora: string;
 };
+/**
+ * Uma ancora cujo alvo sumiu, e para onde o git sugere que ele foi.
+ *
+ * A sugestao e heuristica: o git compara conteudo e da um percentual. Por isso ela e
+ * SUGERIDA e nunca aplicada sozinha — reancorar em silencio moveria a memoria para o
+ * lugar errado sem ninguem ver, que e pior que o alvo ausente que se queria resolver.
+ */
+export type Reancoragem = {
+    pasta: string;
+    memoria: string;
+    ancora: string;
+    sugestao: string;
+    similaridade: number;
+};
+/**
+ * Cruza ancoras ausentes com os renames do commit.
+ *
+ * O caso que isto resolve: uma refatoracao move um arquivo (ou uma pasta inteira) e toda
+ * memoria ancorada ali passa a acusar "alvo ausente" de uma vez. A lista sozinha nao
+ * ajuda — o git sabe para onde o conteudo foi, e e essa a resposta que faltava.
+ *
+ * Ancora de trecho (`arquivo#alvo`) mantem o alvo na sugestao: o arquivo mudou de lugar,
+ * o trecho dentro dele provavelmente nao.
+ */
+export declare function sugereReancoragem(ausentes: {
+    pasta: string;
+    memoria: string;
+    valor: string;
+}[], renames: Rename[]): Reancoragem[];
 /**
  * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
  * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.

package/dist/diff.js

@@ -2,31 +2,89 @@ import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const roda = promisify(execFile);
 /**
- * Quais memorias falam do que este commit mudou.
+ * O que um commit mudou: caminhos tocados e renames detectados.
  *
- * E a peca que devolve a memoria ao code review. Tirar o Brain do repositorio tirou o
- * revisor que o diff dava de graca — no modelo file-based a memoria estava ali, no
- * caminho de quem mexia. Aqui ela volta pelo cruzamento: caminho do diff contra ancora.
+ * `-M` liga a deteccao de rename por similaridade, e e o que torna a reancoragem
+ * possivel: sem ela, mover um arquivo aparece como um apagado mais um criado, e a ancora
+ * que apontava para o antigo so tem "alvo ausente" a dizer. Com ela, o git responde para
+ * ONDE o conteudo foi, com um percentual de confianca.
  *
- * Repare que isto NAO e deriva. Deriva e "o alvo mudou desde a linha de base"; isto e
- * "voce acabou de mexer no que esta memoria guarda" — util mesmo quando a base ainda
- * nem foi medida, e util mesmo que a memoria continue valendo.
+ * Vazio quando o git nao responde — nunca quebra: um aviso que nao pode ser dado nao vira
+ * erro que atrapalha o commit.
  */
-/** Caminhos alterados num commit. Vazio quando o git nao responde — nunca quebra. */
 export async function caminhosDoCommit(raiz, commit) {
     try {
-        const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "--name-only", "-r", commit], { cwd: raiz });
-        return stdout
-            .split(/\r?\n/)
-            .map((l) => l.trim())
-            .filter(Boolean);
+        const { stdout } = await roda("git", ["diff-tree", "--no-commit-id", "-r", "-M", "--name-status", commit], { cwd: raiz });
+        return interpretaNameStatus(stdout);
     }
     catch {
-        // Sem git, commit inexistente, repositorio raso: o cruzamento simplesmente nao
-        // acontece. Um aviso que nao pode ser dado nao vira erro que atrapalha o commit.
-        return [];
+        return { caminhos: [], renames: [] };
     }
 }
+/**
+ * Le a saida de `--name-status`: uma letra de status, TAB, e um ou dois caminhos.
+ *
+ * Rename vem como `R<similaridade>\t<de>\t<para>` (ex: `R094`), e conta como mudanca nos
+ * DOIS caminhos: quem tinha ancora no antigo precisa saber, e quem tem ancora no novo
+ * tambem — o conteudo chegou la.
+ */
+export function interpretaNameStatus(stdout) {
+    const caminhos = [];
+    const renames = [];
+    for (const linha of stdout.split(/\r?\n/)) {
+        if (!linha.trim())
+            continue;
+        const [status, primeiro, segundo] = linha.split("\t");
+        if (!status || !primeiro)
+            continue;
+        if (status.startsWith("R") && segundo) {
+            caminhos.push(primeiro, segundo);
+            renames.push({
+                de: primeiro,
+                para: segundo,
+                // `R094` -> 94. Sem numero (formatos antigos do git), 0 diz "nao sei o quanto".
+                similaridade: Number(status.slice(1)) || 0,
+            });
+            continue;
+        }
+        caminhos.push(primeiro);
+    }
+    return { caminhos, renames };
+}
+/**
+ * Cruza ancoras ausentes com os renames do commit.
+ *
+ * O caso que isto resolve: uma refatoracao move um arquivo (ou uma pasta inteira) e toda
+ * memoria ancorada ali passa a acusar "alvo ausente" de uma vez. A lista sozinha nao
+ * ajuda — o git sabe para onde o conteudo foi, e e essa a resposta que faltava.
+ *
+ * Ancora de trecho (`arquivo#alvo`) mantem o alvo na sugestao: o arquivo mudou de lugar,
+ * o trecho dentro dele provavelmente nao.
+ */
+export function sugereReancoragem(ausentes, renames) {
+    const sugestoes = [];
+    for (const ausente of ausentes) {
+        const corte = ausente.valor.indexOf("#");
+        const arquivo = corte === -1 ? ausente.valor : ausente.valor.slice(0, corte);
+        const trecho = corte === -1 ? "" : ausente.valor.slice(corte);
+        // Casa o arquivo exato ou um diretorio que o continha: mover `src/db/` inteiro
+        // renomeia cada arquivo dentro, e a ancora de diretorio precisa achar isso.
+        const rename = renames.find((r) => r.de === arquivo || arquivo.startsWith(`${r.de}/`));
+        if (!rename)
+            continue;
+        const destino = rename.de === arquivo
+            ? rename.para
+            : `${rename.para}${arquivo.slice(rename.de.length)}`;
+        sugestoes.push({
+            pasta: ausente.pasta,
+            memoria: ausente.memoria,
+            ancora: ausente.valor,
+            sugestao: `${destino}${trecho}`,
+            similaridade: rename.similaridade,
+        });
+    }
+    return sugestoes;
+}
 /**
  * Cruza caminhos com ancoras. A ancora casa quando e o proprio caminho ou quando e um
  * diretorio que o contem — `supabase/migrations` tem que casar com a migration nova.