@semacode/cli 2.2.0 → 2.3.1

package/dist/driftCache.d.ts

@@ -0,0 +1,49 @@
+import type { ObservadorOperacaoDrift } from "./driftCatalogo.js";
+export declare const SCHEMA_CACHE_DRIFT: "sema.drift-index-cache/v1";
+export declare const DIRETORIO_CACHE_DRIFT: string;
+export type PoliticaCacheDrift = "auto" | "refresh" | "off";
+export type ValorJson = null | boolean | number | string | ValorJson[] | {
+    [chave: string]: ValorJson;
+};
+export interface EntradaCacheAgregadoDrift {
+    fingerprintConteudo: string;
+    identidade: ValorJson;
+}
+export interface EnvelopeCacheDrift<T> {
+    schema: typeof SCHEMA_CACHE_DRIFT;
+    key: string;
+    payload: T;
+    payloadDigest: string;
+}
+export interface ResultadoCacheAgregadoDrift<T> {
+    chave: string;
+    valor: T;
+    origem: "cache" | "calculado";
+    politica: PoliticaCacheDrift;
+}
+export interface MetricasCacheDrift {
+    hits: number;
+    misses: number;
+    corruptos: number;
+    gravacoes: number;
+    errosGravacao: number;
+    calculosCompartilhados: number;
+}
+export interface OpcoesCacheDrift {
+    baseProjeto: string;
+    politica?: PoliticaCacheDrift;
+    limiteBytes?: number;
+    observador?: ObservadorOperacaoDrift;
+}
+export interface CacheDrift {
+    readonly baseProjeto: string;
+    readonly politica: PoliticaCacheDrift;
+    chave(entrada: EntradaCacheAgregadoDrift): string;
+    caminhoRelativo(chave: string): string;
+    obterOuCalcular<T>(entrada: EntradaCacheAgregadoDrift, calcular: () => Promise<T>): Promise<ResultadoCacheAgregadoDrift<T>>;
+    metricas(): MetricasCacheDrift;
+}
+export declare function serializarJsonCanonicoCacheDrift(valor: unknown): string;
+export declare function digestJsonCanonicoCacheDrift(valor: unknown): string;
+export declare function criarChaveCacheDrift(entrada: EntradaCacheAgregadoDrift): string;
+export declare function criarCacheDrift(opcoes: OpcoesCacheDrift): CacheDrift;

package/dist/driftCache.js

@@ -0,0 +1,311 @@
+// 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

@@ -0,0 +1,98 @@
+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;
+}