@orkastery/cli 0.5.1 → 0.5.6

package/dist/intelligence-graph-cli.js

@@ -33,8 +33,12 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CORRECAO_DO_INDICE = exports.USO_DO_GRAFO = exports.AMOSTRA_SCHEMA = exports.STATUS_SCHEMA = void 0;
+exports.CORRECAO_DO_INDICE = exports.USO_DO_GRAFO = exports.AMOSTRA_SCHEMA = exports.REDACAO_DOS_ANALISADORES = exports.STATUS_SCHEMA = void 0;
+exports.descreverVersoes = descreverVersoes;
+exports.correcaoDosAnalisadores = correcaoDosAnalisadores;
+exports.checarAnalisadoresDoGrafo = checarAnalisadoresDoGrafo;
 exports.lerPedido = lerPedido;
+exports.situacaoNaArvore = situacaoNaArvore;
 exports.executarGrafo = executarGrafo;
 /**
  * RM-031 KG3 (D7, D8): `ork grafo`, o CLI do indice e da consulta do grafo de codigo.
@@ -56,14 +60,64 @@ const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const intelligence_graph_contract_1 = require("./intelligence-graph-contract");
 const intelligence_graph_index_1 = require("./intelligence-graph-index");
+const intelligence_graph_parsers_1 = require("./intelligence-graph-parsers");
 const intelligence_graph_query_1 = require("./intelligence-graph-query");
 const intelligence_graph_repo_1 = require("./intelligence-graph-repo");
+const intelligence_graph_contexto_1 = require("./intelligence-graph-contexto");
 exports.STATUS_SCHEMA = 'ork.code-graph-index-status/v0';
+/** As versoes dos analisadores como o `ork grafo status` e o `ork doctor` as mostram. */
+function descreverVersoes(v) {
+    return Object.entries(v).map(([k, x]) => `${k} ${x}`).join(', ');
+}
+/** O prefixo das recusas dos analisadores (`intelligence-graph-parsers.ts`). */
+const RECUSA_DOS_ANALISADORES = 'grafo.parser.indisponivel';
+/**
+ * RM-031 (pacote do npm): o que fazer quando os analisadores nao carregam, dito pelo `ork doctor` e
+ * pelo `ork grafo status`. O micromark e so ESM e carrega por `require`, o que o Node so faz sem flag
+ * a partir de 20.19 e de 22.12. Nos outros casos o pacote falta ou esta fora da instalacao do `ork`,
+ * e a instalacao global do npm traz os analisadores, que sao dependencias do pacote. Mora aqui, fora
+ * de `MODULOS_DO_EXTRATOR`, para a redacao nao entrar na chave do indice; a versao vem de quem chama
+ * (o `index.ts`), porque o CLI do grafo so importa a propria familia (fronteira do KG3).
+ */
+function correcaoDosAnalisadores(motivo, versao, redacao = exports.REDACAO_DOS_ANALISADORES) {
+    if (/ERR_REQUIRE_ESM/.test(motivo))
+        return redacao.soEsm(process.version);
+    // Sem a versao do pacote (`0.0.0-desconhecida` quando o package.json dele nao e achado), o comando
+    // sai sem `@<versao>` e o npm instala a ultima publicada.
+    const fixada = versao && /^\d+\.\d+\.\d+/.test(versao) && !versao.startsWith('0.0.0') ? `@${versao}` : '';
+    return redacao.reinstale(fixada);
+}
+exports.REDACAO_DOS_ANALISADORES = {
+    recusa: (motivo) => `${motivo}: o ork grafo indexar recusa nesta instalacao, e sem o indice as consultas e as tools ork_grafo_* tambem`,
+    soEsm: (versaoDoNode) => `o micromark e so ESM, e este Node (${versaoDoNode}) nao o carrega por require: use Node 20.19, 22.12 ou mais novo, ` +
+        'sem a opcao --no-experimental-require-module (na linha de comando ou no NODE_OPTIONS)',
+    reinstale: (fixada) => `reinstale o ork global, que traz os analisadores como dependencias: npm install -g @orkastery/cli${fixada}` +
+        ' (instalado dentro de um projeto ou pelo npx, o npm deixa os analisadores fora do pacote do ork, e o grafo os recusa)',
+};
+/**
+ * RM-031 (pacote do npm): o check "analisadores do grafo" do `ork doctor`. Carrega o que o
+ * `ork grafo indexar` carrega (`carregarAnalisadores`), entao diz o que o indexar faria, inclusive no
+ * Node sem `require` de ESM. A falta e `warn`, com a correcao: o grafo nao e condicao do despacho de
+ * fase. Fora da familia do grafo so o `index.ts` e o worker do MCP a abrem (fronteira do KG1), entao o
+ * `index.ts` passa este check ao doctor, que nao importa o grafo.
+ */
+function checarAnalisadoresDoGrafo(versao, carregar = intelligence_graph_parsers_1.carregarAnalisadores, versoes = intelligence_graph_parsers_1.versoesDosAnalisadores, redacao = exports.REDACAO_DOS_ANALISADORES) {
+    const nome = 'analisadores do grafo';
+    try {
+        carregar();
+        return { nome, nivel: 'ok', detalhe: descreverVersoes(versoes()) };
+    }
+    catch (e) {
+        const motivo = e.message;
+        return { nome, nivel: 'warn', detalhe: redacao.recusa(motivo), correcao: correcaoDosAnalisadores(motivo, versao, redacao) };
+    }
+}
 /** O mesmo schema da amostra do KG2: as amostras auditadas continuam validas. */
 exports.AMOSTRA_SCHEMA = 'ork.graph-edge-audit-sample/v0';
 exports.USO_DO_GRAFO = [
     'uso: ork grafo indexar [--verificar] [--forcar] [--json]',
     '     ork grafo status [--json]',
+    '     ork grafo contexto <thread> [--json [--teto-bytes N]]',
     '     ork grafo vizinhos <no> [--profundidade N] [--sentido entrada|saida|ambos] [--tipo T,...] [--limite N] [--json [--teto-bytes N]]',
     '     ork grafo chamadores <simbolo> [--profundidade N] [--limite N] [--json [--teto-bytes N]]',
     '     ork grafo importadores <arquivo|simbolo> [--profundidade N] [--limite N] [--json [--teto-bytes N]]',
@@ -83,6 +137,7 @@ const ESTADO_DO_INDICE = Object.freeze({
 const SUBCOMANDOS = Object.freeze({
     indexar: { posicionais: 0, bandeiras: ['verificar', 'forcar', 'json'], valores: [] },
     status: { posicionais: 0, bandeiras: ['json'], valores: [] },
+    contexto: { posicionais: 1, bandeiras: ['json'], valores: ['teto-bytes'] },
     vizinhos: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'sentido', 'tipo', 'limite', 'teto-bytes'] },
     chamadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite', 'teto-bytes'] },
     importadores: { posicionais: 1, bandeiras: ['json'], valores: ['profundidade', 'limite', 'teto-bytes'] },
@@ -238,9 +293,11 @@ function status(ctx, p) {
     const doHead = chave ? estado.indices.find((i) => i.chave === chave) ?? null : null;
     // Sem analisadores nao ha chave: o indice do HEAD fica indisponivel, nunca "ausente" (indexar tambem nao roda).
     const indiceDoHeadEstado = erro ? 'indisponivel' : doHead ? (doHead.problema ? 'com-problema' : 'presente') : 'ausente';
+    // RM-031 (pacote do npm): a recusa dos analisadores vem com o que fazer, a mesma correcao do `ork doctor`.
+    const correcao = erro !== null && erro.startsWith(RECUSA_DOS_ANALISADORES) ? correcaoDosAnalisadores(erro, ctx.versao) : null;
     const r = {
         schema: exports.STATUS_SCHEMA, head: arvore.head, arvore: arvore.motivo === null ? 'limpa' : arvore.motivo, chave_do_head: chave,
-        indice_do_head: indiceDoHeadEstado, analisadores, erro,
+        indice_do_head: indiceDoHeadEstado, analisadores, erro, correcao,
         dir: estado.dir, bytes: estado.bytes, indices: estado.indices, sobras: estado.sobras,
     };
     if (p.bandeiras.has('json')) {
@@ -250,8 +307,11 @@ function status(ctx, p) {
     const linhas = [
         `grafo: HEAD ${arvore.head ? arvore.head.slice(0, 12) : 'sem commit'}, arvore ${r.arvore}`,
         `  indice do HEAD  ${chave ?? 'indisponivel'} ${r.indice_do_head === 'ausente' ? '(ausente: rode ork grafo indexar)'
-            : r.indice_do_head === 'indisponivel' ? '(sem os analisadores nesta instalacao, nem a consulta nem o indexar rodam)' : `(${r.indice_do_head})`}`,
-        `  analisadores    ${erro ?? Object.entries(analisadores).map(([k, v]) => `${k} ${v}`).join(', ')}`,
+            : r.indice_do_head === 'indisponivel'
+                ? (correcao ? '(sem os analisadores nesta instalacao, nem a consulta nem o indexar rodam)' : '(sem a chave do indice: o erro esta na linha de baixo)')
+                : `(${r.indice_do_head})`}`,
+        `  analisadores    ${erro ?? descreverVersoes(analisadores)}`,
+        ...(correcao ? [`  correcao        ${correcao}`] : []),
         `  pasta           ${estado.dir ?? 'ainda nao criada'} (${estado.indices.length} indice(s), ${mb(estado.bytes)})`,
     ];
     for (const i of estado.indices) {
@@ -309,7 +369,10 @@ function semIndiceDoHead(ctx, original) {
     }
     throw original;
 }
-/** O indice do HEAD pronto para consulta, com a concessao local e o cabecalho; `grafo` ja vem filtrado por ela. */
+/**
+ * O indice do HEAD pronto para consulta, com a concessao local e o cabecalho; `grafo` ja vem filtrado por ela.
+ * KG5 fatia 5 (D3): `situacao` so le a arvore quando o cabecalho diz `modificada`; limpa, tudo vale `igual`.
+ */
 function consultavel(ctx) {
     let doHead;
     try {
@@ -328,7 +391,8 @@ function consultavel(ctx) {
         arvore: arvore.motivo === null ? 'limpa' : 'modificada',
         extratores: grafo.snapshot.extractors.map((e) => ({ extractor_id: e.extractor_id, extractor_version: e.extractor_version })),
     };
-    return { g: (0, intelligence_graph_query_1.prepararConsulta)(grafo, concessao), cabecalho, grafo, raiz: arvore.raiz };
+    const situacao = cabecalho.arvore === 'limpa' ? intelligence_graph_query_1.TUDO_IGUAL : situacaoNaArvore(arvore.raiz, grafo.snapshot.source_manifest);
+    return { g: (0, intelligence_graph_query_1.prepararConsulta)(grafo, concessao), cabecalho, grafo, raiz: arvore.raiz, situacao };
 }
 function responder(ctx, p, r) {
     ctx.escrever(p.bandeiras.has('json') ? (0, intelligence_graph_query_1.jsonDaResposta)(r) : (0, intelligence_graph_query_1.textoDaResposta)(r));
@@ -373,21 +437,48 @@ function consultar(ctx, p) {
     // As opcoes sao conferidas antes de carregar o indice: erro de uso nao custa a leitura do grafo.
     const [a, b] = p.posicionais;
     const profundidade = inteiro(p, 'profundidade'), limite = inteiro(p, 'limite'), s = sentido(p), t = tipos(p), teto = tetoDeBytes(p);
-    const { g, cabecalho } = consultavel(ctx);
+    const { g, cabecalho, situacao } = consultavel(ctx);
+    // A busca binaria do teto pergunta de novo com outro limite; a situacao guarda o que ja leu da arvore.
     const perguntar = (lim) => {
         if (p.sub === 'vizinhos')
-            return (0, intelligence_graph_query_1.vizinhos)(g, cabecalho, a, { profundidade, limite: lim, sentido: s, tipos: t });
+            return (0, intelligence_graph_query_1.vizinhos)(g, cabecalho, a, { profundidade, limite: lim, sentido: s, tipos: t }, situacao);
         if (p.sub === 'chamadores')
-            return (0, intelligence_graph_query_1.chamadores)(g, cabecalho, a, { profundidade, limite: lim });
+            return (0, intelligence_graph_query_1.chamadores)(g, cabecalho, a, { profundidade, limite: lim }, situacao);
         if (p.sub === 'importadores')
-            return (0, intelligence_graph_query_1.importadores)(g, cabecalho, a, { profundidade, limite: lim });
-        return (0, intelligence_graph_query_1.caminho)(g, cabecalho, a, b, { sentido: s, tipos: t });
+            return (0, intelligence_graph_query_1.importadores)(g, cabecalho, a, { profundidade, limite: lim }, situacao);
+        return (0, intelligence_graph_query_1.caminho)(g, cabecalho, a, b, { sentido: s, tipos: t }, situacao);
     };
     if (teto === undefined)
         return responder(ctx, p, perguntar(limite));
     ctx.escrever(respostaComTeto(perguntar, limite, teto));
     return 0;
 }
+function contexto(ctx, p) {
+    const teto = tetoDeBytes(p);
+    if (teto !== undefined && (teto < 4096 || teto > 65536))
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-invalido', 'teto deve ser inteiro de 4096 a 65536 bytes');
+    if (!ctx.contextoDaThread)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.indisponivel', 'borda sem leitor da thread');
+    const lido = ctx.contextoDaThread(p.posicionais[0]);
+    const { grafo, cabecalho, situacao } = consultavel({ ...ctx, raiz: lido.raiz });
+    if (lido.head !== cabecalho.revision)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.revisao-mudou', 'HEAD mudou durante a leitura; repita a consulta');
+    const json = (0, intelligence_graph_contexto_1.pacoteDeContexto)(grafo, cabecalho, lido.entrada, teto, situacao);
+    if (p.bandeiras.has('json'))
+        ctx.escrever(json);
+    else {
+        const r = JSON.parse(json);
+        // KG5 fatia 5 (D9): o resumo conta as ligacoes cuja fonte mudou na arvore, como o JSON marca.
+        const mudadas = r.arestas.filter((a) => a.arvore === 'modificada').length;
+        ctx.escrever([`Contexto ${r.thread} @ ${r.indice.revision}`,
+            `  ${r.sementes.length}/${r.total_sementes} sementes, ${r.arestas.length}/${r.total_ligacoes} ligacoes agregadas; ${r.medida.pacote_bytes} bytes JSON`,
+            `  tamanho dos arquivos no pacote (nao descoberta): ${r.medida.leitura_crua_bytes} bytes (revisao indexada); tokens: unavailable`,
+            `  diff: ${r.fontes.diff}`,
+            ...(mudadas ? [`  ligacoes com fonte modificada na arvore: ${mudadas}`] : []),
+            `  truncado: ${r.truncado}; arvore: ${r.indice.arvore}; use --json para nos e evidencias`, json].join('\n'));
+    }
+    return 0;
+}
 const sha256 = (b) => (0, node_crypto_1.createHash)('sha256').update(b).digest('hex');
 /**
  * Bytes da arvore, conferidos arquivo a arquivo contra o manifesto do indice: o trecho da amostra e
@@ -427,6 +518,66 @@ function leitorDaArvore(raiz, grafo) {
         return bytes;
     };
 }
+/**
+ * KG5 fatia 5 (D3, D6): a situacao de cada fonte do indice na arvore, pelos bytes. So caminho do manifesto;
+ * sem seguir link, nem no ultimo nome nem numa pasta do caminho: o caminho real tem de ser o proprio caminho
+ * indexado dentro da raiz (CHECK rodada 1, A1). So arquivo regular; tamanho diferente do indexado e
+ * `modificada` sem ler, e o sha256 dos bytes decide o resto, lidos ate o tamanho indexado mais um. O arquivo
+ * aberto tem de ser o mesmo do `lstat` (dispositivo e inode, CHECK rodada 1, S3): troca entre a conferencia e
+ * a abertura vira `ausente`; duas trocas no intervalo ainda passam, e revelariam so se os bytes sao os
+ * indexados. Qualquer falha e `ausente`: nao ha arquivo regular legivel no caminho. Cada caminho e lido uma
+ * vez, sob demanda, e nada e escrito.
+ */
+function situacaoNaArvore(raiz, manifesto) {
+    const porCaminho = new Map(manifesto.map((m) => [m.path, m]));
+    const vistas = new Map();
+    let raizReal = null;
+    const ler = (p) => {
+        const m = porCaminho.get(p);
+        if (!m)
+            return 'ausente';
+        const absoluto = path.join(raiz, p);
+        try {
+            raizReal ??= fs.realpathSync(raiz);
+            const st = fs.lstatSync(absoluto, { throwIfNoEntry: false });
+            if (!st || !st.isFile())
+                return 'ausente';
+            // CHECK rodada 2 (R2-S1): caminho de manifesto adulterado com `..` coincidiria com o real fora da raiz.
+            const real = fs.realpathSync(absoluto);
+            if (real !== path.join(raizReal, p) || !real.startsWith(raizReal + path.sep))
+                return 'ausente';
+            if (st.size !== m.size_bytes)
+                return 'modificada';
+            const fd = fs.openSync(absoluto, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+            try {
+                const aberto = fs.fstatSync(fd);
+                if (!aberto.isFile() || aberto.dev !== st.dev || aberto.ino !== st.ino)
+                    return 'ausente';
+                if (aberto.size !== m.size_bytes)
+                    return 'modificada';
+                const bytes = Buffer.alloc(m.size_bytes + 1);
+                let lidos = 0;
+                for (let n = 1; n > 0 && lidos < bytes.length; lidos += n)
+                    n = fs.readSync(fd, bytes, lidos, bytes.length - lidos, null);
+                return lidos === m.size_bytes && sha256(bytes.subarray(0, lidos)) === m.source_hash ? 'igual' : 'modificada';
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+        catch {
+            return 'ausente';
+        }
+    };
+    return (p) => {
+        const vista = vistas.get(p);
+        if (vista !== undefined)
+            return vista;
+        const s = ler(p);
+        vistas.set(p, s);
+        return s;
+    };
+}
 const localizadorDe = (g) => new Map(g.nodes.map((n) => [n.node_id, { kind: n.kind, path: n.locator.path, fragment: n.locator.fragment }]));
 const rotulo = (l) => `${l.kind}:${l.path}${l.fragment === null ? '' : `#${l.fragment}`}`;
 const chaveDaAresta = (kind, de, para) => `${kind} ${rotulo(de)} -> ${rotulo(para)}`;
@@ -541,12 +692,12 @@ function limpar(ctx, p) {
     return 0;
 }
 /** KG5 (D4, D5): com `--teto-bytes` o erro tambem sai compacto; recusa de indice traz o estado e a correcao. */
-const erroEmJson = (ctx, e, compacto) => {
+const erroEmJson = (ctx, e, compacto, schema = intelligence_graph_query_1.CONSULTA_SCHEMA) => {
     const [codigo, ...detalhe] = String(e.message).split('\n')[0].split(': ');
     const doIndice = Object.prototype.hasOwnProperty.call(ESTADO_DO_INDICE, codigo)
         ? { estado_do_indice: ESTADO_DO_INDICE[codigo], correcao: exports.CORRECAO_DO_INDICE } : {};
     const r = {
-        schema: intelligence_graph_query_1.CONSULTA_SCHEMA,
+        schema,
         erro: { codigo, detalhe: detalhe.join(': ') || null, candidatos: e instanceof intelligence_graph_query_1.ErroDeConsulta ? e.candidatos : [], ...doIndice },
     };
     ctx.escrever(compacto ? JSON.stringify(r) : JSON.stringify(r, null, 2));
@@ -554,7 +705,8 @@ const erroEmJson = (ctx, e, compacto) => {
 };
 /** `ork grafo <subcomando> ...`: devolve o codigo de saida; sem `--json`, o erro de uso ou tipado e lancado. */
 function executarGrafo(argv, ctx) {
-    const compacto = argv.some((a) => a === '--teto-bytes' || a.startsWith('--teto-bytes='));
+    const schema = argv[0] === 'contexto' ? intelligence_graph_contexto_1.CONTEXTO_SCHEMA : intelligence_graph_query_1.CONSULTA_SCHEMA;
+    const compacto = argv[0] === 'contexto' || argv.some((a) => a === '--teto-bytes' || a.startsWith('--teto-bytes='));
     let p;
     try {
         p = lerPedido(argv);
@@ -562,7 +714,7 @@ function executarGrafo(argv, ctx) {
     catch (e) {
         // Com `--json` no argv, tambem o erro de uso sai como objeto, como os demais.
         if (argv.includes('--json'))
-            return erroEmJson(ctx, e, compacto);
+            return erroEmJson(ctx, e, compacto, schema);
         throw e;
     }
     try {
@@ -574,11 +726,13 @@ function executarGrafo(argv, ctx) {
             return amostra(ctx, p);
         if (p.sub === 'limpar')
             return limpar(ctx, p);
+        if (p.sub === 'contexto')
+            return contexto(ctx, p);
         return consultar(ctx, p);
     }
     catch (e) {
         if (!p.bandeiras.has('json'))
             throw e;
-        return erroEmJson(ctx, e, compacto);
+        return erroEmJson(ctx, e, compacto, schema);
     }
 }

package/dist/intelligence-graph-contexto.js

@@ -0,0 +1,254 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTEXTO_FORA_DO_INDICE = exports.CONTEXTO_POR_ALVO = exports.CONTEXTO_TETO_PADRAO = exports.CONTEXTO_SCHEMA = void 0;
+exports.sementesDaThread = sementesDaThread;
+exports.pacoteDeContexto = pacoteDeContexto;
+/**
+ * KG5: composicao pura do contexto da thread. Sem E/S, relogio ou inferencia.
+ *
+ * KG5 fatia 5 (D5): quem chama passa a situacao das fontes na arvore (o CLI le os bytes); o grupo cuja
+ * origem ou alvo nao confere ganha `arvore: "modificada"`, e o que confere sai sem o campo. Sem a situacao,
+ * ou com a arvore limpa, o pacote e o de antes, byte a byte.
+ */
+const node_crypto_1 = require("node:crypto");
+const intelligence_graph_contract_1 = require("./intelligence-graph-contract");
+const intelligence_graph_query_1 = require("./intelligence-graph-query");
+exports.CONTEXTO_SCHEMA = 'ork.thread-graph-context/v2';
+exports.CONTEXTO_TETO_PADRAO = 32768;
+exports.CONTEXTO_POR_ALVO = 8;
+exports.CONTEXTO_FORA_DO_INDICE = 3;
+const LIMITE_REJEICOES_SEGUNDO_SALTO = 8;
+const hash = (texto) => (0, node_crypto_1.createHash)('sha256').update(texto).digest('hex');
+/** Caminho relativo do repositorio, nunca caminho de maquina, URL ou estado privado. */
+function caminhoPublico(bruto) {
+    const p = bruto.replace(/^\.\//, '');
+    if (!p || p.startsWith('/') || p.startsWith('~') || /[:\\\u0000-\u001f\u007f]/.test(p) || p.length > 500
+        || p.split('/').some((x) => !x || x === '..' || x === '.' || x === '.git' || x === '.orkastery'))
+        return null;
+    return p;
+}
+/** GOAL/PLAN citam caminhos relativos a raiz em codigo, links ou texto; nao executam instrucoes. */
+function caminhosCitados(texto, diretorios) {
+    const r = [];
+    const semCitacoes = texto.replace(/`([^`\n]+)`|\]\(([^)\n]+)\)/g, (_m, codigo, link) => {
+        const v = codigo ?? link ?? '';
+        if (!/^(?:[a-z]+:|\/)/i.test(v) && (v.includes('/') || /\.[a-z0-9]+(?:#.*|:\d+(?::\d+)?)?$/i.test(v)
+            || /^(?:Dockerfile|Makefile|LICENSE)$/.test(v)))
+            r.push(v.replace(/#.*$/, '').replace(/:\d+(?::\d+)?$/, ''));
+        return ' ';
+    });
+    // Em prosa, exigir diretorio ou extensao de fonte conhecida evita versoes, Node.js e dominios.
+    for (const m of semCitacoes.matchAll(/(?:^|[\s(\["'])((?:[\p{L}\p{N}_@.-]+\/)+[\p{L}\p{N}_@.-]+|[\p{L}\p{N}_@-]+\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|json|md|markdown|yaml|yml|toml|py|rs|go|c|h|css|html))(?=\.(?:\s|$)|[:#\s),;\]"']|$)/gu))
+        if (!/^Node\.js\.?$/i.test(m[1]))
+            r.push(m[1].replace(/\.$/, ''));
+    return r.filter((bruto) => {
+        const p = caminhoPublico(bruto);
+        return p !== null && !/^Node\.js$/i.test(p) && (/\.(?:ts|tsx|js|jsx|mjs|cjs|mts|cts|json|md|markdown|yaml|yml|toml|py|rs|go|c|h|css|html)$/i.test(p)
+            || /(?:^|\/)(?:Dockerfile|Makefile|LICENSE)$/.test(p)
+            || (p.includes('/') && diretorios.has(p.split('/')[0])));
+    });
+}
+function sementesDaThread(entrada, caminhosDoRepositorio = []) {
+    const diretorios = new Set(caminhosDoRepositorio.filter((p) => p.includes('/')).map((p) => p.split('/')[0]));
+    const mapa = new Map();
+    const adicionar = (bruto, origem) => {
+        const p = caminhoPublico(bruto);
+        if (!p)
+            return;
+        const origens = mapa.get(p) ?? new Set();
+        origens.add(origem);
+        mapa.set(p, origens);
+    };
+    if (entrada.diffEstado !== 'ignorado-sem-worktree')
+        for (const p of entrada.diff)
+            adicionar(p, 'diff');
+    for (const tipo of ['goal', 'plan'])
+        for (const p of caminhosCitados(entrada[tipo] ?? '', diretorios))
+            adicionar(p, tipo);
+    for (const c of entrada.claims)
+        adicionar(c.arquivo, `claim:${c.id}`);
+    return [...mapa].sort(([a], [b]) => (0, intelligence_graph_contract_1.compararUtf8)(a, b))
+        .map(([arquivo, origens]) => ({ arquivo, origens: [...origens].sort(intelligence_graph_contract_1.compararUtf8) }));
+}
+const compararTipo = (a, b) => Number(a === 'cites') - Number(b === 'cites') || (0, intelligence_graph_contract_1.compararUtf8)(a, b);
+/** O grafo recebido ja deve estar filtrado pela concessao de quem consulta. */
+function pacoteDeContexto(grafo, indice, entrada, tetoBytes = exports.CONTEXTO_TETO_PADRAO, situacao = intelligence_graph_query_1.TUDO_IGUAL) {
+    if (!Number.isInteger(tetoBytes) || tetoBytes < 4096 || tetoBytes > 65536)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-invalido', 'teto deve ser inteiro de 4096 a 65536 bytes');
+    const porId = new Map(grafo.nodes.map((n) => [n.node_id, n]));
+    const arquivos = new Set(grafo.nodes.filter((n) => n.kind === 'file').map((n) => n.locator.path));
+    const sementes = sementesDaThread(entrada, [...arquivos]).map((s) => ({ ...s, estado: arquivos.has(s.arquivo) ? 'indexado' : 'fora-do-indice' }));
+    const indexadas = sementes.filter((s) => s.estado === 'indexado'), ausentes = sementes.filter((s) => s.estado !== 'indexado');
+    const alvos = new Set(indexadas.map((s) => s.arquivo));
+    const diff = entrada.diffEstado === 'ignorado-sem-worktree' ? [] : [...new Set(entrada.diff)].sort(intelligence_graph_contract_1.compararUtf8);
+    // Distancia em arquivos, em ambos os sentidos, sem depender da ordem das arestas.
+    const adj = new Map();
+    for (const a of grafo.edges) {
+        const de = porId.get(a.from).locator.path, para = porId.get(a.to).locator.path;
+        if (de === para)
+            continue;
+        if (!adj.has(de))
+            adj.set(de, new Set());
+        if (!adj.has(para))
+            adj.set(para, new Set());
+        adj.get(de).add(para);
+        adj.get(para).add(de);
+    }
+    const vizinhos = new Set([...alvos].flatMap((p) => [...(adj.get(p) ?? [])]));
+    const dist = new Map(diff.filter((p) => arquivos.has(p)).map((p) => [p, 0]));
+    const fila = [...dist.keys()];
+    for (let i = 0; i < fila.length; i++)
+        for (const p of adj.get(fila[i]) ?? []) {
+            if (!dist.has(p)) {
+                dist.set(p, dist.get(fila[i]) + 1);
+                fila.push(p);
+            }
+        }
+    const extratores = [...indice.extratores].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)((0, intelligence_graph_contract_1.canonico)(a), (0, intelligence_graph_contract_1.canonico)(b)));
+    const extratorIds = new Map(extratores.map((e, i) => [(0, intelligence_graph_contract_1.canonico)(e), i]));
+    const grupos = new Map();
+    let totalArestas = 0, arestasDiretas = 0, estruturais = 0, evidenciasAuxiliares = 0, auxiliaresDiretas = 0;
+    for (const a of grafo.edges) {
+        const de = porId.get(a.from), para = porId.get(a.to);
+        const direto = alvos.has(de.locator.path) || alvos.has(para.locator.path);
+        if (!direto && (de.locator.path === para.locator.path
+            || (!vizinhos.has(de.locator.path) && !vizinhos.has(para.locator.path))))
+            continue;
+        totalArestas++;
+        if (direto)
+            arestasDiretas++;
+        if ((a.kind === 'declares' || a.kind === 'contains') && de.locator.path === para.locator.path && alvos.has(de.locator.path)) {
+            estruturais++;
+            continue;
+        }
+        const proprias = a.evidence.filter((e) => e.path === de.locator.path);
+        evidenciasAuxiliares += a.evidence.length - proprias.length;
+        if (direto)
+            auxiliaresDiretas += a.evidence.length - proprias.length;
+        // Sem evidencia no arquivo de origem, a aresta fica em omitidos.arestas.
+        if (!proprias.length)
+            continue;
+        const origem = `file ${de.locator.path}`, destino = (0, intelligence_graph_query_1.rotuloDoNo)(para);
+        const chave = (0, intelligence_graph_contract_1.canonico)([a.kind, destino, de.locator.path]);
+        const grupo = grupos.get(chave) ?? { kind: a.kind, origem, destino, alvo: para.node_id, quantidade: 0,
+            evidencias: new Map(), entreArquivos: de.locator.path !== para.locator.path,
+            salto: direto ? 1 : 2,
+            distancia: Math.min(dist.get(de.locator.path) ?? Infinity, dist.get(para.locator.path) ?? Infinity) };
+        grupo.quantidade++;
+        for (const e of proprias) {
+            const x = extratorIds.get((0, intelligence_graph_contract_1.canonico)({ extractor_id: e.extractor_id, extractor_version: e.extractor_version }));
+            if (x === undefined)
+                throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.extrator-ausente', 'extrator da evidencia ausente no cabecalho');
+            const s = e.span;
+            const tupla = [x, e.extraction_method,
+                s.type === 'text' ? [s.line_start, s.line_end] : ['pdf', s.page, s.extracted_text_hash], [s.byte_start, s.byte_end]];
+            grupo.evidencias.set((0, intelligence_graph_contract_1.canonico)(tupla), tupla);
+        }
+        grupos.set(chave, grupo);
+    }
+    // Entre arquivos > perto do diff > tipo > rotulos; empates independem da ordem do indice.
+    const ordenados = [...grupos.values()].sort((a, b) => a.salto - b.salto || Number(b.entreArquivos) - Number(a.entreArquivos)
+        || (a.distancia === b.distancia ? 0 : a.distancia < b.distancia ? -1 : 1)
+        || compararTipo(a.kind, b.kind) || (0, intelligence_graph_contract_1.compararUtf8)(a.destino, b.destino) || (0, intelligence_graph_contract_1.compararUtf8)(a.origem, b.origem));
+    // Dentro da mesma prioridade, intercalar tipos impede calls de expulsar imports/references.
+    const rodadas = new Map();
+    const justos = ordenados.map((g) => {
+        const chave = JSON.stringify([g.salto, g.alvo, g.entreArquivos, g.distancia, g.kind]);
+        const rodada = rodadas.get(chave) ?? 0;
+        rodadas.set(chave, rodada + 1);
+        return { g, rodada };
+    }).sort((a, b) => a.g.salto - b.g.salto || Number(b.g.entreArquivos) - Number(a.g.entreArquivos)
+        || (a.g.distancia === b.g.distancia ? 0 : a.g.distancia < b.g.distancia ? -1 : 1)
+        || a.rodada - b.rodada || compararTipo(a.g.kind, b.g.kind)
+        || (0, intelligence_graph_contract_1.compararUtf8)(a.g.destino, b.g.destino) || (0, intelligence_graph_contract_1.compararUtf8)(a.g.origem, b.g.origem)).map(({ g }) => g);
+    const normalizada = { ...entrada, diff, diffEstado: entrada.diffEstado ?? 'coletado-na-worktree',
+        claims: [...entrada.claims].sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)((0, intelligence_graph_contract_1.canonico)(a), (0, intelligence_graph_contract_1.canonico)(b))) };
+    const fixo = { schema: exports.CONTEXTO_SCHEMA, thread: entrada.thread, base: entrada.base, entrada_sha256: hash((0, intelligence_graph_contract_1.canonico)(normalizada)),
+        indice: { ...indice, extratores },
+        fontes: { goal: entrada.goal === null ? 'ausente' : hash(entrada.goal), plan: entrada.plan === null ? 'ausente' : hash(entrada.plan),
+            diff: normalizada.diffEstado },
+        consulta: { profundidade: 2, sentido: 'ambos', por_alvo: exports.CONTEXTO_POR_ALVO, fora_do_indice: exports.CONTEXTO_FORA_DO_INDICE },
+        total_sementes: sementes.length, sementes_fora_do_indice: ausentes.length, total_arestas: totalArestas,
+        total_ligacoes: ordenados.length, resumidas: { estruturais }, parcial: intelligence_graph_query_1.AVISO_DE_PARCIALIDADE };
+    const selecionadas = [], ligacoes = [];
+    // D4 e D5: as evidencias do grupo estao no arquivo da origem; o alvo pesa como nas consultas por no.
+    const modificado = (a) => (a.modificada ??= situacao(a.origem.slice(5)) !== 'igual' || situacao(porId.get(a.alvo).locator.path) !== 'igual');
+    const totalDiretas = ordenados.filter((a) => a.salto === 1).length;
+    const totalSegundoSalto = ordenados.length - totalDiretas;
+    const montar = () => {
+        const caminhos = new Set(selecionadas.filter((s) => s.estado === 'indexado').map((s) => s.arquivo));
+        const rotulos = new Set([...caminhos].map((p) => `file ${p}`));
+        for (const a of ligacoes) {
+            rotulos.add(a.origem);
+            rotulos.add(a.destino);
+            caminhos.add(porId.get(a.alvo).locator.path);
+            caminhos.add(a.origem.slice(5));
+        }
+        const refs = new Map([...rotulos].sort(intelligence_graph_contract_1.compararUtf8).map((r, i) => [r, `n${i + 1}`]));
+        const fontes = grafo.snapshot.source_manifest.filter((m) => caminhos.has(m.path)).sort((a, b) => (0, intelligence_graph_contract_1.compararUtf8)(a.path, b.path));
+        const diretas = ligacoes.filter((a) => a.salto === 1);
+        const omitidos = { sementes: sementes.length - selecionadas.length, ligacoes: totalDiretas - diretas.length,
+            segundo_salto: totalSegundoSalto - (ligacoes.length - diretas.length),
+            arestas: totalArestas - estruturais - ligacoes.reduce((s, a) => s + a.quantidade, 0), evidencias_auxiliares: evidenciasAuxiliares };
+        const diretasOmitidas = arestasDiretas - estruturais - diretas.reduce((s, a) => s + a.quantidade, 0);
+        const cortado = omitidos.sementes > 0 || omitidos.ligacoes > 0 || diretasOmitidas > 0 || auxiliaresDiretas > 0;
+        const r = { ...fixo, sementes: selecionadas, nos: Object.fromEntries([...refs].map(([r, ref]) => [ref, r])),
+            arestas: ligacoes.map((a) => ({ kind: a.kind, from: refs.get(a.origem), to: refs.get(a.destino), quantidade: a.quantidade,
+                ...(a.salto === 2 ? { salto: 2 } : {}), ...(modificado(a) ? { arvore: 'modificada' } : {}),
+                evidencias: [...a.evidencias].sort(([a], [b]) => (0, intelligence_graph_contract_1.compararUtf8)(a, b)).map(([, e]) => e) })),
+            truncado: cortado, omitidos, teto: { bytes: tetoBytes, cortado },
+            medida: { pacote_bytes: 0, leitura_crua_bytes: fontes.reduce((s, f) => s + f.size_bytes, 0),
+                arquivos: fontes.map((f) => ({ path: f.path, bytes: f.size_bytes })),
+                origem: 'source_manifest; tamanho dos arquivos, nao custo de descoberta', tokens: 'unavailable' } };
+        let texto = (0, intelligence_graph_contract_1.canonico)(r);
+        while (r.medida.pacote_bytes !== Buffer.byteLength(texto)) {
+            r.medida.pacote_bytes = Buffer.byteLength(texto);
+            texto = (0, intelligence_graph_contract_1.canonico)(r);
+        }
+        return texto;
+    };
+    let melhor = montar();
+    if (Buffer.byteLength(melhor) > tetoBytes)
+        throw new intelligence_graph_query_1.ErroDeConsulta('grafo.contexto.teto-excedido', 'cabecalho nao cabe no teto');
+    const tentarSemente = (s) => {
+        selecionadas.push(s);
+        const texto = montar();
+        if (Buffer.byteLength(texto) <= tetoBytes)
+            melhor = texto;
+        else
+            selecionadas.pop();
+    };
+    for (const s of indexadas)
+        tentarSemente(s);
+    const porAlvo = new Map();
+    const tentarLigacao = (a) => {
+        if ((porAlvo.get(a.alvo) ?? 0) >= exports.CONTEXTO_POR_ALVO)
+            return 'por-alvo';
+        ligacoes.push(a);
+        const texto = montar();
+        if (Buffer.byteLength(texto) <= tetoBytes) {
+            melhor = texto;
+            porAlvo.set(a.alvo, (porAlvo.get(a.alvo) ?? 0) + 1);
+            return 'incluida';
+        }
+        ligacoes.pop(); // Um hub grande nao impede uma ligacao menor e relevante de entrar.
+        return 'sem-espaco';
+    };
+    for (const a of justos)
+        if (a.salto === 1)
+            tentarLigacao(a);
+    for (const s of ausentes.slice(0, exports.CONTEXTO_FORA_DO_INDICE))
+        tentarSemente(s);
+    // Expande somente pontes que sobreviveram ao corte direto; a fronteira fica fixa nesta rodada.
+    const pontes = new Set(ligacoes.flatMap((a) => [a.origem.slice(5), porId.get(a.alvo).locator.path]));
+    let rejeicoes = 0;
+    for (const a of justos)
+        if (a.salto === 2 && (pontes.has(a.origem.slice(5)) || pontes.has(porId.get(a.alvo).locator.path))) {
+            const resultado = tentarLigacao(a);
+            if (resultado === 'incluida')
+                rejeicoes = 0;
+            else if (resultado === 'sem-espaco' && ++rejeicoes >= LIMITE_REJEICOES_SEGUNDO_SALTO)
+                break;
+        }
+    return melhor;
+}

package/dist/intelligence-graph-contract.js

@@ -29,7 +29,7 @@ exports.GRAFO_LIMITES = Object.freeze({
     extratores: 32, diagnosticos: 100_000, caminho: 1024, fragmento: 512, paginas: 100_000,
 });
 exports.TIPOS_DE_NO = ['file', 'symbol', 'section', 'artifact'];
-exports.TIPOS_DE_ARESTA = ['contains', 'declares', 'imports', 'calls', 'references', 'derived_from'];
+exports.TIPOS_DE_ARESTA = ['contains', 'declares', 'imports', 'calls', 'references', 'derived_from', 'cites'];
 /** D4: so metodo deterministico sustenta aresta. Embedding, similaridade e inferencia ficam fora. */
 exports.METODOS_DE_EXTRACAO = ['ast', 'structured', 'explicit-link', 'text-location'];
 exports.CLASSE_DE_CONFIANCA = 'EXTRACTED';
@@ -45,6 +45,7 @@ exports.MATRIZ_DE_ARESTAS = Object.freeze({
     imports: { file: ['file', 'symbol'], symbol: ['file', 'symbol'], section: nenhum, artifact: nenhum },
     calls: { file: nenhum, symbol: ['symbol'], section: nenhum, artifact: nenhum },
     references: { file: exports.TIPOS_DE_NO, symbol: exports.TIPOS_DE_NO, section: exports.TIPOS_DE_NO, artifact: exports.TIPOS_DE_NO },
+    cites: { file: ['file'], symbol: nenhum, section: ['file'], artifact: nenhum },
     derived_from: { file: nenhum, symbol: nenhum, section: nenhum, artifact: ['file', 'section', 'artifact'] },
 });
 const inteiro = zod_1.z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);