@orkastery/cli 0.4.2 → 0.5.0

package/dist/intelligence-graph-parsers.js

@@ -0,0 +1,327 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PACOTES_DOS_ANALISADORES = void 0;
+exports.pacotesDosAnalisadores = pacotesDosAnalisadores;
+exports.versoesDosAnalisadores = versoesDosAnalisadores;
+exports.criarJuizDeSintaxe = criarJuizDeSintaxe;
+exports.carregarAnalisadores = carregarAnalisadores;
+/**
+ * RM-031 KG3 (D1): os analisadores do extrator do grafo, carregados da instalacao do `ork` que
+ * roda. Sucede o adaptador do micromark e o juiz de sintaxe que o comando provisorio do KG2 levava
+ * em `core/scripts/` (KG2 D15 e D16), com o mesmo comportamento e as mesmas versoes.
+ *
+ * `typescript` e os pacotes do micromark so valem dentro da instalacao do `ork` que roda (o
+ * `node_modules` do pacote `@orkastery/cli` que contem este modulo), nunca do diretorio atual, do
+ * `NODE_PATH` nem de uma pasta acima, como a do projeto que instalou o `ork` como dependencia: o
+ * repositorio lido e dado, e codigo dele nunca e carregado. Eles nao sao dependencias de runtime do
+ * pacote publicado (D1: dependencia nova e decisao de produto); onde faltam ou estao fora da
+ * instalacao, a recusa e `grafo.parser.indisponivel: <pacote>`. `pacotesDosAnalisadores` lista o
+ * fecho de dependencias deles, com versao, para a chave do indice (CHECK rodada 1, A10).
+ *
+ * O juiz de sintaxe e o V8 do Node que roda a extracao, o mesmo que carregaria o arquivo. CommonJS
+ * compila aqui, em funcao com as variaveis do modulo, como o carregador faz. ESM compila num unico
+ * processo filho por chamada, com `vm.SourceTextModule`, que so analisa o modulo, sem ligar nem
+ * avaliar. O filho roda sem ambiente e com argumentos fixos; o veredito volta estruturado no stdout
+ * e o stderr nunca e lido. Nada e executado.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const vm = __importStar(require("node:vm"));
+/** Os unicos pacotes que o nucleo carrega para extrair: o compilador e o micromark com a tabela GFM. */
+exports.PACOTES_DOS_ANALISADORES = [
+    'typescript', 'micromark', 'micromark-extension-gfm-table', 'decode-named-character-reference',
+    'micromark-util-decode-numeric-character-reference',
+];
+const NOME_DA_INSTALACAO = '@orkastery/cli';
+function lerJson(arquivo) {
+    try {
+        return JSON.parse(fs.readFileSync(arquivo, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** A raiz do pacote `@orkastery/cli` que contem este modulo: `dist/` ou `dist-test/src/` ficam abaixo dela. */
+function raizDaInstalacao() {
+    for (let dir = __dirname;; dir = path.dirname(dir)) {
+        if (lerJson(path.join(dir, 'package.json'))?.name === NOME_DA_INSTALACAO)
+            return dir;
+        if (path.dirname(dir) === dir)
+            throw new Error('grafo.parser.indisponivel: instalacao do ork nao encontrada');
+    }
+}
+/**
+ * O `node_modules` da instalacao pelo caminho real: o `require.resolve` devolve o caminho real do
+ * pacote, e o `node_modules` pode ser link simbolico (clone com as dependencias ligadas, pnpm).
+ * CHECK rodada 2 (R2-B1): comparar o caminho sem resolver recusava a instalacao inteira.
+ */
+function modulosDaInstalacao(raiz) {
+    try {
+        return fs.realpathSync(path.join(raiz, 'node_modules'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Sem `node_modules` na instalacao, nada esta dentro dela. */
+const dentro = (modulos, alvo) => modulos !== null && alvo.startsWith(modulos + path.sep);
+/**
+ * Resolve a entrada do pacote a partir da instalacao e sobe ate o `package.json` com o nome dele,
+ * sem sair do pacote. O `exports` do micromark nao expoe o `package.json`, e um `package.json` de
+ * subpasta (`{ "type": "module" }`) nao tem nome. Entrada fora do `node_modules` da instalacao
+ * (pasta acima, `NODE_PATH`, pasta global) e recusada antes de qualquer leitura dela.
+ */
+function pacoteDe(nome) {
+    const raiz = raizDaInstalacao();
+    let entrada;
+    try {
+        entrada = require.resolve(nome, { paths: [raiz] });
+    }
+    catch {
+        throw new Error(`grafo.parser.indisponivel: ${nome}`);
+    }
+    if (!dentro(modulosDaInstalacao(raiz), entrada))
+        throw new Error(`grafo.parser.indisponivel: ${nome} fora da instalacao do ork`);
+    for (let dir = path.dirname(entrada); path.basename(dir) !== 'node_modules' && path.dirname(dir) !== dir; dir = path.dirname(dir)) {
+        const dados = lerJson(path.join(dir, 'package.json'));
+        if (dados && dados.name === nome && typeof dados.version === 'string')
+            return { entrada, dir, versao: dados.version };
+    }
+    throw new Error(`grafo.parser.indisponivel: ${nome} sem package.json`);
+}
+/**
+ * O `package.json` da dependencia `dep` vista de `de`, pela busca do Node, sem sair da instalacao.
+ * Tudo em caminho real: `de` vem do `require.resolve`, e o topo e a pasta real que contem o
+ * `node_modules` da instalacao.
+ */
+function pacoteInstalado(modulos, dep, de) {
+    if (modulos === null)
+        return null;
+    const topo = path.dirname(modulos);
+    for (let dir = de; dir === topo || dir.startsWith(topo + path.sep); dir = path.dirname(dir)) {
+        if (path.basename(dir) !== 'node_modules') {
+            const arquivo = path.join(dir, 'node_modules', dep, 'package.json');
+            if (fs.existsSync(arquivo)) {
+                const real = fs.realpathSync(arquivo);
+                return dentro(modulos, real) ? real : null;
+            }
+        }
+        if (dir === topo)
+            break;
+    }
+    return null;
+}
+/**
+ * CHECK rodada 1 (A10): o fecho de dependencias dos analisadores, `nome@versao` ordenado. O parser
+ * de CommonMark (`micromark-core-commonmark`) e os utilitarios mudam o grafo sem mudar a versao do
+ * micromark: a chave do indice precisa deles.
+ */
+function pacotesDosAnalisadores() {
+    const modulos = modulosDaInstalacao(raizDaInstalacao()), vistos = new Map();
+    const fila = exports.PACOTES_DOS_ANALISADORES.map((p) => path.join(pacoteDe(p).dir, 'package.json'));
+    while (fila.length) {
+        const arquivo = fila.shift();
+        const dados = lerJson(arquivo);
+        if (!dados || typeof dados.name !== 'string' || typeof dados.version !== 'string')
+            throw new Error(`grafo.parser.indisponivel: ${arquivo} ilegivel`);
+        const chave = `${dados.name}@${dados.version}`;
+        if (vistos.has(arquivo))
+            continue;
+        vistos.set(arquivo, chave);
+        const obrigatorias = new Set(Object.keys(dados.dependencies ?? {}));
+        const deps = [...new Set([...obrigatorias, ...Object.keys(dados.optionalDependencies ?? {})])].sort();
+        for (const dep of deps) {
+            const achado = pacoteInstalado(modulos, dep, path.dirname(arquivo));
+            if (achado && !vistos.has(achado))
+                fila.push(achado);
+            // Opcional que nao veio e normal; obrigatoria que falta dentro da instalacao fica marcada, e a carga recusa.
+            else if (!achado && obrigatorias.has(dep))
+                vistos.set(`${arquivo}\u0000${dep}`, `${dep}@ausente`);
+        }
+    }
+    return [...new Set(vistos.values())].sort();
+}
+function versoesDosAnalisadores() {
+    const versoes = Object.fromEntries(exports.PACOTES_DOS_ANALISADORES.map((p) => [p, pacoteDe(p).versao]));
+    return {
+        typescript: versoes.typescript,
+        javascript: `node.${process.versions.node}`,
+        markdown: `micromark.${versoes.micromark}.gfm-table.${versoes['micromark-extension-gfm-table']}`,
+        unicode: String(process.versions.unicode),
+    };
+}
+/** O micromark e so ESM: o `require` de ESM do Node carrega; onde ele nao existe, a recusa e tipada. */
+function carregar(nome) {
+    const { entrada } = pacoteDe(nome);
+    try {
+        return require(entrada);
+    }
+    catch (e) {
+        throw new Error(`grafo.parser.indisponivel: ${nome} (${e.code ?? 'erro ao carregar'})`);
+    }
+}
+/**
+ * KG2 D15: `analisar(texto)` devolve os eventos do micromark com o offset no texto (unidades UTF-16);
+ * `referencia(valor)` decodifica uma referencia de caractere (`eacute`, `#233`, `#xE9`) com as
+ * funcoes que o micromark usa ao gerar HTML, e devolve `null` se o nome nao e entidade do HTML5.
+ */
+function carregarMarkdown(versao) {
+    const { parse, postprocess, preprocess } = carregar('micromark');
+    const { gfmTable } = carregar('micromark-extension-gfm-table');
+    const { decodeNamedCharacterReference } = carregar('decode-named-character-reference');
+    const { decodeNumericCharacterReference } = carregar('micromark-util-decode-numeric-character-reference');
+    if (typeof parse !== 'function' || typeof postprocess !== 'function' || typeof preprocess !== 'function' || typeof gfmTable !== 'function'
+        || typeof decodeNamedCharacterReference !== 'function' || typeof decodeNumericCharacterReference !== 'function') {
+        throw new Error('grafo.parser.indisponivel: micromark sem a API esperada');
+    }
+    const extensions = [gfmTable()];
+    const referencia = (valor) => {
+        if (valor[0] !== '#')
+            return decodeNamedCharacterReference(valor) || null;
+        const hexa = valor[1] === 'x' || valor[1] === 'X';
+        return decodeNumericCharacterReference(valor.slice(hexa ? 2 : 1), hexa ? 16 : 10);
+    };
+    const analisar = (texto) => postprocess(parse({ extensions }).document().write(preprocess()(texto, undefined, true)))
+        .map(([tipo, token]) => ({ entrada: tipo === 'enter', tipo: token.type, inicio: token.start.offset, fim: token.end.offset }));
+    return { analisar, referencia, versao };
+}
+const VARIAVEIS_DO_CJS = ['exports', 'require', 'module', '__filename', '__dirname'];
+/** O V8 encerra a linha, e a linha `#!`, em LF, CR, U+2028 e U+2029. */
+const FIM_DE_LINHA = new Set([0x0a, 0x0d, 0x2028, 0x2029]);
+/** Processo filho: le os textos por stdin e devolve 1 (aceito), 0 (SyntaxError), 3 (pilha estourada) ou 2 (outro erro). */
+const FILHO = `
+const vm = require('node:vm');
+const partes = [];
+process.stdin.on('data', (c) => partes.push(c));
+process.stdin.on('end', () => {
+  const textos = JSON.parse(Buffer.concat(partes).toString('utf8'));
+  const r = textos.map((t) => {
+    try { new vm.SourceTextModule(t); return 1; } catch (e) { return e instanceof SyntaxError ? 0 : e instanceof RangeError ? 3 : 2; }
+  });
+  process.stdout.write(JSON.stringify(r));
+});
+`;
+/**
+ * Como o carregador do Node le a fonte: a linha `#!` do inicio em branco e, so no ESM, sem o BOM (o
+ * carregador CommonJS recusa BOM antes do `#!`).
+ */
+function comoOCarregadorLe(texto, formato) {
+    const t = formato === 'esm' && texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto;
+    if (!t.startsWith('#!'))
+        return t;
+    let fim = 2;
+    while (fim < t.length && !FIM_DE_LINHA.has(t.charCodeAt(fim)))
+        fim++;
+    return ' '.repeat(fim) + t.slice(fim);
+}
+/** KG2 D16: o juiz de sintaxe do JavaScript, em lote e com cache por texto dentro de uma extracao. */
+function criarJuizDeSintaxe() {
+    const vistos = new Map();
+    const cjs = (texto) => {
+        try {
+            vm.compileFunction(texto, VARIAVEIS_DO_CJS);
+            return true;
+        }
+        catch (e) {
+            if (e instanceof SyntaxError)
+                return false;
+            throw e;
+        }
+    };
+    const esmEmLote = (textos) => {
+        const r = (0, node_child_process_1.spawnSync)(process.execPath, ['--experimental-vm-modules', '--no-warnings', '-e', FILHO], {
+            input: JSON.stringify(textos), encoding: 'utf8', env: {}, maxBuffer: 64 * 1024 * 1024, timeout: 600000,
+        });
+        if (r.error || r.signal || r.status !== 0) {
+            throw new Error(`sintaxe.esm.indisponivel: ${r.error ? r.error.code ?? 'erro' : r.signal ?? `status ${r.status}`}`);
+        }
+        let vereditos = null;
+        try {
+            vereditos = JSON.parse(r.stdout);
+        }
+        catch {
+            vereditos = null;
+        }
+        if (!Array.isArray(vereditos) || vereditos.length !== textos.length || vereditos.some((v) => ![0, 1, 2, 3].includes(v))) {
+            throw new Error('sintaxe.esm.indisponivel: resposta invalida do filho');
+        }
+        // Pilha estourada no V8 do filho: o extrator a trata como a propria (`extracao.limite.pilha`).
+        if (vereditos.includes(3))
+            throw new RangeError('Maximum call stack size exceeded no juiz de sintaxe ESM');
+        if (vereditos.includes(2))
+            throw new Error('sintaxe.esm.indisponivel: erro que nao e de sintaxe no filho');
+        return vereditos.map((v) => v === 1);
+    };
+    const sintaxe = (pedidos) => {
+        const chaves = pedidos.map((p) => p.formato + (0, node_crypto_1.createHash)('sha256').update(p.texto).digest('hex'));
+        const esm = new Map();
+        pedidos.forEach((p, i) => {
+            if (vistos.has(chaves[i]) || esm.has(chaves[i]))
+                return;
+            const t = comoOCarregadorLe(p.texto, p.formato);
+            if (p.formato === 'cjs')
+                vistos.set(chaves[i], cjs(t));
+            else
+                esm.set(chaves[i], t);
+        });
+        if (esm.size) {
+            const lista = [...esm];
+            const r = esmEmLote(lista.map(([, t]) => t));
+            lista.forEach(([k], i) => vistos.set(k, r[i]));
+        }
+        return chaves.map((k) => vistos.get(k));
+    };
+    return { sintaxe, versao: `node.${process.versions.node}` };
+}
+/**
+ * O `Parser` do extrator do KG2, com o compilador e o micromark desta instalacao. Confere que o
+ * compilador carregado e o da versao lida para a chave do indice.
+ */
+function carregarAnalisadores() {
+    const versoes = versoesDosAnalisadores();
+    // CHECK rodada 3: dependencia transitiva que falta dentro da instalacao seria achada pelo Node fora
+    // dela (no node_modules de uma pasta acima) e carregada. Recusa antes de carregar qualquer pacote.
+    const ausentes = pacotesDosAnalisadores().filter((p) => p.endsWith('@ausente'));
+    if (ausentes.length)
+        throw new Error(`grafo.parser.indisponivel: dependencia fora da instalacao do ork (${ausentes.join(', ')})`);
+    const ts = carregar('typescript');
+    if (!ts || typeof ts.createProgram !== 'function' || ts.version !== versoes.typescript) {
+        throw new Error(`grafo.parser.indisponivel: typescript ${ts.version} carregado, ${versoes.typescript} no package.json`);
+    }
+    return { ts, unicode: versoes.unicode, markdown: carregarMarkdown(versoes.markdown), javascript: criarJuizDeSintaxe() };
+}

package/dist/intelligence-graph-query.js

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rotuloDoNo = exports.ErroDeConsulta = exports.AVISO_DE_PARCIALIDADE = exports.CANDIDATOS_LISTADOS = exports.LIMITE_MAXIMO = exports.LIMITE_PADRAO = exports.PROFUNDIDADE_MAXIMA = exports.CONSULTA_SCHEMA = void 0;
+exports.filtrarGrafo = filtrarGrafo;
+exports.prepararConsulta = prepararConsulta;
+exports.resolverNo = resolverNo;
+exports.vizinhos = vizinhos;
+exports.chamadores = chamadores;
+exports.importadores = importadores;
+exports.caminho = caminho;
+exports.jsonDaResposta = jsonDaResposta;
+exports.textoDaResposta = textoDaResposta;
+/**
+ * RM-031 KG3 (D5 a D7): consulta sobre o grafo do indice.
+ *
+ * Modulo puro: recebe o grafo ja lido e a concessao, sem arquivo, processo, rede, relogio nem acaso.
+ * So percorre arestas do grafo: nada de busca textual, inferencia ou similaridade. O que o extrator
+ * do KG2 nao prova nao esta no grafo, e toda resposta diz que e parcial.
+ *
+ * D6: a concessao filtra antes de qualquer mapa (`filtrarGrafo`): no, aresta, evidencia e
+ * diagnostico fora dela nao existem para a consulta nem para a amostra, nem em resposta, contagem,
+ * candidato ou erro.
+ *
+ * D7: a resposta e a mesma para o mesmo grafo e a mesma pergunta, byte a byte, em texto e em JSON
+ * (`ork.code-graph-query/v0`, provisorio e fora do contrato): ordem por code point, sem horario.
+ */
+const intelligence_graph_contract_1 = require("./intelligence-graph-contract");
+exports.CONSULTA_SCHEMA = 'ork.code-graph-query/v0';
+exports.PROFUNDIDADE_MAXIMA = 5;
+exports.LIMITE_PADRAO = 500;
+exports.LIMITE_MAXIMO = 10_000;
+/** Candidatos listados quando um nome solto e ambiguo. */
+exports.CANDIDATOS_LISTADOS = 20;
+exports.AVISO_DE_PARCIALIDADE = 'parcial: so arestas que o extrator prova; chamada por despacho de tipo, import nao resolvido e as lacunas do relatorio de extracao ficam fora';
+/** Erro tipado da consulta; `candidatos` so no nome ambiguo, e so com nos visiveis. */
+class ErroDeConsulta extends Error {
+    codigo;
+    detalhe;
+    candidatos;
+    constructor(codigo, detalhe, candidatos = []) {
+        super(`${codigo}: ${detalhe}`);
+        this.codigo = codigo;
+        this.detalhe = detalhe;
+        this.candidatos = candidatos;
+    }
+}
+exports.ErroDeConsulta = ErroDeConsulta;
+const TIPOS_DE_NO_COM_FRAGMENTO = ['symbol', 'section', 'artifact'];
+const chaveDoLocalizador = (kind, p, fragmento) => `${kind}\u0000${p}\u0000${fragmento ?? ''}`;
+const rotuloDoNo = (n) => `${n.kind} ${n.locator.path}${n.locator.fragment === null ? '' : `#${n.locator.fragment}`}`;
+exports.rotuloDoNo = rotuloDoNo;
+function visivel(a, c) {
+    return a.tenant_id === c.tenant_id && a.acl_refs.every((r) => c.acl_refs.includes(r));
+}
+/**
+ * D6: o grafo so com o que a concessao ve. Aresta precisa estar visivel, com as duas pontas visiveis
+ * e ao menos uma evidencia visivel; evidencia e diagnostico fora da concessao saem.
+ */
+function filtrarGrafo(grafo, concessao) {
+    const nodes = grafo.nodes.filter((n) => visivel(n.access, concessao));
+    const ids = new Set(nodes.map((n) => n.node_id));
+    const edges = [];
+    for (const a of grafo.edges) {
+        if (!visivel(a.access, concessao) || !ids.has(a.from) || !ids.has(a.to))
+            continue;
+        const evidence = a.evidence.filter((e) => visivel(e.access, concessao));
+        if (evidence.length)
+            edges.push(evidence.length === a.evidence.length ? a : { ...a, evidence });
+    }
+    return { ...grafo, nodes, edges, diagnostics: grafo.diagnostics.filter((d) => visivel(d.access, concessao)) };
+}
+/** D6: filtra pela concessao e monta os mapas. Nada fora dela entra em mapa nenhum. */
+function prepararConsulta(grafoInteiro, concessao) {
+    const grafo = filtrarGrafo(grafoInteiro, concessao);
+    const nos = new Map(), rotulos = new Map(), porLocalizador = new Map();
+    const arquivos = new Map(), porFragmento = new Map();
+    for (const n of grafo.nodes) {
+        nos.set(n.node_id, n);
+        rotulos.set(n.node_id, (0, exports.rotuloDoNo)(n));
+        porLocalizador.set(chaveDoLocalizador(n.kind, n.locator.path, n.locator.fragment), n);
+        if (n.kind === 'file')
+            arquivos.set(n.locator.path, n);
+        else if (n.locator.fragment !== null) {
+            const lista = porFragmento.get(n.locator.fragment) ?? [];
+            lista.push(n);
+            porFragmento.set(n.locator.fragment, lista);
+        }
+    }
+    const saida = new Map(), entrada = new Map();
+    for (const aresta of grafo.edges) {
+        for (const [mapa, id] of [[saida, aresta.from], [entrada, aresta.to]]) {
+            const lista = mapa.get(id) ?? [];
+            lista.push(aresta);
+            mapa.set(id, lista);
+        }
+    }
+    const ordem = (outra) => (x, y) => (0, intelligence_graph_contract_1.compararUtf8)(x.kind, y.kind) || (0, intelligence_graph_contract_1.compararUtf8)(outra(x), outra(y)) || (0, intelligence_graph_contract_1.compararUtf8)(x.edge_id, y.edge_id);
+    for (const lista of saida.values())
+        lista.sort(ordem((a) => rotulos.get(a.to)));
+    for (const lista of entrada.values())
+        lista.sort(ordem((a) => rotulos.get(a.from)));
+    for (const lista of porFragmento.values())
+        lista.sort((x, y) => (0, intelligence_graph_contract_1.compararUtf8)((0, exports.rotuloDoNo)(x), (0, exports.rotuloDoNo)(y)));
+    return { repository_id: grafo.repository_id, snapshot_id: grafo.snapshot.snapshot_id, nos, rotulos, porLocalizador, arquivos, porFragmento, saida, entrada };
+}
+function ambiguo(texto, candidatos) {
+    const rotulos = candidatos.map(exports.rotuloDoNo).sort(intelligence_graph_contract_1.compararUtf8);
+    const listados = rotulos.slice(0, exports.CANDIDATOS_LISTADOS);
+    throw new ErroDeConsulta('grafo.consulta.ambiguo', `${texto} tem ${rotulos.length} candidatos: ${listados.join('; ')}${rotulos.length > listados.length ? '; ...' : ''}`, listados);
+}
+/** Os nos com o localizador `caminho#fragmento` em cada `#` do texto: o fragmento tambem pode ter `#` (`Classe.#privado`). */
+function porLocalizadores(g, texto, tipos) {
+    const achados = new Map();
+    for (let i = texto.indexOf('#'); i > 0; i = texto.indexOf('#', i + 1)) {
+        for (const k of tipos) {
+            const n = g.porLocalizador.get(chaveDoLocalizador(k, texto.slice(0, i), texto.slice(i + 1)));
+            if (n)
+                achados.set(n.node_id, n);
+        }
+    }
+    return [...achados.values()];
+}
+/**
+ * D5: o no pelo texto. `tipo:caminho#fragmento` fixa o tipo; `caminho` exato e o arquivo;
+ * `caminho#fragmento` e o no com esse localizador, em qualquer `#` que separe um caminho que existe;
+ * o resto e nome solto, que casa o fragmento exato de um simbolo, secao ou artefato. Ambiguo lista os
+ * candidatos, nunca escolhe. O rotulo que a resposta imprime (sem o tipo) volta como entrada.
+ */
+function resolverNo(g, texto) {
+    if (!texto)
+        throw new ErroDeConsulta('grafo.consulta.uso', 'no vazio');
+    const desconhecido = () => {
+        throw new ErroDeConsulta('grafo.consulta.no-desconhecido', texto);
+    };
+    const tipado = /^(file|symbol|section|artifact):(.+)$/.exec(texto);
+    if (tipado) {
+        const kind = tipado[1], resto = tipado[2];
+        if (kind === 'file')
+            return g.arquivos.get(resto) ?? desconhecido();
+        const candidatos = porLocalizadores(g, resto, [kind]);
+        if (candidatos.length === 1)
+            return candidatos[0];
+        if (candidatos.length > 1)
+            ambiguo(texto, candidatos);
+        return desconhecido();
+    }
+    const arquivo = g.arquivos.get(texto);
+    if (arquivo)
+        return arquivo;
+    const candidatos = porLocalizadores(g, texto, TIPOS_DE_NO_COM_FRAGMENTO);
+    if (candidatos.length === 1)
+        return candidatos[0];
+    if (candidatos.length > 1)
+        ambiguo(texto, candidatos);
+    const soltos = g.porFragmento.get(texto) ?? [];
+    if (soltos.length === 1)
+        return soltos[0];
+    if (soltos.length > 1)
+        ambiguo(texto, soltos);
+    return desconhecido();
+}
+function noDaResposta(g, n, distancia) {
+    return { rotulo: g.rotulos.get(n.node_id), kind: n.kind, path: n.locator.path, fragment: n.locator.fragment, node_id: n.node_id, distancia };
+}
+function arestaDaResposta(g, a, distancia) {
+    const evidencias = a.evidence.map((e) => ({
+        extractor_id: e.extractor_id, extractor_version: e.extractor_version, extraction_method: e.extraction_method, path: e.path, span: e.span,
+    })).sort((x, y) => (0, intelligence_graph_contract_1.compararUtf8)(x.path, y.path) || (x.span.byte_start - y.span.byte_start) || (x.span.byte_end - y.span.byte_end)
+        || (0, intelligence_graph_contract_1.compararUtf8)(x.extractor_id, y.extractor_id) || (0, intelligence_graph_contract_1.compararUtf8)(x.extraction_method, y.extraction_method));
+    return { kind: a.kind, from: g.rotulos.get(a.from), to: g.rotulos.get(a.to), edge_id: a.edge_id, distancia, evidencias };
+}
+/** CHECK rodada 1 (A2): primeiro as arestas mais perto do alvo, e o limite corta as mais longe. */
+const ordemDasArestas = (x, y) => (x.distancia - y.distancia)
+    || (0, intelligence_graph_contract_1.compararUtf8)(x.kind, y.kind) || (0, intelligence_graph_contract_1.compararUtf8)(x.from, y.from) || (0, intelligence_graph_contract_1.compararUtf8)(x.to, y.to) || (0, intelligence_graph_contract_1.compararUtf8)(x.edge_id, y.edge_id);
+function incidentes(g, id, sentido, tipos) {
+    const r = [];
+    if (sentido !== 'entrada')
+        for (const a of g.saida.get(id) ?? [])
+            if (tipos.has(a.kind))
+                r.push({ aresta: a, outra: a.to, sentido: 'saida' });
+    if (sentido !== 'saida')
+        for (const a of g.entrada.get(id) ?? [])
+            if (tipos.has(a.kind))
+                r.push({ aresta: a, outra: a.from, sentido: 'entrada' });
+    return r;
+}
+function inteiroEntre(nome, v, min, max) {
+    if (!Number.isSafeInteger(v) || v < min || v > max)
+        throw new ErroDeConsulta('grafo.consulta.uso', `${nome} precisa ser inteiro de ${min} a ${max}`);
+    return v;
+}
+function tiposValidos(tipos) {
+    const lista = [...new Set(tipos ?? intelligence_graph_contract_1.TIPOS_DE_ARESTA)];
+    for (const t of lista)
+        if (!intelligence_graph_contract_1.TIPOS_DE_ARESTA.includes(t))
+            throw new ErroDeConsulta('grafo.consulta.uso', `tipo de aresta desconhecido: ${t}`);
+    if (!lista.length)
+        throw new ErroDeConsulta('grafo.consulta.uso', 'nenhum tipo de aresta');
+    return lista.sort(intelligence_graph_contract_1.compararUtf8);
+}
+/**
+ * D5: o raio `profundidade` em volta do alvo, pelo sentido e pelos tipos pedidos. Entram os nos a
+ * ate `profundidade` saltos e todas as arestas que saem dos nos a menos de `profundidade` saltos,
+ * cada uma com a distancia do no que a explorou. `limite` corta pela distancia e pela ordem fixa, e
+ * a lista de nos so traz o alvo e as pontas das arestas devolvidas.
+ */
+function vizinhanca(g, cabecalho, tipo, texto, opcoes) {
+    const profundidade = inteiroEntre('profundidade', opcoes.profundidade ?? 1, 1, exports.PROFUNDIDADE_MAXIMA);
+    const limite = inteiroEntre('limite', opcoes.limite ?? exports.LIMITE_PADRAO, 1, exports.LIMITE_MAXIMO);
+    const sentido = opcoes.sentido ?? 'ambos';
+    if (!['entrada', 'saida', 'ambos'].includes(sentido))
+        throw new ErroDeConsulta('grafo.consulta.uso', `sentido desconhecido: ${sentido}`);
+    const tipos = tiposValidos(opcoes.tipos), permitidos = new Set(tipos);
+    const alvo = resolverNo(g, texto);
+    const distancia = new Map([[alvo.node_id, 0]]), vistas = new Map();
+    let camada = [alvo.node_id];
+    for (let d = 0; d < profundidade && camada.length; d++) {
+        const proxima = [];
+        for (const id of camada.sort((x, y) => (0, intelligence_graph_contract_1.compararUtf8)(g.rotulos.get(x), g.rotulos.get(y)))) {
+            for (const { aresta, outra } of incidentes(g, id, sentido, permitidos)) {
+                if (!vistas.has(aresta.edge_id))
+                    vistas.set(aresta.edge_id, { aresta, d });
+                if (!distancia.has(outra)) {
+                    distancia.set(outra, d + 1);
+                    proxima.push(outra);
+                }
+            }
+        }
+        camada = proxima;
+    }
+    const todas = [...vistas.values()].map(({ aresta, d }) => arestaDaResposta(g, aresta, d)).sort(ordemDasArestas);
+    const devolvidas = todas.slice(0, limite);
+    const idPorRotulo = new Map([...distancia.keys()].map((id) => [g.rotulos.get(id), id]));
+    const pontas = new Set([alvo.node_id, ...devolvidas.flatMap((a) => [idPorRotulo.get(a.from), idPorRotulo.get(a.to)])]);
+    const nos = [...pontas].map((id) => noDaResposta(g, g.nos.get(id), distancia.get(id)))
+        .sort((x, y) => (x.distancia - y.distancia) || (0, intelligence_graph_contract_1.compararUtf8)(x.rotulo, y.rotulo));
+    return {
+        schema: exports.CONSULTA_SCHEMA,
+        consulta: { tipo, alvo: texto, para: null, profundidade, sentido, tipos, limite },
+        indice: cabecalho, alvo: noDaResposta(g, alvo, 0), para: null, nos, total_nos: distancia.size,
+        arestas: devolvidas, total_arestas: todas.length, truncado: todas.length > limite,
+        caminho: null, nos_explorados: null, parcial: exports.AVISO_DE_PARCIALIDADE,
+    };
+}
+function vizinhos(g, cabecalho, alvo, opcoes = {}) {
+    return vizinhanca(g, cabecalho, 'vizinhos', alvo, opcoes);
+}
+/** Quem chama o simbolo: as arestas `calls` que chegam, ate `profundidade` saltos. */
+function chamadores(g, cabecalho, alvo, opcoes = {}) {
+    if (resolverNo(g, alvo).kind !== 'symbol')
+        throw new ErroDeConsulta('grafo.consulta.alvo-invalido', 'chamadores pede um simbolo; para arquivo, use importadores ou vizinhos');
+    return vizinhanca(g, cabecalho, 'chamadores', alvo, { ...opcoes, sentido: 'entrada', tipos: ['calls'] });
+}
+/** Quem importa o arquivo ou o simbolo: as arestas `imports` que chegam, ate `profundidade` saltos. */
+function importadores(g, cabecalho, alvo, opcoes = {}) {
+    const kind = resolverNo(g, alvo).kind;
+    if (kind !== 'file' && kind !== 'symbol')
+        throw new ErroDeConsulta('grafo.consulta.alvo-invalido', 'importadores pede um arquivo ou um simbolo');
+    return vizinhanca(g, cabecalho, 'importadores', alvo, { ...opcoes, sentido: 'entrada', tipos: ['imports'] });
+}
+/**
+ * D5: o menor caminho de `de` a `para`, pelas arestas no sentido pedido (padrao: `saida`, a direcao
+ * da aresta). Busca em largura com a expansao na ordem fixa: entre caminhos do mesmo tamanho, sai
+ * sempre o mesmo. Sem caminho, `caminho` e `null`, com os nos explorados.
+ */
+function caminho(g, cabecalho, de, para, opcoes = {}) {
+    const sentido = opcoes.sentido ?? 'saida';
+    if (!['entrada', 'saida', 'ambos'].includes(sentido))
+        throw new ErroDeConsulta('grafo.consulta.uso', `sentido desconhecido: ${sentido}`);
+    const tipos = tiposValidos(opcoes.tipos), permitidos = new Set(tipos);
+    const origem = resolverNo(g, de), destino = resolverNo(g, para);
+    const anterior = new Map([[origem.node_id, null]]);
+    const fila = [origem.node_id];
+    for (let i = 0; i < fila.length && !anterior.has(destino.node_id); i++) {
+        for (const { aresta, outra, sentido: s } of incidentes(g, fila[i], sentido, permitidos)) {
+            if (anterior.has(outra))
+                continue;
+            anterior.set(outra, { de: fila[i], aresta, sentido: s });
+            fila.push(outra);
+        }
+    }
+    let passos = null;
+    let nos = [noDaResposta(g, origem, 0), noDaResposta(g, destino, null)];
+    if (anterior.has(destino.node_id)) {
+        const cadeia = [];
+        for (let id = destino.node_id, atual = anterior.get(id); atual; id = atual.de, atual = anterior.get(id)) {
+            cadeia.push({ id, passo: { sentido: atual.sentido, aresta: arestaDaResposta(g, atual.aresta, 0) } });
+        }
+        cadeia.reverse();
+        cadeia.forEach((c, n) => { c.passo.aresta.distancia = n; });
+        passos = cadeia.map((c) => c.passo);
+        nos = [origem.node_id, ...cadeia.map((c) => c.id)].map((id, d) => noDaResposta(g, g.nos.get(id), d));
+    }
+    return {
+        schema: exports.CONSULTA_SCHEMA,
+        consulta: { tipo: 'caminho', alvo: de, para, profundidade: null, sentido, tipos, limite: null },
+        indice: cabecalho, alvo: noDaResposta(g, origem, 0), para: noDaResposta(g, destino, passos ? passos.length : null),
+        nos, total_nos: nos.length,
+        arestas: passos ? passos.map((p) => p.aresta) : [], total_arestas: passos ? passos.length : 0, truncado: false,
+        caminho: passos, nos_explorados: anterior.size, parcial: exports.AVISO_DE_PARCIALIDADE,
+    };
+}
+function jsonDaResposta(r) {
+    return JSON.stringify(r, null, 2);
+}
+function linhasDaEvidencia(e) {
+    const s = e.span;
+    const onde = s.type === 'text'
+        ? `${e.path}:${s.line_start ?? '?'}${s.line_end !== null && s.line_end !== s.line_start ? `-${s.line_end}` : ''}`
+        : `${e.path} pagina ${s.page}`;
+    return `      ${e.extractor_id} ${e.extraction_method} ${onde} bytes ${s.byte_start}-${s.byte_end}`;
+}
+function linhasDaAresta(a, prefixo = '  ') {
+    return [`${prefixo}${a.kind}  ${a.from} -> ${a.to}`, ...a.evidencias.map(linhasDaEvidencia)];
+}
+function textoDaResposta(r) {
+    const c = r.consulta, i = r.indice;
+    const linhas = [
+        `grafo de ${i.repository_id} na revisao ${i.revision.slice(0, 12)}, indice ${i.chave.slice(0, 16)}, snapshot ${i.snapshot_id.slice(0, 17)}`,
+    ];
+    if (i.arvore === 'modificada')
+        linhas.push('aviso: a arvore tem mudanca rastreada; a resposta e do HEAD, nao da arvore');
+    linhas.push(`extratores: ${i.extratores.map((e) => `${e.extractor_id} ${e.extractor_version}`).join(', ')}`);
+    if (c.tipo === 'caminho') {
+        const para = r.para;
+        if (!r.caminho) {
+            linhas.push(`sem caminho de ${r.alvo.rotulo} para ${para.rotulo} (sentido ${c.sentido}): ${r.nos_explorados} nos explorados`);
+        }
+        else {
+            linhas.push(`caminho de ${r.alvo.rotulo} para ${para.rotulo} (sentido ${c.sentido}): ${r.caminho.length} passo(s)`);
+            r.caminho.forEach((p, n) => linhas.push(...linhasDaAresta(p.aresta, `  ${n + 1}. ${p.sentido === 'entrada' ? '(contra a aresta) ' : ''}`)));
+        }
+    }
+    else {
+        const filtro = c.tipo === 'vizinhos' ? `, sentido ${c.sentido}, tipos ${c.tipos.length === intelligence_graph_contract_1.TIPOS_DE_ARESTA.length ? 'todos' : c.tipos.join(',')}` : '';
+        linhas.push(`${c.tipo} de ${r.alvo.rotulo} (profundidade ${c.profundidade}${filtro}): ${r.total_arestas} aresta(s), ${r.total_nos - 1} no(s)`);
+        for (const a of r.arestas)
+            linhas.push(...linhasDaAresta(a));
+        if (r.truncado)
+            linhas.push(`truncado: ${r.arestas.length} de ${r.total_arestas} arestas, as mais perto do alvo; use --limite`);
+    }
+    linhas.push(r.parcial);
+    return linhas.join('\n');
+}