@semacode/cli 2.3.1 → 3.5.0

package/dist/driftCache.js

@@ -1,311 +0,0 @@
-// SEMA-GOVERNED: sema.produto.governanca_ia.drift
-// Descrição: persiste resultados agregados de indexação com chave por conteúdo e validação contra corrupção.
-import { createHash } from "node:crypto";
-import { lstat, readFile } from "node:fs/promises";
-import path from "node:path";
-import { escreverArquivoWorkspaceSeguro, validarDestinosEscritaWorkspace, } from "./workspaceWrite.js";
-export const SCHEMA_CACHE_DRIFT = "sema.drift-index-cache/v1";
-export const DIRETORIO_CACHE_DRIFT = path.join(".tmp", "sema-cache", "drift-index", "v1");
-const LIMITE_BYTES_PADRAO = 32 * 1024 * 1024;
-const PADRAO_DIGEST = /^sha256:[a-f0-9]{64}$/u;
-function emitirEvento(observador, evento) {
-    try {
-        observador?.(evento);
-    }
-    catch {
-        // Observabilidade nunca altera o resultado funcional do drift.
-    }
-}
-function normalizarPolitica(valor) {
-    return valor === "refresh" || valor === "off" ? valor : "auto";
-}
-function normalizarLimiteBytes(valor) {
-    if (!Number.isSafeInteger(valor) || valor <= 0) {
-        return LIMITE_BYTES_PADRAO;
-    }
-    return valor;
-}
-function falharJsonCanonico(motivo, caminho) {
-    throw new TypeError(`json_cache_drift_invalido:${motivo}:${caminho}`);
-}
-function serializarCanonico(valor, caminho, visitados) {
-    if (valor === null) {
-        return "null";
-    }
-    if (typeof valor === "string" || typeof valor === "boolean") {
-        return JSON.stringify(valor);
-    }
-    if (typeof valor === "number") {
-        if (!Number.isFinite(valor)) {
-            return falharJsonCanonico("numero_nao_finito", caminho);
-        }
-        return Object.is(valor, -0) ? "0" : JSON.stringify(valor);
-    }
-    if (typeof valor !== "object") {
-        return falharJsonCanonico(`tipo_${typeof valor}_nao_suportado`, caminho);
-    }
-    if (visitados.has(valor)) {
-        return falharJsonCanonico("referencia_ciclica", caminho);
-    }
-    visitados.add(valor);
-    try {
-        if (Array.isArray(valor)) {
-            const itens = [];
-            for (let indice = 0; indice < valor.length; indice += 1) {
-                if (!Object.hasOwn(valor, indice)) {
-                    falharJsonCanonico("array_esparso", `${caminho}[${indice}]`);
-                }
-                itens.push(serializarCanonico(valor[indice], `${caminho}[${indice}]`, visitados));
-            }
-            return `[${itens.join(",")}]`;
-        }
-        const prototipo = Object.getPrototypeOf(valor);
-        if (prototipo !== Object.prototype && prototipo !== null) {
-            return falharJsonCanonico("objeto_nao_plano", caminho);
-        }
-        const objeto = valor;
-        const campos = Object.keys(objeto)
-            .sort()
-            .map((chave) => (`${JSON.stringify(chave)}:${serializarCanonico(objeto[chave], `${caminho}.${chave}`, visitados)}`));
-        return `{${campos.join(",")}}`;
-    }
-    finally {
-        visitados.delete(valor);
-    }
-}
-export function serializarJsonCanonicoCacheDrift(valor) {
-    return serializarCanonico(valor, "$", new Set());
-}
-export function digestJsonCanonicoCacheDrift(valor) {
-    return `sha256:${createHash("sha256")
-        .update(serializarJsonCanonicoCacheDrift(valor))
-        .digest("hex")}`;
-}
-export function criarChaveCacheDrift(entrada) {
-    if (!entrada.fingerprintConteudo.trim()) {
-        throw new TypeError("fingerprint_conteudo_cache_drift_vazio");
-    }
-    return digestJsonCanonicoCacheDrift({
-        schema: SCHEMA_CACHE_DRIFT,
-        fingerprintConteudo: entrada.fingerprintConteudo,
-        identidade: entrada.identidade,
-    });
-}
-function nomeArquivoDaChave(chave) {
-    if (!PADRAO_DIGEST.test(chave)) {
-        throw new TypeError(`chave_cache_drift_invalida:${chave}`);
-    }
-    return `${chave.slice("sha256:".length)}.json`;
-}
-function registroObjeto(valor) {
-    return typeof valor === "object" && valor !== null && !Array.isArray(valor);
-}
-function erroEhAusencia(erro) {
-    return ["ENOENT", "ENOTDIR"].includes(erro.code ?? "");
-}
-class CacheDriftImplementacao {
-    baseProjeto;
-    politica;
-    limiteBytes;
-    observador;
-    emVoo = new Map();
-    contadores = {
-        hits: 0,
-        misses: 0,
-        corruptos: 0,
-        gravacoes: 0,
-        errosGravacao: 0,
-        calculosCompartilhados: 0,
-    };
-    constructor(opcoes) {
-        this.baseProjeto = path.resolve(opcoes.baseProjeto);
-        this.politica = normalizarPolitica(opcoes.politica);
-        this.limiteBytes = normalizarLimiteBytes(opcoes.limiteBytes);
-        this.observador = opcoes.observador;
-    }
-    chave(entrada) {
-        return criarChaveCacheDrift(entrada);
-    }
-    caminhoRelativo(chave) {
-        return path.join(DIRETORIO_CACHE_DRIFT, nomeArquivoDaChave(chave));
-    }
-    obterOuCalcular(entrada, calcular) {
-        const chave = this.chave(entrada);
-        const existente = this.emVoo.get(chave);
-        if (existente) {
-            this.contadores.calculosCompartilhados += 1;
-            return existente;
-        }
-        const execucao = this.executar(chave, calcular);
-        this.emVoo.set(chave, execucao);
-        const limpar = () => {
-            if (this.emVoo.get(chave) === execucao) {
-                this.emVoo.delete(chave);
-            }
-        };
-        void execucao.then(limpar, limpar);
-        return execucao;
-    }
-    metricas() {
-        return { ...this.contadores };
-    }
-    async executar(chave, calcular) {
-        const caminhoRelativo = this.caminhoRelativo(chave);
-        if (this.politica === "off") {
-            this.registrarMiss(chave, caminhoRelativo, "politica_off");
-            return {
-                chave,
-                valor: await calcular(),
-                origem: "calculado",
-                politica: this.politica,
-            };
-        }
-        if (this.politica === "auto") {
-            const leitura = await this.lerCache(chave, caminhoRelativo, true);
-            if (leitura.estado === "hit") {
-                return {
-                    chave,
-                    valor: leitura.payload,
-                    origem: "cache",
-                    politica: this.politica,
-                };
-            }
-        }
-        else {
-            this.registrarMiss(chave, caminhoRelativo, "politica_refresh");
-        }
-        const valor = await calcular();
-        await this.gravarCache(chave, caminhoRelativo, valor);
-        return {
-            chave,
-            valor,
-            origem: "calculado",
-            politica: this.politica,
-        };
-    }
-    async lerCache(chave, caminhoRelativo, registrarEventos) {
-        let caminhoAbsoluto = path.resolve(this.baseProjeto, caminhoRelativo);
-        try {
-            const [destino] = await validarDestinosEscritaWorkspace(this.baseProjeto, [caminhoRelativo]);
-            caminhoAbsoluto = destino.caminhoAbsoluto;
-            if (!destino.existe) {
-                if (registrarEventos) {
-                    this.registrarMiss(chave, caminhoRelativo, "arquivo_ausente");
-                }
-                return { estado: "miss" };
-            }
-            const informacao = await lstat(caminhoAbsoluto);
-            if (!informacao.isFile() || informacao.isSymbolicLink()) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "nao_eh_arquivo_regular", registrarEventos);
-            }
-            if (informacao.size > this.limiteBytes) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "limite_bytes_excedido", registrarEventos);
-            }
-            const bytes = await readFile(caminhoAbsoluto);
-            if (bytes.byteLength > this.limiteBytes) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "limite_bytes_excedido_apos_leitura", registrarEventos);
-            }
-            let bruto;
-            try {
-                bruto = JSON.parse(bytes.toString("utf8"));
-            }
-            catch {
-                return this.registrarCorrupto(chave, caminhoRelativo, "json_invalido", registrarEventos);
-            }
-            if (!registroObjeto(bruto)) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "envelope_invalido", registrarEventos);
-            }
-            if (bruto.schema !== SCHEMA_CACHE_DRIFT || bruto.key !== chave) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "schema_ou_chave_divergente", registrarEventos);
-            }
-            if (typeof bruto.payloadDigest !== "string" || !PADRAO_DIGEST.test(bruto.payloadDigest)) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "payload_digest_invalido", registrarEventos);
-            }
-            let digestCalculado;
-            try {
-                digestCalculado = digestJsonCanonicoCacheDrift(bruto.payload);
-            }
-            catch {
-                return this.registrarCorrupto(chave, caminhoRelativo, "payload_nao_canonico", registrarEventos);
-            }
-            if (digestCalculado !== bruto.payloadDigest) {
-                return this.registrarCorrupto(chave, caminhoRelativo, "payload_digest_divergente", registrarEventos);
-            }
-            if (registrarEventos) {
-                this.contadores.hits += 1;
-                emitirEvento(this.observador, {
-                    tipo: "cache.hit",
-                    chave,
-                    caminho: caminhoAbsoluto,
-                });
-            }
-            return { estado: "hit", payload: bruto.payload };
-        }
-        catch (erro) {
-            if (registrarEventos) {
-                this.registrarMiss(chave, caminhoRelativo, erroEhAusencia(erro) ? "arquivo_ausente" : "cache_indisponivel");
-            }
-            return { estado: "miss" };
-        }
-    }
-    registrarCorrupto(chave, caminhoRelativo, motivo, registrarEventos) {
-        if (registrarEventos) {
-            this.contadores.misses += 1;
-            this.contadores.corruptos += 1;
-            emitirEvento(this.observador, {
-                tipo: "cache.corrupt",
-                chave,
-                caminho: path.resolve(this.baseProjeto, caminhoRelativo),
-                motivo,
-            });
-        }
-        return { estado: "corrupt" };
-    }
-    registrarMiss(chave, caminhoRelativo, motivo) {
-        this.contadores.misses += 1;
-        emitirEvento(this.observador, {
-            tipo: "cache.miss",
-            chave,
-            caminho: path.resolve(this.baseProjeto, caminhoRelativo),
-            motivo,
-        });
-    }
-    async gravarCache(chave, caminhoRelativo, payload) {
-        let envelope;
-        let conteudo;
-        try {
-            envelope = {
-                schema: SCHEMA_CACHE_DRIFT,
-                key: chave,
-                payload,
-                payloadDigest: digestJsonCanonicoCacheDrift(payload),
-            };
-            conteudo = JSON.stringify(envelope);
-            if (Buffer.byteLength(conteudo, "utf8") > this.limiteBytes) {
-                this.contadores.errosGravacao += 1;
-                return;
-            }
-        }
-        catch {
-            // Resultado não serializável continua válido; apenas não é cacheado.
-            this.contadores.errosGravacao += 1;
-            return;
-        }
-        try {
-            await escreverArquivoWorkspaceSeguro(this.baseProjeto, caminhoRelativo, conteudo, { sobrescrever: true });
-            this.contadores.gravacoes += 1;
-        }
-        catch {
-            // Outra execução pode ter publicado a mesma chave. Um vencedor válido
-            // encerra a corrida; qualquer outra falha permanece apenas perda de cache.
-            const vencedor = await this.lerCache(chave, caminhoRelativo, false);
-            if (vencedor.estado !== "hit") {
-                this.contadores.errosGravacao += 1;
-            }
-        }
-    }
-}
-export function criarCacheDrift(opcoes) {
-    return new CacheDriftImplementacao(opcoes);
-}
-//# sourceMappingURL=driftCache.js.map

