brito-cli 0.15.0 → 0.16.1

package/dist/graph/pathfind.js

@@ -0,0 +1,168 @@
+/**
+ * Algoritmos de grafo em memória para o cofre: Dijkstra, A* com landmarks (ALT) e PageRank personalizado.
+ * Custo da aresta = custo da relação + penalidade de hub (log do grau): o caminho preferido não passa por "Início" ou "Deus".
+ */
+class Heap {
+    k = [];
+    v = [];
+    get size() { return this.k.length; }
+    push(key, val) {
+        let i = this.k.length;
+        this.k.push(key);
+        this.v.push(val);
+        while (i > 0) {
+            const p = (i - 1) >> 1;
+            if (this.k[p] <= this.k[i])
+                break;
+            this.swap(i, p);
+            i = p;
+        }
+    }
+    pop() {
+        const top = [this.k[0], this.v[0]];
+        const lk = this.k.pop(), lv = this.v.pop();
+        if (this.k.length) {
+            this.k[0] = lk;
+            this.v[0] = lv;
+            let i = 0;
+            for (;;) {
+                const l = 2 * i + 1, r = l + 1;
+                let m = i;
+                if (l < this.k.length && this.k[l] < this.k[m])
+                    m = l;
+                if (r < this.k.length && this.k[r] < this.k[m])
+                    m = r;
+                if (m === i)
+                    break;
+                this.swap(i, m);
+                i = m;
+            }
+        }
+        return top;
+    }
+    swap(a, b) { [this.k[a], this.k[b]] = [this.k[b], this.k[a]]; [this.v[a], this.v[b]] = [this.v[b], this.v[a]]; }
+}
+export class WGraph {
+    n;
+    adj;
+    deg;
+    constructor(n, edges, hub = 0.25) {
+        this.n = n;
+        this.adj = Array.from({ length: n }, () => []);
+        this.deg = new Array(n).fill(0);
+        for (const [a, b] of edges) {
+            this.deg[a]++;
+            this.deg[b]++;
+        }
+        for (const [a, b, base] of edges) {
+            const w = base + hub * (Math.log2(1 + this.deg[a]) + Math.log2(1 + this.deg[b]));
+            this.adj[a].push({ to: b, w });
+            this.adj[b].push({ to: a, w });
+        }
+    }
+    dijkstra(s) {
+        const dist = new Float64Array(this.n).fill(Infinity);
+        dist[s] = 0;
+        const h = new Heap();
+        h.push(0, s);
+        while (h.size) {
+            const [d, u] = h.pop();
+            if (d > dist[u])
+                continue;
+            for (const e of this.adj[u]) {
+                const nd = d + e.w;
+                if (nd < dist[e.to]) {
+                    dist[e.to] = nd;
+                    h.push(nd, e.to);
+                }
+            }
+        }
+        return dist;
+    }
+    /** Landmarks por ponto mais distante: distâncias pré-calculadas que dão a heurística admissível do A*. */
+    landmarks(k, from = 0) {
+        const out = [];
+        const mind = new Float64Array(this.n).fill(Infinity);
+        let cur = from;
+        for (let i = 0; i < k && cur >= 0; i++) {
+            const dist = this.dijkstra(cur);
+            out.push(dist);
+            let best = -1, bd = -1;
+            for (let v = 0; v < this.n; v++) {
+                mind[v] = Math.min(mind[v], dist[v]);
+                if (mind[v] !== Infinity && mind[v] > bd) {
+                    bd = mind[v];
+                    best = v;
+                }
+            }
+            cur = best;
+        }
+        return out;
+    }
+    astar(s, t, lm) {
+        const hf = (v) => {
+            let m = 0;
+            for (const d of lm) {
+                const a = d[v], b = d[t];
+                if (a !== Infinity && b !== Infinity)
+                    m = Math.max(m, Math.abs(a - b));
+            }
+            return m;
+        };
+        const g = new Float64Array(this.n).fill(Infinity);
+        const prev = new Int32Array(this.n).fill(-1);
+        g[s] = 0;
+        const h = new Heap();
+        h.push(hf(s), s);
+        const done = new Uint8Array(this.n);
+        let settled = 0;
+        while (h.size) {
+            const [, u] = h.pop();
+            if (done[u])
+                continue;
+            done[u] = 1;
+            settled++;
+            if (u === t) {
+                const path = [t];
+                while (path[0] !== s)
+                    path.unshift(prev[path[0]]);
+                return { cost: g[t], settled, path };
+            }
+            for (const e of this.adj[u]) {
+                const ng = g[u] + e.w;
+                if (ng < g[e.to]) {
+                    g[e.to] = ng;
+                    prev[e.to] = u;
+                    h.push(ng + hf(e.to), e.to);
+                }
+            }
+        }
+        return { cost: Infinity, settled, path: [] };
+    }
+    /** PageRank personalizado: a massa parte das sementes e segue as arestas na proporção de 1/custo. */
+    ppr(seeds, alpha = 0.2, iters = 25) {
+        const tot = [...seeds.values()].reduce((a, b) => a + b, 0) || 1;
+        const p0 = new Float64Array(this.n);
+        for (const [k, v] of seeds)
+            p0[k] = v / tot;
+        const wsum = this.adj.map((l) => l.reduce((a, e) => a + 1 / e.w, 0));
+        let p = Float64Array.from(p0);
+        for (let it = 0; it < iters; it++) {
+            const q = new Float64Array(this.n);
+            for (let u = 0; u < this.n; u++) {
+                if (!p[u])
+                    continue;
+                if (!wsum[u]) {
+                    q[u] += p[u];
+                    continue;
+                }
+                for (const e of this.adj[u])
+                    q[e.to] += (1 - alpha) * p[u] * (1 / e.w) / wsum[u];
+            }
+            for (let i = 0; i < this.n; i++)
+                q[i] += alpha * p0[i];
+            p = q;
+        }
+        return p;
+    }
+}

