@semacode/cli 2.3.0 → 2.3.1

package/dist/driftCatalogo.js

@@ -0,0 +1,657 @@
+// SEMA-GOVERNED: sema.produto.governanca_ia.drift
+// Descrição: cataloga somente o plano explícito do drift e compartilha leituras e fingerprints de conteúdo.
+import { createHash } from "node:crypto";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+export const SCHEMA_SNAPSHOT_CATALOGO_DRIFT = "sema.drift-catalog/v1";
+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(raiz, 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.toString(),
+        ctimeNs: info.ctimeNs.toString(),
+        dev: info.dev.toString(),
+        ino: info.ino.toString(),
+    };
+}
+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.dev === b.dev
+        && a.ino === b.ino
+        && a.size === b.size
+        && a.mtimeNs === b.mtimeNs
+        && a.ctimeNs === b.ctimeNs;
+}
+function registroObjeto(valor) {
+    return typeof valor === "object" && valor !== null && !Array.isArray(valor);
+}
+function caminhoRelativoSeguro(valor) {
+    return typeof valor === "string"
+        && valor.length > 0
+        && valor !== "."
+        && valor !== ".."
+        && !valor.startsWith("../")
+        && !valor.includes("\\")
+        && !path.posix.isAbsolute(valor);
+}
+function diretorioRelativoSeguro(valor) {
+    return valor === "." || caminhoRelativoSeguro(valor);
+}
+function assinaturaDiretorioValida(valor) {
+    return registroObjeto(valor)
+        && ["mtimeNs", "ctimeNs", "dev", "ino"]
+            .every((campo) => typeof valor[campo] === "string" && /^\d+$/u.test(valor[campo]));
+}
+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();
+    conteudos = new Map();
+    extensoesPermitidas;
+    concorrencia;
+    observador;
+    baseDiretorioReal;
+    extensoesSnapshot;
+    diretoriosVisitados = new Map();
+    diretoriosIgnoradosSnapshot = [];
+    contadores = {
+        diretoriosVisitados: 0,
+        arquivosCatalogados: 0,
+        leiturasConteudo: 0,
+        bytesLidos: 0,
+        acertosMemoriaConteudo: 0,
+        origem: "plano_explicito",
+        diretoriosValidadosCache: 0,
+    };
+    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))
+                .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.extensoesSnapshot = this.extensoesPermitidas
+            ? [...this.extensoesPermitidas].sort((a, b) => a.localeCompare(b, "en"))
+            : null;
+        this.concorrencia = normalizarConcorrencia(opcoes.concorrencia);
+        this.observador = opcoes.observador;
+    }
+    async construir(arquivosExplicitos, diretoriosIgnorados, snapshot) {
+        await this.baseDiretorioReal;
+        this.diretoriosIgnoradosSnapshot = [...diretoriosIgnorados]
+            .sort((a, b) => a.localeCompare(b, "en"));
+        const restaurado = snapshot
+            ? await this.restaurarSnapshot(snapshot, diretoriosIgnorados, arquivosExplicitos)
+            : false;
+        if (!restaurado) {
+            this.contadores.origem = this.raizes.length > 0 ? "caminhada" : "plano_explicito";
+            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"));
+        await mapearComLimite(explicitos, this.concorrencia, async (arquivo) => {
+            if (!await this.caminhoPermaneceNoWorkspace(arquivo)) {
+                return;
+            }
+            let informacao;
+            try {
+                informacao = await lstat(arquivo);
+            }
+            catch (erro) {
+                if (erroEhAusencia(erro)) {
+                    return;
+                }
+                throw erro;
+            }
+            if (!informacao.isFile() || informacao.isSymbolicLink()) {
+                return;
+            }
+            this.adicionarArquivo(arquivo, 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 this.listarEntradas({ extensoes })
+            .filter((arquivo) => raizesAbsolutas.some((raiz) => caminhoEstaDentro(raiz, arquivo.caminho)))
+            .map((arquivo) => arquivo.caminho);
+    }
+    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 [...this.registros.values()]
+            .filter((registro) => !extensoes || extensoes.has(registro.extensao))
+            .filter((registro) => !raiz || caminhoEstaDentro(raiz, registro.caminho))
+            .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) {
+            return Promise.reject(new Error(`Arquivo fora do plano explicito do drift: ${absoluto}`));
+        }
+        const existente = this.conteudos.get(chave);
+        if (existente) {
+            this.contadores.acertosMemoriaConteudo += 1;
+            return existente;
+        }
+        const leitura = this.lerFisicamente(registro.caminho);
+        this.conteudos.set(chave, leitura);
+        void leitura.catch(() => {
+            if (this.conteudos.get(chave) === leitura) {
+                this.conteudos.delete(chave);
+            }
+        });
+        return leitura;
+    }
+    async lerTexto(caminho) {
+        return (await this.ler(caminho)).texto;
+    }
+    async digest(caminho) {
+        return (await this.ler(caminho)).digest;
+    }
+    async fingerprint(caminhos) {
+        const selecionados = caminhos
+            ? [...new Map(caminhos.map((caminho) => {
+                    const absoluto = path.resolve(this.baseDiretorio, caminho);
+                    return [chaveCaminho(absoluto), absoluto];
+                })).values()]
+            : this.arquivosCatalogados();
+        selecionados.sort((a, b) => chaveCaminho(a).localeCompare(chaveCaminho(b), "en"));
+        const itens = await mapearComLimite(selecionados, this.concorrencia, async (arquivo) => ({
+            caminho: chaveCaminho(arquivo).replace(/\\/g, "/"),
+            digest: await this.digest(arquivo),
+        }));
+        return `sha256:${createHash("sha256").update(JSON.stringify(itens)).digest("hex")}`;
+    }
+    obterFingerprint(caminhos) {
+        return this.fingerprint(caminhos);
+    }
+    emitir(tipo, arquivo) {
+        emitirEvento(this.observador, {
+            tipo,
+            caminho: arquivo ? path.resolve(this.baseDiretorio, arquivo) : undefined,
+        });
+    }
+    metricas() {
+        return { ...this.contadores };
+    }
+    snapshot() {
+        return {
+            schema: SCHEMA_SNAPSHOT_CATALOGO_DRIFT,
+            raizes: this.raizes.map((raiz) => this.relativoSeguro(raiz, true)),
+            extensoes: this.extensoesSnapshot ? [...this.extensoesSnapshot] : null,
+            diretoriosIgnorados: [...this.diretoriosIgnoradosSnapshot],
+            diretorios: [...this.diretoriosVisitados.entries()]
+                .map(([caminho, assinatura]) => ({
+                caminho: this.relativoSeguro(caminho, true),
+                assinatura: { ...assinatura },
+            }))
+                .sort((a, b) => a.caminho.localeCompare(b.caminho, "en")),
+            arquivos: [...this.registros.values()]
+                .map((registro) => ({
+                caminho: this.relativoSeguro(registro.caminho),
+                explicito: registro.explicito,
+            }))
+                .sort((a, b) => a.caminho.localeCompare(b.caminho, "en")),
+        };
+    }
+    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()) {
+            this.adicionarArquivo(diretorio, false);
+            return [];
+        }
+        if (!informacao.isDirectory()) {
+            return [];
+        }
+        let entradas;
+        try {
+            entradas = await readdir(diretorio, { withFileTypes: true });
+        }
+        catch (erro) {
+            if (erroEhAusencia(erro)) {
+                return [];
+            }
+            throw erro;
+        }
+        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;
+        this.diretoriosVisitados.set(path.resolve(diretorio), assinaturaDiretorio(informacaoDepois));
+        emitirEvento(this.observador, {
+            tipo: "catalog.visit",
+            caminho: diretorio,
+            categoria: "diretorio",
+        });
+        const proximos = [];
+        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);
+                }
+                continue;
+            }
+            if (entrada.isFile()) {
+                this.adicionarArquivo(caminhoAtual, false);
+            }
+        }
+        return proximos;
+    }
+    adicionarArquivo(caminho, explicito, emitirVisita = true) {
+        const absoluto = path.resolve(caminho);
+        const extensao = path.extname(absoluto).toLowerCase();
+        if (this.extensoesPermitidas && !this.extensoesPermitidas.has(extensao)) {
+            return;
+        }
+        const chave = chaveCaminho(absoluto);
+        const existente = this.registros.get(chave);
+        const raizes = this.raizes.filter((raiz) => caminhoEstaDentro(raiz, absoluto));
+        if (existente) {
+            existente.explicito = existente.explicito || explicito;
+            for (const raiz of raizes) {
+                existente.raizes.add(raiz);
+            }
+            return;
+        }
+        this.registros.set(chave, {
+            caminho: absoluto,
+            extensao,
+            explicito,
+            raizes: new Set(raizes),
+        });
+        this.contadores.arquivosCatalogados += 1;
+        if (emitirVisita) {
+            emitirEvento(this.observador, {
+                tipo: "catalog.visit",
+                caminho: absoluto,
+                categoria: "arquivo",
+            });
+        }
+    }
+    async restaurarSnapshot(snapshot, diretoriosIgnorados, arquivosExplicitos) {
+        if (!registroObjeto(snapshot)
+            || snapshot.schema !== SCHEMA_SNAPSHOT_CATALOGO_DRIFT
+            || !Array.isArray(snapshot.raizes)
+            || !snapshot.raizes.every(diretorioRelativoSeguro)
+            || !Array.isArray(snapshot.diretoriosIgnorados)
+            || !snapshot.diretoriosIgnorados.every((item) => typeof item === "string")
+            || !(snapshot.extensoes === null
+                || (Array.isArray(snapshot.extensoes) && snapshot.extensoes.every((item) => typeof item === "string")))
+            || !Array.isArray(snapshot.diretorios)
+            || !Array.isArray(snapshot.arquivos)) {
+            return false;
+        }
+        const raizesAtuais = this.raizes.map((raiz) => this.relativoSeguro(raiz, true));
+        const ignoradosAtuais = [...diretoriosIgnorados].sort((a, b) => a.localeCompare(b, "en"));
+        if (JSON.stringify(snapshot.raizes) !== JSON.stringify(raizesAtuais)
+            || JSON.stringify(snapshot.extensoes) !== JSON.stringify(this.extensoesSnapshot)
+            || JSON.stringify(snapshot.diretoriosIgnorados) !== JSON.stringify(ignoradosAtuais)) {
+            return false;
+        }
+        const diretorios = snapshot.diretorios.map((entrada) => {
+            if (!registroObjeto(entrada)
+                || !diretorioRelativoSeguro(entrada.caminho)
+                || !assinaturaDiretorioValida(entrada.assinatura)) {
+                return undefined;
+            }
+            return {
+                caminho: path.resolve(this.baseDiretorio, entrada.caminho),
+                assinatura: entrada.assinatura,
+            };
+        });
+        if (diretorios.some((entrada) => !entrada)) {
+            return false;
+        }
+        if (diretorios.some((entrada) => entrada
+            && !this.caminhoPertenceRaizCatalogavel(entrada.caminho, diretoriosIgnorados, true))) {
+            return false;
+        }
+        const estadosDiretorios = await mapearComLimite(diretorios, this.concorrencia, async (entrada) => {
+            if (!await this.caminhoPermaneceNoWorkspace(entrada.caminho)) {
+                return false;
+            }
+            try {
+                const info = await lstat(entrada.caminho, { bigint: true });
+                this.contadores.diretoriosValidadosCache += 1;
+                return info.isDirectory()
+                    && !info.isSymbolicLink()
+                    && assinaturasDiretorioIguais(entrada.assinatura, assinaturaDiretorio(info));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (estadosDiretorios.some((valido) => !valido)) {
+            this.contadores.diretoriosValidadosCache = 0;
+            return false;
+        }
+        const arquivos = snapshot.arquivos.map((entrada) => {
+            if (!registroObjeto(entrada)
+                || !caminhoRelativoSeguro(entrada.caminho)
+                || typeof entrada.explicito !== "boolean") {
+                return undefined;
+            }
+            return {
+                caminho: path.resolve(this.baseDiretorio, entrada.caminho),
+                explicito: entrada.explicito,
+            };
+        });
+        if (arquivos.some((entrada) => !entrada)) {
+            return false;
+        }
+        const arquivosTipados = arquivos;
+        const explicitosPermitidos = new Set(arquivosExplicitos.map((arquivo) => chaveCaminho(path.resolve(this.baseDiretorio, arquivo))));
+        if (arquivosTipados.some((entrada) => entrada.explicito
+            ? !explicitosPermitidos.has(chaveCaminho(entrada.caminho))
+            : !this.caminhoPertenceRaizCatalogavel(entrada.caminho, diretoriosIgnorados))) {
+            return false;
+        }
+        const caminhosRepresentados = new Set([
+            ...diretorios
+                .filter((entrada) => Boolean(entrada))
+                .map((entrada) => chaveCaminho(entrada.caminho)),
+            ...arquivosTipados.map((entrada) => chaveCaminho(entrada.caminho)),
+        ]);
+        if (this.raizes.some((raiz) => !caminhosRepresentados.has(chaveCaminho(raiz)))) {
+            // Uma raiz ausente nao pode produzir um snapshot eterno: a criacao
+            // posterior dessa raiz precisa forcar uma nova caminhada.
+            return false;
+        }
+        const estadosArquivos = await mapearComLimite(arquivosTipados, this.concorrencia, async (entrada) => {
+            if (!caminhoEstaDentro(this.baseDiretorio, entrada.caminho)
+                || !await this.caminhoPermaneceNoWorkspace(entrada.caminho)) {
+                return false;
+            }
+            try {
+                const info = await lstat(entrada.caminho);
+                return info.isFile()
+                    && !info.isSymbolicLink()
+                    && (!this.extensoesPermitidas
+                        || this.extensoesPermitidas.has(path.extname(entrada.caminho).toLowerCase()));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (estadosArquivos.some((valido) => !valido)) {
+            return false;
+        }
+        const diretoriosTipados = diretorios;
+        const diretoriosAindaEstaveis = await mapearComLimite(diretoriosTipados, this.concorrencia, async (entrada) => {
+            try {
+                const info = await lstat(entrada.caminho, { bigint: true });
+                return info.isDirectory()
+                    && !info.isSymbolicLink()
+                    && assinaturasDiretorioIguais(entrada.assinatura, assinaturaDiretorio(info));
+            }
+            catch {
+                return false;
+            }
+        });
+        if (diretoriosAindaEstaveis.some((valido) => !valido)) {
+            return false;
+        }
+        for (const entrada of arquivosTipados) {
+            this.adicionarArquivo(entrada.caminho, entrada.explicito, false);
+        }
+        for (const entrada of diretoriosTipados) {
+            this.diretoriosVisitados.set(entrada.caminho, { ...entrada.assinatura });
+        }
+        this.contadores.origem = "snapshot";
+        return true;
+    }
+    relativoSeguro(caminho, permitirBase = false) {
+        const relativo = path.relative(this.baseDiretorio, path.resolve(caminho)).replace(/\\/g, "/");
+        if (!(permitirBase ? diretorioRelativoSeguro(relativo || ".") : caminhoRelativoSeguro(relativo))) {
+            throw new Error(`caminho_snapshot_catalogo_invalido:${caminho}`);
+        }
+        return relativo || ".";
+    }
+    caminhoPertenceRaizCatalogavel(caminho, diretoriosIgnorados, incluirUltimoSegmento = false) {
+        return this.raizes.some((raiz) => {
+            if (!caminhoEstaDentro(raiz, caminho)) {
+                return false;
+            }
+            const segmentos = path.relative(raiz, caminho)
+                .split(path.sep)
+                .filter(Boolean);
+            if (!incluirUltimoSegmento) {
+                segmentos.pop();
+            }
+            return segmentos.every((segmento) => !diretoriosIgnorados.has(segmento.toLowerCase()));
+        });
+    }
+    async lerFisicamente(caminho) {
+        if (!await this.caminhoPermaneceNoWorkspace(caminho)) {
+            throw new Error(`Arquivo catalogado saiu do workspace real: ${caminho}`);
+        }
+        const informacaoAntes = await lstat(caminho, { bigint: true });
+        if (!informacaoAntes.isFile() || informacaoAntes.isSymbolicLink()) {
+            throw new Error(`Arquivo catalogado deixou de ser arquivo regular: ${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),
+            ]);
+            const baseReal = await this.baseDiretorioReal;
+            if (!caminhoEstaDentro(baseReal, caminhoRealAberto)
+                || !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)
+                || !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, opcoes.snapshot);
+    return catalogo;
+}
+//# sourceMappingURL=driftCatalogo.js.map

package/dist/driftCatalogoPersistente.d.ts

@@ -0,0 +1,8 @@
+import { type PoliticaCacheDrift, type ValorJson } from "./driftCache.js";
+import { type CatalogoDrift, type OpcoesCatalogoDrift } from "./driftCatalogo.js";
+export declare const SCHEMA_CACHE_CATALOGO_DRIFT: "sema.drift-catalog-cache/v1";
+export interface OpcoesCatalogoPersistenteDrift {
+    politica: PoliticaCacheDrift;
+    identidade: ValorJson;
+}
+export declare function criarCatalogoPersistenteDrift(opcoes: OpcoesCatalogoDrift, opcoesCache: OpcoesCatalogoPersistenteDrift): Promise<CatalogoDrift>;