package/dist/driftCacheIncremental.d.ts

@@ -1,98 +0,0 @@
-import type { ConteudoArquivoDrift, ObservadorOperacaoDrift } from "./driftCatalogo.js";
-import { type PoliticaCacheDrift, type ValorJson } from "./driftCache.js";
-export declare const FILE_INDEX_SCHEMA: 2;
-export declare const SCHEMA_MANIFESTO_ARQUIVOS_DRIFT: "sema.drift-file-cache/v2";
-export declare const SCHEMA_GRUPO_INDICE_DRIFT: "sema.drift-index-group-cache/v2";
-export declare const DIRETORIO_CACHE_INCREMENTAL_DRIFT: string;
-export declare const DIRETORIO_IDENTIDADES_CACHE_INCREMENTAL_DRIFT: string;
-export declare function caminhoManifestoArquivosDrift(identidadeDigest: string): string;
-export declare function caminhoManifestoGruposDrift(identidadeDigest: string): string;
-export interface AssinaturaArquivoDrift {
-    size: string;
-    mtimeNs: string;
-    ctimeNs: string;
-    dev: string;
-    ino: string;
-}
-export interface EstadoArquivoCacheDrift<T> {
-    caminho: string;
-    contentHash: string;
-    valor: T;
-    origem: "metadata_hit" | "content_hit" | "calculado";
-}
-export interface EstadoGrupoCacheDrift<T> {
-    chave: string;
-    valor: T;
-    origem: "cache" | "calculado";
-}
-export interface MetricasCacheIncrementalDrift {
-    metadataHits: number;
-    contentHits: number;
-    fileMisses: number;
-    groupHits: number;
-    groupMisses: number;
-    corruptos: number;
-    extracoesArquivo: number;
-    extracoesGrupo: number;
-    gravacoes: number;
-    errosGravacao: number;
-}
-export interface OpcoesCacheIncrementalDrift {
-    baseProjeto: string;
-    politica: PoliticaCacheDrift;
-    identidade: ValorJson;
-    observador?: ObservadorOperacaoDrift;
-}
-export interface ResolverArquivoCacheDrift<T> {
-    arquivo: string;
-    analise: string;
-    assinar?: () => Promise<AssinaturaArquivoDrift>;
-    ler: () => Promise<ConteudoArquivoDrift>;
-    extrair: (conteudo: ConteudoArquivoDrift) => Promise<T> | T;
-    validar: (valor: unknown) => valor is T;
-}
-export interface ResolverGrupoCacheDrift<T> {
-    membros: Array<{
-        caminho: string;
-        contentHash: string;
-    }>;
-    calcular: () => Promise<T>;
-    validar: (valor: unknown) => valor is T;
-}
-export declare function obterAssinaturaArquivoDrift(arquivo: string): Promise<AssinaturaArquivoDrift>;
-export declare class CacheIncrementalDrift {
-    readonly identidadeDigest: string;
-    readonly politica: PoliticaCacheDrift;
-    private readonly baseProjeto;
-    private readonly baseProjetoReal;
-    private readonly observador?;
-    private readonly caminhoManifestoArquivos;
-    private readonly caminhoManifestoGrupos;
-    private manifesto?;
-    private manifestoEmVoo?;
-    private manifestoSujo;
-    private readonly arquivosSujos;
-    private manifestoGrupos?;
-    private manifestoGruposEmVoo?;
-    private manifestoGruposSujo;
-    private readonly gruposSujos;
-    private readonly arquivosEmVoo;
-    private readonly metricasAtuais;
-    constructor(opcoes: OpcoesCacheIncrementalDrift);
-    metricas(): MetricasCacheIncrementalDrift;
-    resolverArquivo<T>(opcoes: ResolverArquivoCacheDrift<T>): Promise<EstadoArquivoCacheDrift<T>>;
-    private resolverArquivoInterno;
-    resolverGrupo<T>(opcoes: ResolverGrupoCacheDrift<T>): Promise<EstadoGrupoCacheDrift<T>>;
-    finalizar(): Promise<void>;
-    private chaveEnvelope;
-    private lerManifestoArquivosAtual;
-    private lerManifestoGruposAtual;
-    private gravarManifestoArquivosComMerge;
-    private gravarManifestoGruposComMerge;
-    private obterManifesto;
-    private carregarManifesto;
-    private obterManifestoGrupos;
-    private carregarManifestoGrupos;
-    private registrarCorrupto;
-    private validarArquivoNoWorkspace;
-}