@semacode/cli 2.3.0 → 3.0.0

package/dist/driftCatalogo.js

@@ -0,0 +1,516 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift, sema.produto.governanca_ia.drift.cache.store
+// Descrição: cataloga somente o plano físico do drift e compartilha uma leitura estável por arquivo.
+import { createHash } from "node:crypto";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+const CONCORRENCIA_PADRAO = 8;
+const CONCORRENCIA_MAXIMA = 64;
+function emitirEvento(observador, evento) {
+    try {
+        observador?.(evento);
+    }
+    catch {
+        // Observabilidade nunca altera o resultado funcional do drift.
+    }
+}
+function normalizarConcorrencia(valor) {
+    if (!Number.isFinite(valor)) {
+        return CONCORRENCIA_PADRAO;
+    }
+    return Math.max(1, Math.min(CONCORRENCIA_MAXIMA, Math.trunc(valor)));
+}
+function normalizarExtensao(extensao) {
+    const limpa = extensao.trim().toLowerCase();
+    if (!limpa) {
+        return limpa;
+    }
+    return limpa.startsWith(".") ? limpa : `.${limpa}`;
+}
+function ehFiltroCatalogoDrift(valor) {
+    return !Array.isArray(valor);
+}
+function chaveCaminho(caminho) {
+    const normalizado = path.normalize(path.resolve(caminho));
+    return process.platform === "win32" ? normalizado.toLowerCase() : normalizado;
+}
+function caminhoEstaDentro(raiz, alvo) {
+    const relativo = path.relative(path.resolve(raiz), path.resolve(alvo));
+    return relativo === "" || (relativo !== ".."
+        && !relativo.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relativo));
+}
+function erroEhAusencia(erro) {
+    return ["ENOENT", "ENOTDIR"].includes(erro.code ?? "");
+}
+function assinaturaDiretorio(info) {
+    return {
+        mtimeNs: info.mtimeNs,
+        ctimeNs: info.ctimeNs,
+        dev: info.dev,
+        ino: info.ino,
+    };
+}
+function assinaturasDiretorioIguais(a, b) {
+    return a.mtimeNs === b.mtimeNs
+        && a.ctimeNs === b.ctimeNs
+        && a.dev === b.dev
+        && a.ino === b.ino;
+}
+function identidadeArquivoEstavel(a, b) {
+    return a.isFile()
+        && b.isFile()
+        && !a.isSymbolicLink()
+        && !b.isSymbolicLink()
+        && a.nlink === 1n
+        && b.nlink === 1n
+        && a.dev === b.dev
+        && a.ino === b.ino
+        && a.size === b.size
+        && a.mtimeNs === b.mtimeNs
+        && a.ctimeNs === b.ctimeNs;
+}
+function criarIdentidadeArquivoCatalogado(caminhoReal, informacao) {
+    return {
+        caminhoReal: path.resolve(caminhoReal),
+        dev: informacao.dev,
+        ino: informacao.ino,
+        nlink: informacao.nlink,
+        size: informacao.size,
+        mtimeNs: informacao.mtimeNs,
+        ctimeNs: informacao.ctimeNs,
+    };
+}
+function identidadeCatalogadaCorresponde(identidade, caminhoReal, informacao) {
+    return chaveCaminho(identidade.caminhoReal) === chaveCaminho(caminhoReal)
+        && informacao.isFile()
+        && !informacao.isSymbolicLink()
+        && identidade.nlink === 1n
+        && informacao.nlink === 1n
+        && identidade.dev === informacao.dev
+        && identidade.ino === informacao.ino
+        && identidade.size === informacao.size
+        && identidade.mtimeNs === informacao.mtimeNs
+        && identidade.ctimeNs === informacao.ctimeNs;
+}
+function chavesFisicasArquivo(identidade) {
+    const chaves = [`real:${chaveCaminho(identidade.caminhoReal)}`];
+    if (identidade.dev !== 0n || identidade.ino !== 0n) {
+        chaves.push(`id:${identidade.dev.toString()}:${identidade.ino.toString()}`);
+    }
+    return chaves;
+}
+function mesmoObjetoFisico(a, b) {
+    const possuiIdentidadeInode = (a.dev !== 0n || a.ino !== 0n) && (b.dev !== 0n || b.ino !== 0n);
+    return possuiIdentidadeInode
+        ? a.dev === b.dev && a.ino === b.ino
+        : chaveCaminho(a.caminhoReal) === chaveCaminho(b.caminhoReal);
+}
+async function mapearComLimite(itens, limite, executar) {
+    if (itens.length === 0) {
+        return [];
+    }
+    const resultados = new Array(itens.length);
+    let proximoIndice = 0;
+    const trabalhador = async () => {
+        for (;;) {
+            const indice = proximoIndice;
+            proximoIndice += 1;
+            if (indice >= itens.length) {
+                return;
+            }
+            resultados[indice] = await executar(itens[indice]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limite, itens.length) }, () => trabalhador()));
+    return resultados;
+}
+class CatalogoDriftImplementacao {
+    baseDiretorio;
+    raizes;
+    registros = new Map();
+    registrosFisicos = new Map();
+    conteudos = new Map();
+    extensoesPermitidas;
+    concorrencia;
+    observador;
+    baseDiretorioReal;
+    contadores = {
+        diretoriosVisitados: 0,
+        arquivosCatalogados: 0,
+        leiturasConteudo: 0,
+        bytesLidos: 0,
+        acertosMemoriaConteudo: 0,
+        origem: "plano_explicito",
+    };
+    constructor(opcoes) {
+        this.baseDiretorio = path.resolve(opcoes.baseDiretorio ?? process.cwd());
+        this.baseDiretorioReal = realpath(this.baseDiretorio);
+        this.raizes = [...new Map((opcoes.raizes ?? [])
+                .map((raiz) => path.resolve(this.baseDiretorio, raiz))
+                .filter((raiz) => caminhoEstaDentro(this.baseDiretorio, raiz))
+                .map((raiz) => [chaveCaminho(raiz), raiz])).values()].sort((a, b) => a.localeCompare(b, "pt-BR"));
+        const extensoes = opcoes.extensoes
+            ?.map(normalizarExtensao)
+            .filter(Boolean);
+        this.extensoesPermitidas = extensoes?.length
+            ? new Set(extensoes)
+            : undefined;
+        this.concorrencia = normalizarConcorrencia(opcoes.concorrencia);
+        this.observador = opcoes.observador;
+    }
+    async construir(arquivosExplicitos, diretoriosIgnorados) {
+        await this.baseDiretorioReal;
+        if (this.raizes.length > 0) {
+            this.contadores.origem = "caminhada";
+            await this.caminharRaizes(diretoriosIgnorados);
+        }
+        await this.incluir(arquivosExplicitos);
+    }
+    async incluir(arquivosExplicitos) {
+        const explicitos = [...new Map(arquivosExplicitos
+                .map((arquivo) => path.resolve(this.baseDiretorio, arquivo))
+                .map((arquivo) => [chaveCaminho(arquivo), arquivo])).values()].sort((a, b) => a.localeCompare(b, "pt-BR"));
+        const sondagens = await mapearComLimite(explicitos, this.concorrencia, async (arquivo) => this.sondarArquivoSeguro(arquivo));
+        for (const sondagem of sondagens
+            .filter((item) => Boolean(item))
+            .sort((a, b) => a.caminho.localeCompare(b.caminho, "pt-BR"))) {
+            this.adicionarArquivo(sondagem, true);
+        }
+    }
+    listar(extensoesOuFiltro = [], raizes) {
+        if (ehFiltroCatalogoDrift(extensoesOuFiltro)) {
+            return this.listarEntradas(extensoesOuFiltro).map((arquivo) => arquivo.caminho);
+        }
+        const extensoes = extensoesOuFiltro.length ? extensoesOuFiltro : undefined;
+        if (!raizes?.length) {
+            return this.listarEntradas({ extensoes }).map((arquivo) => arquivo.caminho);
+        }
+        const raizesAbsolutas = raizes.map((raiz) => path.resolve(this.baseDiretorio, raiz));
+        return [...new Map(raizesAbsolutas.flatMap((raiz) => this.listarEntradas({ extensoes, raiz }).map((arquivo) => [chaveCaminho(arquivo.caminho), arquivo.caminho]))).values()].sort((a, b) => a.localeCompare(b, "pt-BR"));
+    }
+    listarEntradas(filtro = {}) {
+        const extensoes = filtro.extensoes
+            ? new Set(filtro.extensoes.map(normalizarExtensao).filter(Boolean))
+            : undefined;
+        const raiz = filtro.raiz
+            ? path.resolve(this.baseDiretorio, filtro.raiz)
+            : undefined;
+        return [...new Set(this.registros.values())]
+            .filter((registro) => !extensoes || extensoes.has(registro.extensao))
+            .filter((registro) => !raiz || [...registro.aliases].some((alias) => caminhoEstaDentro(raiz, alias)))
+            .map((registro) => ({
+            caminho: registro.caminho,
+            extensao: registro.extensao,
+            explicito: registro.explicito,
+            raizes: [...registro.raizes].sort((a, b) => a.localeCompare(b, "pt-BR")),
+        }))
+            .sort((a, b) => a.caminho.localeCompare(b.caminho, "pt-BR"));
+    }
+    listarPorExtensoes(extensoes, raiz) {
+        return raiz ? this.listar(extensoes, [raiz]) : this.listar(extensoes);
+    }
+    listarPorRaiz(raiz, extensoes) {
+        return this.listar(extensoes, [raiz]);
+    }
+    arquivosCatalogados() {
+        return this.listar();
+    }
+    contem(caminho) {
+        return this.registros.has(chaveCaminho(path.resolve(this.baseDiretorio, caminho)));
+    }
+    ler(caminho) {
+        const absoluto = path.resolve(this.baseDiretorio, caminho);
+        const chave = chaveCaminho(absoluto);
+        const registro = this.registros.get(chave);
+        if (!registro) {
+            const descricao = caminhoEstaDentro(this.baseDiretorio, absoluto)
+                ? absoluto
+                : `[fora_do_workspace]/${path.basename(absoluto)}`;
+            return Promise.reject(new Error(`Arquivo fora do plano explicito do drift: ${descricao}`));
+        }
+        const existente = this.conteudos.get(registro);
+        if (existente) {
+            this.contadores.acertosMemoriaConteudo += 1;
+            return existente;
+        }
+        const leitura = this.lerFisicamente(registro);
+        this.conteudos.set(registro, leitura);
+        void leitura.catch(() => {
+            if (this.conteudos.get(registro) === leitura) {
+                this.conteudos.delete(registro);
+            }
+        });
+        return leitura;
+    }
+    async lerTexto(caminho) {
+        return (await this.ler(caminho)).texto;
+    }
+    async digest(caminho) {
+        return (await this.ler(caminho)).digest;
+    }
+    emitir(tipo, arquivo) {
+        emitirEvento(this.observador, {
+            tipo,
+            caminho: arquivo ? path.resolve(this.baseDiretorio, arquivo) : undefined,
+        });
+    }
+    metricas() {
+        return { ...this.contadores };
+    }
+    async caminharRaizes(diretoriosIgnorados) {
+        let nivel = [...this.raizes];
+        const visitados = new Set();
+        while (nivel.length > 0) {
+            const nivelUnico = [...new Map(nivel.map((diretorio) => [chaveCaminho(diretorio), diretorio])).values()]
+                .filter((diretorio) => {
+                const chave = chaveCaminho(diretorio);
+                if (visitados.has(chave)) {
+                    return false;
+                }
+                visitados.add(chave);
+                return true;
+            })
+                .sort((a, b) => a.localeCompare(b, "pt-BR"));
+            const proximos = await mapearComLimite(nivelUnico, this.concorrencia, async (diretorio) => this.visitarDiretorio(diretorio, diretoriosIgnorados));
+            nivel = proximos.flat();
+        }
+    }
+    async visitarDiretorio(diretorio, diretoriosIgnorados) {
+        if (!await this.caminhoPermaneceNoWorkspace(diretorio)) {
+            return [];
+        }
+        let informacao;
+        try {
+            informacao = await lstat(diretorio, { bigint: true });
+        }
+        catch (erro) {
+            if (erroEhAusencia(erro)) {
+                return [];
+            }
+            throw erro;
+        }
+        if (informacao.isSymbolicLink()) {
+            return [];
+        }
+        if (informacao.isFile()) {
+            const sondagem = await this.sondarArquivoSeguro(diretorio);
+            if (sondagem) {
+                this.adicionarArquivo(sondagem, false);
+            }
+            return [];
+        }
+        if (!informacao.isDirectory()) {
+            return [];
+        }
+        const entradas = await readdir(diretorio, { withFileTypes: true });
+        const informacaoDepois = await lstat(diretorio, { bigint: true });
+        if (!informacaoDepois.isDirectory()
+            || informacaoDepois.isSymbolicLink()
+            || !assinaturasDiretorioIguais(assinaturaDiretorio(informacao), assinaturaDiretorio(informacaoDepois))) {
+            throw new Error(`catalogo_diretorio_instavel:${diretorio}`);
+        }
+        this.contadores.diretoriosVisitados += 1;
+        emitirEvento(this.observador, {
+            tipo: "catalog.visit",
+            caminho: diretorio,
+            categoria: "diretorio",
+        });
+        const proximos = [];
+        const arquivos = [];
+        for (const entrada of entradas.sort((a, b) => a.name.localeCompare(b.name, "pt-BR"))) {
+            if (entrada.isSymbolicLink()) {
+                continue;
+            }
+            const caminhoAtual = path.join(diretorio, entrada.name);
+            if (entrada.isDirectory()) {
+                if (!diretoriosIgnorados.has(entrada.name.toLowerCase())) {
+                    proximos.push(caminhoAtual);
+                }
+            }
+            else if (entrada.isFile()) {
+                arquivos.push(caminhoAtual);
+            }
+        }
+        const sondagens = await mapearComLimite(arquivos, this.concorrencia, async (arquivo) => this.sondarArquivoSeguro(arquivo));
+        for (const sondagem of sondagens
+            .filter((item) => Boolean(item))
+            .sort((a, b) => a.caminho.localeCompare(b.caminho, "pt-BR"))) {
+            this.adicionarArquivo(sondagem, false);
+        }
+        return proximos;
+    }
+    adicionarArquivo(sondagem, explicito) {
+        const absoluto = path.resolve(sondagem.caminho);
+        const extensao = path.extname(absoluto).toLowerCase();
+        if (!explicito && this.extensoesPermitidas && !this.extensoesPermitidas.has(extensao)) {
+            return;
+        }
+        const chave = chaveCaminho(absoluto);
+        const chavesFisicas = chavesFisicasArquivo(sondagem.identidade);
+        const existentePorCaminho = this.registros.get(chave);
+        if (existentePorCaminho && !mesmoObjetoFisico(existentePorCaminho.identidade, sondagem.identidade)) {
+            throw new Error(`Arquivo catalogado mudou de identidade fisica: ${absoluto}`);
+        }
+        const existente = existentePorCaminho
+            ?? chavesFisicas.map((chaveFisica) => this.registrosFisicos.get(chaveFisica)).find(Boolean);
+        const raizes = this.raizes.filter((raiz) => caminhoEstaDentro(raiz, absoluto));
+        if (existente) {
+            existente.explicito = existente.explicito || explicito;
+            existente.aliases.add(absoluto);
+            this.registros.set(chave, existente);
+            for (const raiz of raizes) {
+                existente.raizes.add(raiz);
+            }
+            for (const chaveFisica of chavesFisicas) {
+                this.registrosFisicos.set(chaveFisica, existente);
+            }
+            if (absoluto.localeCompare(existente.caminho, "pt-BR") < 0) {
+                existente.caminho = absoluto;
+                existente.extensao = extensao;
+                existente.identidade = sondagem.identidade;
+            }
+            return;
+        }
+        const registro = {
+            caminho: absoluto,
+            extensao,
+            explicito,
+            raizes: new Set(raizes),
+            aliases: new Set([absoluto]),
+            identidade: sondagem.identidade,
+        };
+        this.registros.set(chave, registro);
+        for (const chaveFisica of chavesFisicas) {
+            this.registrosFisicos.set(chaveFisica, registro);
+        }
+        this.contadores.arquivosCatalogados += 1;
+        emitirEvento(this.observador, {
+            tipo: "catalog.visit",
+            caminho: absoluto,
+            categoria: "arquivo",
+        });
+    }
+    async sondarArquivoSeguro(caminho) {
+        const absoluto = path.resolve(caminho);
+        if (!caminhoEstaDentro(this.baseDiretorio, absoluto)) {
+            return undefined;
+        }
+        try {
+            const informacaoAntes = await lstat(absoluto, { bigint: true });
+            if (!informacaoAntes.isFile() || informacaoAntes.isSymbolicLink() || informacaoAntes.nlink !== 1n) {
+                return undefined;
+            }
+            const [baseReal, caminhoReal] = await Promise.all([
+                this.baseDiretorioReal,
+                realpath(absoluto),
+            ]);
+            const informacaoDepois = await lstat(absoluto, { bigint: true });
+            if (!caminhoEstaDentro(baseReal, caminhoReal)
+                || !identidadeArquivoEstavel(informacaoAntes, informacaoDepois)) {
+                return undefined;
+            }
+            return {
+                caminho: absoluto,
+                identidade: criarIdentidadeArquivoCatalogado(caminhoReal, informacaoDepois),
+            };
+        }
+        catch (erro) {
+            if (erroEhAusencia(erro)) {
+                return undefined;
+            }
+            throw erro;
+        }
+    }
+    async lerFisicamente(registro) {
+        const caminho = registro.caminho;
+        const informacaoAntes = await lstat(caminho, { bigint: true });
+        const [baseReal, caminhoRealAntes] = await Promise.all([
+            this.baseDiretorioReal,
+            realpath(caminho),
+        ]);
+        if (!caminhoEstaDentro(baseReal, caminhoRealAntes)
+            || !identidadeCatalogadaCorresponde(registro.identidade, caminhoRealAntes, informacaoAntes)) {
+            throw new Error(`Arquivo catalogado mudou entre catalogacao e primeira leitura: ${caminho}`);
+        }
+        const handle = await open(caminho, "r");
+        let bytes;
+        try {
+            const informacaoHandleAntes = await handle.stat({ bigint: true });
+            emitirEvento(this.observador, {
+                tipo: "content.open",
+                caminho,
+                categoria: "arquivo",
+            });
+            const [informacaoCaminhoAberto, caminhoRealAberto] = await Promise.all([
+                lstat(caminho, { bigint: true }),
+                realpath(caminho),
+            ]);
+            if (!caminhoEstaDentro(baseReal, caminhoRealAberto)
+                || !identidadeCatalogadaCorresponde(registro.identidade, caminhoRealAberto, informacaoCaminhoAberto)
+                || !identidadeArquivoEstavel(informacaoAntes, informacaoHandleAntes)
+                || !identidadeArquivoEstavel(informacaoHandleAntes, informacaoCaminhoAberto)) {
+                throw new Error(`Arquivo catalogado mudou durante abertura segura: ${caminho}`);
+            }
+            bytes = await handle.readFile();
+            const [informacaoHandleDepois, informacaoCaminhoDepois, caminhoRealDepois] = await Promise.all([
+                handle.stat({ bigint: true }),
+                lstat(caminho, { bigint: true }),
+                realpath(caminho),
+            ]);
+            if (!caminhoEstaDentro(baseReal, caminhoRealDepois)
+                || !identidadeCatalogadaCorresponde(registro.identidade, caminhoRealDepois, informacaoCaminhoDepois)
+                || !identidadeArquivoEstavel(informacaoHandleAntes, informacaoHandleDepois)
+                || !identidadeArquivoEstavel(informacaoHandleDepois, informacaoCaminhoDepois)) {
+                throw new Error(`Arquivo catalogado mudou durante leitura segura: ${caminho}`);
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        this.contadores.leiturasConteudo += 1;
+        this.contadores.bytesLidos += bytes.byteLength;
+        emitirEvento(this.observador, {
+            tipo: "content.read",
+            caminho,
+            categoria: "arquivo",
+            bytes: bytes.byteLength,
+            digest,
+        });
+        return {
+            caminho,
+            bytes,
+            texto: bytes.toString("utf8"),
+            digest,
+        };
+    }
+    async caminhoPermaneceNoWorkspace(caminho) {
+        const absoluto = path.resolve(caminho);
+        if (!caminhoEstaDentro(this.baseDiretorio, absoluto)) {
+            return false;
+        }
+        try {
+            const [baseReal, caminhoReal] = await Promise.all([
+                this.baseDiretorioReal,
+                realpath(absoluto),
+            ]);
+            return caminhoEstaDentro(baseReal, caminhoReal);
+        }
+        catch (erro) {
+            if (erroEhAusencia(erro)) {
+                return false;
+            }
+            throw erro;
+        }
+    }
+}
+export async function criarCatalogoDrift(opcoes) {
+    const ignoradosOrigem = opcoes.diretoriosIgnorados ?? [];
+    const ignorados = new Set([...ignoradosOrigem]
+        .map((diretorio) => diretorio.trim().toLowerCase())
+        .filter(Boolean));
+    const catalogo = new CatalogoDriftImplementacao(opcoes);
+    await catalogo.construir(opcoes.arquivos ?? [], ignorados);
+    return catalogo;
+}
+//# sourceMappingURL=driftCatalogo.js.map

package/dist/driftEscopo.d.ts

@@ -0,0 +1,21 @@
+import type { ContextoProjetoCarregado } from "./projeto.js";
+import type { ConfiguracaoEscopoDriftAplicada, EscopoDriftReal } from "./drift.part01.js";
+import type { CatalogoDrift } from "./driftCatalogo.js";
+export { extrairReferenciasLocaisDrift } from "./driftEscopoReferencias.js";
+export type EstrategiaEscopoDrift = "arquivos_vinculados" | "projeto";
+export type CoberturaEscopoDrift = "completa" | "parcial";
+export interface PlanoEscopoDrift {
+    escopo: EscopoDriftReal;
+    estrategia: EstrategiaEscopoDrift;
+    arquivos: string[];
+    arquivosDeclarados: string[];
+    arquivosInferidos: string[];
+    arquivosAusentes: string[];
+    diretorios: string[];
+    modulos: string[];
+    cobertura: CoberturaEscopoDrift;
+    bloqueios: string[];
+    dependencias: Record<string, string[]>;
+}
+export declare function planejarEscopoDrift(contexto: ContextoProjetoCarregado, configuracao: ConfiguracaoEscopoDriftAplicada): Promise<PlanoEscopoDrift>;
+export declare function expandirDependenciasPlanoDrift(contexto: ContextoProjetoCarregado, plano: PlanoEscopoDrift, catalogo: CatalogoDrift): Promise<PlanoEscopoDrift>;