package/dist/graph/sections.js

@@ -6,7 +6,7 @@ import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
-export const SECTIONS_VERSION = "m1";
+export const SECTIONS_VERSION = "m2";
 const MD_RE = /\.(md|markdown)$/i;
 /** Formatos que só viram metadado (Doc sem seções): a fonte de verdade é o .md derivado deles. */
 const META_RE = /\.(pdf|epub|docx)$/i;
@@ -14,7 +14,10 @@ const IGNORE_RE = /(^|\/)(node_modules|dist|build|\.git|\.brito|\.venv|target|ve
 const MAX_MD_BYTES = 5_000_000;
 /** Siglas da NAA (e variantes sem acento); só estas valem como livro, para não confundir "Cap 3" com passagem. */
 const LIVROS = new Set(("Gn Êx Ex Lv Nm Dt Js Jz Rt 1Sm 2Sm 1Rs 2Rs 1Cr 2Cr Ed Ne Et Jó Sl Pv Ec Ct Is Jr Lm Ez Dn Os Jl Am Ob Jn Mq Na Hc Sf Ag Zc Ml " +
-    "Mt Mc Lc Jo At Rm 1Co 2Co Gl Ef Fp Cl 1Ts 2Ts 1Tm 2Tm Tt Fm Hb Tg 1Pe 2Pe 1Jo 2Jo 3Jo Jd Ap").split(" "));
+    "Mt Mc Lc Jo At Rm 1Co 2Co Gl Ef Fp Cl 1Ts 2Ts 1Tm 2Tm Tt Fm Hb Tg 1Pe 2Pe 1Jo 2Jo 3Jo Jd Ap " +
+    // formas longas e variantes usuais em português (as fichas do cofre usam "1Cor", "Hab" etc.)
+    "Gên Gen Êxo Exo Lev Núm Num Deut Jos Juí Jz Rute 1Sam 2Sam 1Re 2Re 1Cr 2Cr Esd Est Jó Sal Prov Ecl Cant Isa Jer Lam Eze Ezq Dan Ose Joe Amó Abd Jon Miq Naum Hab Sof Ageu Zac Mal " +
+    "Mat Mar Luc Joã Atos Rom 1Cor 2Cor Gál Efé Fil Col 1Tes 2Tes 1Tim 2Tim Tito Filem Heb Tia 1Ped 2Ped 1Joã 2Joã 3Joã Jud Apoc").split(" "));
 /** "Rm 9.13; Rm 3.25-26; Ob 15" → ["Rm 9.13","Rm 3.25","Rm 3.26","Ob 15"]. Intervalo vira um item por versículo (máx. 60). */
 export function parsePassagens(txt) {
     const out = [];

package/dist/graph/vaultgraph.js

@@ -0,0 +1,89 @@
+/**
+ * O cofre como grafo em memória (Doc + Passagem; arestas LIGA e CITA) para pathfinding e expansão por PageRank.
+ * O corpo (texto das seções) NÃO fica aqui: só os nós e as arestas. Quem mostra o resultado busca o texto no banco.
+ */
+import crypto from "node:crypto";
+import { WGraph } from "./pathfind.js";
+import { fold } from "./vault.js";
+const cache = new WeakMap();
+export const HUB_DEGREE = 40;
+const pair = (a, b) => (a < b ? `${a}|${b}` : `${b}|${a}`);
+export const label = (v, i) => (i < v.nDocs ? v.paths[i] : `[${v.refs[i - v.nDocs]}]`);
+export const relOf = (v, a, b) => v.rel.get(pair(a, b)) ?? "?";
+export async function vaultGraph(store) {
+    const docs = (await store.run("MATCH (d:Doc) RETURN d.path AS p, d.titulo AS t, d.hash AS h ORDER BY p"));
+    const liga = (await store.run("MATCH (a:Doc)-[r:LIGA]->(b:Doc) RETURN a.path AS a, b.path AS b, r.tipo AS t"));
+    const cita = (await store.run("MATCH (d:Doc)-[:CITA]->(p:Passagem) RETURN d.path AS d, p.ref AS r"));
+    const sig = crypto.createHash("sha1").update(docs.map((d) => d.p + d.h).join("\n")).digest("hex") + `:${liga.length}:${cita.length}`;
+    const old = cache.get(store);
+    if (old && old.sig === sig)
+        return old;
+    const idx = new Map(docs.map((d, i) => [d.p, i]));
+    const refIdx = new Map();
+    for (const c of cita)
+        if (!refIdx.has(c.r))
+            refIdx.set(c.r, docs.length + refIdx.size);
+    const edges = new Map();
+    const rel = new Map();
+    const add = (a, b, cost, t) => {
+        const k = pair(a, b);
+        const o = edges.get(k);
+        if (!o || cost < o[2]) {
+            edges.set(k, [a, b, cost]);
+            rel.set(k, t);
+        }
+    };
+    for (const l of liga) {
+        const a = idx.get(l.a), b = idx.get(l.b);
+        if (a !== undefined && b !== undefined && a !== b)
+            add(a, b, l.t === "menciona" ? 1.6 : 1.0, l.t);
+    }
+    for (const c of cita) {
+        const a = idx.get(c.d);
+        if (a !== undefined)
+            add(a, refIdx.get(c.r), 1.2, "cita");
+    }
+    const g = new WGraph(docs.length + refIdx.size, [...edges.values()]);
+    const first = g.deg.findIndex((d) => d > 0);
+    const v = {
+        g, lm: first < 0 ? [] : g.landmarks(8, first), nDocs: docs.length,
+        paths: docs.map((d) => d.p), titles: docs.map((d) => d.t), refs: [...refIdx.keys()], rel, sig,
+    };
+    cache.set(store, v);
+    return v;
+}
+/** Resolve um nome (caminho, título, nome de arquivo ou passagem "Rm 9.13") para nós. Exato primeiro, depois por inclusão. */
+export function resolveEntity(v, q) {
+    const f = fold(q).trim();
+    if (!f)
+        return [];
+    const names = (i) => [fold(v.paths[i]), fold(v.paths[i].replace(/\.\w+$/, "")), fold(v.paths[i].split("/").pop().replace(/\.\w+$/, "")), fold(v.titles[i] ?? "")];
+    const exact = [];
+    for (let i = 0; i < v.nDocs; i++)
+        if (names(i).includes(f))
+            exact.push(i);
+    v.refs.forEach((r, k) => { if (fold(r) === f)
+        exact.push(v.nDocs + k); });
+    if (exact.length)
+        return exact;
+    const part = [];
+    for (let i = 0; i < v.nDocs; i++)
+        if (names(i).some((n) => n.length >= 3 && n.includes(f)))
+            part.push(i);
+    return part.sort((a, b) => v.paths[a].length - v.paths[b].length).slice(0, 5);
+}
+/** Entidades nomeadas na pergunta: títulos de nota que aparecem inteiros no texto (a mais longa vence a que ela contém). */
+export function entitiesIn(v, query) {
+    const clean = (s) => fold(s).replace(/[^\p{L}\p{N}.]+/gu, " ").trim();
+    const q = ` ${clean(query)} `;
+    const hit = [];
+    for (let i = 0; i < v.nDocs; i++) {
+        const t = clean(v.titles[i] ?? "");
+        if (t.length >= 4 && q.includes(` ${t} `))
+            hit.push(i);
+    }
+    const keep = hit.filter((i) => !hit.some((j) => j !== i && clean(v.titles[j]).includes(clean(v.titles[i])) && clean(v.titles[j]).length > clean(v.titles[i]).length));
+    v.refs.forEach((r, k) => { if (q.includes(` ${fold(r)} `))
+        keep.push(v.nDocs + k); });
+    return keep;
+}

package/dist/graph/vaultquery.js

@@ -0,0 +1,103 @@
+import { vaultSearch } from "./vault.js";
+import { searchSecoes } from "./vault.js";
+import { HUB_DEGREE, entitiesIn, label, relOf, resolveEntity, vaultGraph } from "./vaultgraph.js";
+const isNote = (v, i) => i < v.nDocs && v.paths[i].endsWith(".md") && !/^(Diário de estudo|Modelos)\//.test(v.paths[i]) && !v.paths[i].startsWith("00 ");
+const clip = (s, n = 150) => { const f = s.replace(/\s+/g, " ").trim(); return f.length > n ? f.slice(0, n) + " …" : f; };
+async function intro(store, doc) {
+    const rows = await store.run("MATCH (s:Secao {doc:$d}) RETURN s.texto AS x ORDER BY s.ordem LIMIT 6", { d: doc });
+    for (const r of rows) {
+        // pula seções que são só lista de links ou nota de página: pega a primeira com prosa
+        const prose = String(r.x).split("\n").filter((l) => !/^\s*[-*]?\s*(\[\[[^\]]*\]\]\s*)+$/.test(l) && !/^\s*Páginas\s*=/.test(l)).join(" ").replace(/\[\[([^\]|]*)(?:\|[^\]]*)?\]\]/g, "$1");
+        if (prose.replace(/\s+/g, " ").trim().length >= 40)
+            return clip(prose);
+    }
+    return "";
+}
+/** Por que `r` apareceu: ligação direta com uma semente ou um vizinho em comum com ela. */
+function via(v, r, seeds) {
+    const S = new Set(seeds);
+    for (const e of v.g.adj[r])
+        if (S.has(e.to))
+            return `${label(v, e.to)} (${relOf(v, r, e.to)})`;
+    const nbS = new Map();
+    for (const s of seeds)
+        for (const e of v.g.adj[s])
+            if (!nbS.has(e.to))
+                nbS.set(e.to, s);
+    for (const e of v.g.adj[r])
+        if (nbS.has(e.to) && v.g.deg[e.to] <= HUB_DEGREE)
+            return `${label(v, nbS.get(e.to))} → ${label(v, e.to)} (${relOf(v, r, e.to)})`;
+    return "";
+}
+export async function vaultSearchGraph(root, store, query, opts = {}) {
+    const base = await vaultSearch(root, store, query, opts);
+    const v = await vaultGraph(store);
+    if (!v.nDocs)
+        return base;
+    const ents = entitiesIn(v, query);
+    const hits = await searchSecoes(store, query, { em: opts.em, limit: 10 });
+    const hitIdx = [];
+    for (const h of hits) {
+        const i = v.paths.indexOf(h.doc);
+        if (i >= 0 && !hitIdx.includes(i))
+            hitIdx.push(i);
+    }
+    const join = ents.length >= 2;
+    const seeds = join ? ents.slice(0, 4) : [...new Set([...ents, ...hitIdx.slice(0, 3)])];
+    if (!seeds.length)
+        return base;
+    const w = new Map();
+    if (join)
+        seeds.forEach((s) => w.set(s, 1));
+    else {
+        ents.forEach((e) => w.set(e, 2));
+        hitIdx.slice(0, 3).forEach((d, i) => w.set(d, (w.get(d) ?? 0) + 1 / (1 + i)));
+    }
+    const p = v.g.ppr(w);
+    const skip = new Set([...seeds, ...(join ? [] : hitIdx)]);
+    const cand = [];
+    for (let i = 0; i < v.nDocs; i++)
+        if (p[i] > 0 && !skip.has(i) && isNote(v, i) && v.g.deg[i] <= HUB_DEGREE * 2)
+            cand.push(i);
+    cand.sort((a, b) => p[b] - p[a]);
+    const top = cand.slice(0, opts.limit ?? 5);
+    if (!top.length)
+        return base;
+    const head = join ? `## Notas ligadas a ${seeds.map((s) => label(v, s)).join(" e ")} (junção no grafo)` : "## Relacionadas pelo grafo (não citam as palavras, mas se ligam às notas achadas)";
+    const lines = [head];
+    for (const r of top)
+        lines.push(`- ${v.paths[r]} | ${v.titles[r]}${via(v, r, seeds) ? ` | via ${via(v, r, seeds)}` : ""}`);
+    return join ? `${lines.join("\n")}\n\n${base}` : `${base}\n\n${lines.join("\n")}`;
+}
+/** Caminho de menor custo entre duas notas/passagens, com a relação de cada salto e o início do texto de cada nota. */
+export async function vaultPath(store, de, para) {
+    const v = await vaultGraph(store);
+    const A = resolveEntity(v, de), B = resolveEntity(v, para);
+    if (!A.length)
+        return `não achei nada para "${de}" (use título, caminho ou passagem como "Rm 9.13")`;
+    if (!B.length)
+        return `não achei nada para "${para}" (use título, caminho ou passagem como "Rm 9.13")`;
+    const a = A[0], b = B[0];
+    const notes = [];
+    if (A.length > 1)
+        notes.push(`"${de}" casa com ${A.length} itens; usei ${label(v, a)} (outros: ${A.slice(1, 4).map((x) => label(v, x)).join(", ")})`);
+    if (B.length > 1)
+        notes.push(`"${para}" casa com ${B.length} itens; usei ${label(v, b)} (outros: ${B.slice(1, 4).map((x) => label(v, x)).join(", ")})`);
+    if (a === b)
+        return "origem e destino são o mesmo item";
+    const r = v.g.astar(a, b, v.lm);
+    if (!r.path.length)
+        return `sem caminho entre ${label(v, a)} e ${label(v, b)}`;
+    const out = [`Caminho de menor custo (${r.path.length - 1} saltos, custo ${r.cost.toFixed(2)}, ${r.settled} nós visitados):`];
+    for (let k = 0; k < r.path.length; k++) {
+        const n = r.path[k];
+        const text = n < v.nDocs ? await intro(store, v.paths[n]) : "";
+        out.push(`${k + 1}. ${label(v, n)}${n < v.nDocs && v.titles[n] ? ` — ${v.titles[n]}` : ""}${text ? `\n     ${text}` : ""}`);
+        if (k < r.path.length - 1)
+            out.push(`   ↓ ${relOf(v, n, r.path[k + 1])}`);
+    }
+    const hubs = r.path.slice(1, -1).filter((n) => v.g.deg[n] > HUB_DEGREE);
+    if (hubs.length)
+        out.push(`Aviso: o caminho passa por nó muito ligado (${hubs.map((n) => label(v, n)).join(", ")}); a relação pode ser fraca.`);
+    return [...notes, ...out].join("\n");
+}

