/* * This file is part of NFeWizard-io. * * NFeWizard-io is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * NFeWizard-io is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with NFeWizard-io. If not, see . */ import libxmljs from 'libxmljs2'; import xsdAssembler from 'xsd-assembler'; import xsdValidator from 'xsd-schema-validator'; import { getSchema } from '../adapters/SchemaLoader.js'; import type { Environment } from '../environment/Environment.js'; /** Estratégias de validação de schema disponíveis. */ export type SchemaValidator = 'validateSchemaJsBased' | 'validateSchemaJavaBased'; /** * Nomes de métodos/operações fiscais aceitos pela validação de schema. * Devem corresponder às chaves mapeadas em `SchemaLoader.getSchema`. */ export type SchemaValidateMethod = | 'NFEStatusServico' | 'NFEConsultaProtocolo' | 'RecepcaoEvento' | 'NFeDistribuicaoDFe' | 'NFEAutorizacao' | 'NFeAutorizacao' | 'NFEInutilizacao' | 'NFERetAutorizacao' | 'CTeDistribuicaoDFe' | 'DCEAutorizacao' | 'DCEAutorizacaoZip' | 'DCEStatusServico' | 'DCEConsultaProtocolo' | 'DCERecepcaoEvento' | 'DCECancelamento' | 'DCEDistribuicao' | 'DCEDistribuicaoAut' | 'NFSe_Autorizacao' | 'NFSe_Consulta' | 'NFSe_Distribuicao' | 'NFSe_Eventos' | 'NFSe_ParametrosMunicipais'; /** * Erro individual de validação de schema, já com mensagem original e versão humanizada. */ export interface SchemaValidationIssue { /** Mensagem original retornada pelo parser/validador (libxmljs ou xsd-schema-validator). */ raw: string; /** Versão amigável da mensagem, em português, sem namespaces. */ humanized: string; /** Elemento XML envolvido (quando identificável). Ex.: `NFe`, `infNFe`, `ide`. */ element?: string; /** Atributo envolvido (quando o erro for em atributo). */ attribute?: string; /** Filhos/valores esperados extraídos da mensagem (quando aplicável). */ expected?: string[]; /** Linha do XML reportada pelo validador. */ line?: number; /** Coluna do XML reportada pelo validador. */ column?: number; } /** * Resultado completo da validação. Compatível com o retorno anterior * (`{ success, message }`) e expandido com campos adicionais. */ export interface SchemaValidationResult { success: boolean; /** Mensagem-resumo (humanizada). Em sucesso: `'XML válido.'`. */ message: string; /** Lista de todos os erros de schema encontrados. Vazia em sucesso. */ errors: SchemaValidationIssue[]; /** Relatório multilinha pronto para `console.log`, no estilo do validador SEFAZ-RS. */ report: string; /** Linhas estruturadas para `console.table(result.tableRows)`. */ tableRows: Array<{ '#': number; Linha: number | ''; Elemento: string; Mensagem: string }>; /** Método/schema utilizado na validação. */ metodo: SchemaValidateMethod; /** Nome do arquivo XSD aplicado. */ schema: string; } export interface NFESchemaValidateOptions { /** * Qual validador utilizar. * * - `'validateSchemaJsBased'` — usa `libxmljs2` + `xsd-assembler` (sem JDK). * - `'validateSchemaJavaBased'` — usa `xsd-schema-validator` (requer JDK). * * Quando não informado, lê `lib.useForSchemaValidation` da configuração da lib * (via `environment`); se nenhum dos dois estiver definido, aplica * `'validateSchemaJsBased'` como padrão. */ validator?: SchemaValidator; /** * Instância do `Environment` inicializada pela lib. Usada apenas para ler * `lib.useForSchemaValidation` quando `validator` não for informado * explicitamente. */ environment?: Environment; } /** Remove o prefixo `{namespace}` deixando apenas o nome local do elemento. */ function stripNamespace(name: string): string { return name.replace(/^\{[^}]*\}/, ''); } /** * Interpreta uma mensagem de erro do libxmljs2 / xsd-schema-validator e retorna * um `SchemaValidationIssue` com versão humanizada + metadados estruturados. */ function humanizeIssue(raw: string, line?: number, column?: number): SchemaValidationIssue { const issue: SchemaValidationIssue = { raw, humanized: raw, line, column }; // 1) Elemento com filhos ausentes // Element '{ns}Nome': Missing child element(s). Expected is one of ( {ns}a, {ns}b ). let m = raw.match(/Element\s+'([^']+)':\s*Missing child element\(s\)\.\s*Expected is one of\s*\(\s*([^)]+)\s*\)\.?/i); if (m) { const element = stripNamespace(m[1]); const expected = m[2].split(',').map((s) => stripNamespace(s.trim())).filter(Boolean); issue.element = element; issue.expected = expected; issue.humanized = `Elemento <${element}> está incompleto. Filho ausente, esperado um de: ${expected.join(', ')}.`; return issue; } // 2) Elemento não esperado // Element '{ns}Nome': This element is not expected. Expected is one of ( {ns}a, {ns}b ). m = raw.match(/Element\s+'([^']+)':\s*This element is not expected\.\s*(?:Expected is one of\s*\(\s*([^)]+)\s*\)\.?)?/i); if (m) { const element = stripNamespace(m[1]); issue.element = element; if (m[2]) { issue.expected = m[2].split(',').map((s) => stripNamespace(s.trim())).filter(Boolean); issue.humanized = `Elemento <${element}> inesperado nesta posição. Esperado um de: ${issue.expected.join(', ')}.`; } else { issue.humanized = `Elemento <${element}> inesperado nesta posição.`; } return issue; } // 3) Atributo inválido / faltando // Element '{ns}Nome', attribute 'attr': ... m = raw.match(/Element\s+'([^']+)',\s*attribute\s+'([^']+)':\s*(.+?)\.?$/i); if (m) { const element = stripNamespace(m[1]); const attribute = m[2]; const desc = m[3]; issue.element = element; issue.attribute = attribute; issue.humanized = `Elemento <${element}> — atributo "${attribute}": ${desc}.`; return issue; } // 4) Valor inválido para tipo // Element '{ns}Nome': [facet 'pattern'] The value '...' is not accepted by the pattern '...'. // Element '{ns}Nome': '...' is not a valid value of the atomic type 'TString'. m = raw.match(/Element\s+'([^']+)':\s*(?:\[facet[^\]]*\]\s*)?(.+?)\.?$/i); if (m) { const element = stripNamespace(m[1]); issue.element = element; issue.humanized = `Elemento <${element}>: ${m[2]}.`; return issue; } // 5) Sem padrão reconhecido — devolve raw como humanizado return issue; } /** Cria um issue "interno" quando o erro não veio do schema (ex.: XML mal formado). */ function internalIssue(raw: string): SchemaValidationIssue { return { raw, humanized: raw }; } /** * Monta o relatório textual estilo SEFAZ-RS pronto para `console.log`. */ function buildReport(metodo: SchemaValidateMethod, schemaFile: string, errors: SchemaValidationIssue[]): string { const linhas: string[] = []; linhas.push('=== Resultado da Validação do Schema ==='); linhas.push(`Tipo de Mensagem: ${metodo}`); linhas.push(`Schema XML: ${schemaFile}`); if (errors.length === 0) { linhas.push('Parser XML: Nenhum erro encontrado'); linhas.push('Schema XML: Nenhum erro encontrado'); linhas.push('Status: XML válido.'); } else { linhas.push(`Status: ${errors.length} erro(s) de validação`); linhas.push(''); errors.forEach((err, idx) => { const pos = err.line ? ` (linha ${err.line}${err.column ? `, col ${err.column}` : ''})` : ''; linhas.push(` ${idx + 1}. ${err.humanized}${pos}`); }); } linhas.push('========================================='); return linhas.join('\n'); } /** Converte a lista de erros em linhas para `console.table`. */ function buildTableRows(errors: SchemaValidationIssue[]): SchemaValidationResult['tableRows'] { if (errors.length === 0) { return [{ '#': 1, Linha: '', Elemento: '-', Mensagem: 'XML válido.' }]; } return errors.map((err, idx) => ({ '#': idx + 1, Linha: err.line ?? '', Elemento: err.element ?? '-', Mensagem: err.humanized, })); } function schemaFileName(schemaPath: string): string { if (!schemaPath) return '-'; const parts = schemaPath.split(/[\\/]/); return parts[parts.length - 1] || schemaPath; } function makeResult( success: boolean, metodo: SchemaValidateMethod, schemaPath: string, errors: SchemaValidationIssue[], ): SchemaValidationResult { const schema = schemaFileName(schemaPath); const report = buildReport(metodo, schema, errors); const message = success ? 'XML válido.' : errors[0]?.humanized ?? 'Erro de validação não identificado.'; return { success, message, errors, report, tableRows: buildTableRows(errors), metodo, schema, }; } function runJsBased(xml: string, metodo: SchemaValidateMethod): Promise { return new Promise(async (resolve, reject) => { const { basePath, schemaPath } = getSchema(metodo); if (!schemaPath) { reject(makeResult(false, metodo, '', [internalIssue( `Schema XSD não encontrado para o método '${metodo}'. Verifique se o nome do método está correto.`, )])); return; } try { const completeXSD = await xsdAssembler.assemble(schemaPath); const xmlDoc = libxmljs.parseXml(xml); const xsdDoc = libxmljs.parseXml(completeXSD, { baseUrl: `${basePath}/` }); const isValid = xmlDoc.validate(xsdDoc); if (isValid) { resolve(makeResult(true, metodo, schemaPath, [])); return; } const errors: SchemaValidationIssue[] = (xmlDoc.validationErrors || []).map((e: any) => humanizeIssue(String(e.message ?? e).trim(), e.line, e.column), ); reject(makeResult(false, metodo, schemaPath, errors.length ? errors : [internalIssue('XML inválido (sem detalhes do validador).')])); } catch (error: any) { reject(makeResult(false, metodo, schemaPath, [internalIssue(String(error?.message ?? error))])); } }); } function runJavaBased(xml: string, metodo: SchemaValidateMethod): Promise { return new Promise((resolve, reject) => { const { schemaPath } = getSchema(metodo); if (!schemaPath) { reject(makeResult(false, metodo, '', [internalIssue( `Schema XSD não encontrado para o método '${metodo}'. Verifique se o nome do método está correto.`, )])); return; } try { xsdValidator.validateXML(xml, schemaPath, (err: any, validationResult: any) => { if (err) { reject(makeResult(false, metodo, schemaPath, [humanizeIssue(String(err.message ?? err))])); return; } if (!validationResult?.valid) { const msgs: string[] = validationResult?.messages ?? []; const errors = msgs.length ? msgs.map((m) => humanizeIssue(String(m))) : [internalIssue('XML inválido (sem detalhes do validador).')]; reject(makeResult(false, metodo, schemaPath, errors)); return; } resolve(makeResult(true, metodo, schemaPath, [])); }); } catch (error: any) { reject(makeResult(false, metodo, schemaPath, [internalIssue(String(error?.message ?? error))])); } }); } /** * Valida um XML contra o schema XSD correspondente ao método fiscal informado. * * ### Seleção do validador (ordem de prioridade) * 1. `options.validator` — escolha explícita do caller. * 2. `options.environment.getConfig().lib?.useForSchemaValidation` — valor definido * na inicialização da lib. * 3. `'validateSchemaJsBased'` — padrão (sem JDK). * * @param xml - String XML a ser validada. * @param metodo - Nome do método/operação fiscal (ex.: `'NFeAutorizacao'`). * @param options - Opções opcionais: `validator` e/ou `environment`. * * @example * // Sem opções: usa validateSchemaJsBased * await NFE_SchemaValidate(xml, 'NFeAutorizacao'); * * @example * // Passando o environment inicializado pela lib (lê useForSchemaValidation do config) * await NFE_SchemaValidate(xml, 'NFeAutorizacao', { environment }); * * @example * // Forçando um validador específico * await NFE_SchemaValidate(xml, 'NFeAutorizacao', { validator: 'validateSchemaJavaBased' }); */ export function NFE_SchemaValidate( xml: string, metodo: SchemaValidateMethod, options?: NFESchemaValidateOptions, ): Promise { let chosen: SchemaValidator = 'validateSchemaJsBased'; if (options?.validator) { chosen = options.validator; } else if (options?.environment) { const fromConfig = options.environment.getConfig()?.lib?.useForSchemaValidation; if (fromConfig) chosen = fromConfig; } const xmlNormalizado = wrapEnviNFeIfNeeded(xml, metodo); return chosen === 'validateSchemaJavaBased' ? runJavaBased(xmlNormalizado, metodo) : runJsBased(xmlNormalizado, metodo); } /** * Para os métodos de autorização de NF-e, o schema XSD (`enviNFe_v4.00.xsd`) * exige que o elemento raiz seja ``. Quando o caller passa apenas a * árvore ``, envelopamos automaticamente em `` com `idLote=1` e * `indSinc=1` para que a validação funcione. */ function wrapEnviNFeIfNeeded(xml: string, metodo: SchemaValidateMethod): string { if (metodo !== 'NFEAutorizacao' && metodo !== 'NFeAutorizacao') return xml; const semDecl = xml.replace(/^\s*<\?xml[^?]*\?>\s*/, '').trimStart(); if (/^]/.test(semDecl)) { return `11${semDecl}`; } return xml; }