package/dist/tools/vault.js

@@ -1,17 +1,30 @@
 import { z } from "zod";
 import { defineTool } from "./registry.js";
-import { vaultSearch } from "../graph/vault.js";
+import { vaultPath, vaultSearchGraph } from "../graph/vaultquery.js";
 defineTool({
     name: "vault_search",
     concurrent: true,
     readsGraph: true,
-    description: "Busca por palavras num cofre de notas Markdown (sem acento nem caixa, todas as palavras): devolve seções de .md com arquivo e linhas (`arq.md:12-30`), os vizinhos do 1º resultado no grafo ([[links]]) e, se houver índice, trechos de livros/aulas com página. USE ANTES de abrir arquivos ou PDFs; depois leia só a faixa de linhas indicada.",
+    description: "Busca por palavras num cofre de notas Markdown (sem acento nem caixa, todas as palavras): devolve seções de .md com arquivo e linhas (`arq.md:12-30`), os vizinhos do 1º resultado no grafo ([[links]]) as notas relacionadas pelo grafo (que não citam as palavras mas se ligam às achadas; com 2 entidades na pergunta, as notas ligadas às duas) e, se houver índice, trechos de livros/aulas com página. USE ANTES de abrir arquivos ou PDFs; depois leia só a faixa de linhas indicada.",
     schema: z.object({
         query: z.string().describe("palavras ou frase"),
         em: z.string().optional().describe("limita a caminhos que contêm este texto (ex.: 'Temas/', 'Frame')"),
         limit: z.number().int().min(1).max(20).optional(),
     }),
     async run({ query, em, limit }, { root, graph }) {
-        return vaultSearch(root, graph, query, { em, limit });
+        return vaultSearchGraph(root, graph, query, { em, limit });
+    },
+});
+defineTool({
+    name: "vault_path",
+    concurrent: true,
+    readsGraph: true,
+    description: "Como duas notas ou passagens se ligam: caminho de menor custo no grafo do cofre (A*), com a relação de cada salto (autor, fonte, temas, menciona, cita) e o início do texto de cada nota. Evita nós muito ligados. USE para 'como X se relaciona com Y?'. Aceita título, caminho ou passagem ('Rm 9.13').",
+    schema: z.object({
+        de: z.string().describe("nota ou passagem de origem"),
+        para: z.string().describe("nota ou passagem de destino"),
+    }),
+    async run({ de, para }, { graph }) {
+        return vaultPath(graph, de, para);
     },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brito-cli",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Coding-agent CLI with a code knowledge graph, memory and reviewable skills / CLI de agente de código com grafo de conhecimento, memória e skills revisáveis",
   "type": "module",
   "bin": {