# Documentacion por archivo
Este documento lista los archivos principales del repositorio y explica que
feature implementa cada uno.
## Crate runtime
| `Cargo.toml` | Package | Define package `xdoc-rs`, lib `xdoc`, workspace auxiliar y dependencias publicables. |
| `src/lib.rs` | Entrada | Declara los modulos publicos del motor y mantiene la crate como una sola libreria generica. |
## Core
| `src/core/mod.rs` | Core | Reexporta errores, nombres, namespaces y arbol para `xdoc::core`. |
| `src/core/error.rs` | Core/errors | Define `XmlResult<T>`, `XmlError`, `ErrorKind` y `Span`. |
| `src/core/names.rs` | Core/names | Define `QName`, `NamespaceUri`, `NamespacePrefix`, constantes XML y validacion de nombres/namespaces. |
| `src/core/namespace.rs` | Core/namespaces | Define `NamespaceDeclaration` y `NamespaceTable` con orden deterministico. |
| `src/core/tree.rs` | Core/tree | Define `Document`, `NodeId`, `Node`, `NodeKind`, `ElementData`, `Attribute` y `XmlPath`. |
## Construccion declarativa
| `src/builder/mod.rs` | Builder | Implementa `DocumentBuilder`, `ElementBuilder`, `FragmentBuilder`, `XmlNode`, `IntoXmlFragment`, `element`, `text` y `fragment`. |
| `src/component/mod.rs` | Component | Implementa `Children`, `IntoXml`, `document`, `children` y reexports para componentes Rust. |
| `src/macros/mod.rs` | Macro | Reexporta `xml!` y define `XmlTemplate`, puente runtime entre proc-macro, builder y document. |
## Writer y parser
| `src/writer/mod.rs` | Writer | Serializa `Document` con `to_string_compact`, `to_string_pretty`, `to_string_with_config`, escape de texto/atributos y `WriterConfig`. |
| `src/parser/mod.rs` | Parser | Lee XML hacia `Document`, aplica `ParserConfig`, respeta limites y rechaza DTD/entidades externas por defecto. |
## Query, transform y schema
| `src/query/mod.rs` | Query | Implementa subset tipo XPath: `Query`, `QueryResult`, `QueryValue`, `NamespaceContext` y `DocumentQueryExt`. |
| `src/transform/mod.rs` | Transform | Implementa templates programaticos XML a XML: `Transform`, `Template`, `ElementTemplate`, `BindingContext` y `TransformConfig`. |
| `src/schema/mod.rs` | Schema | Implementa contratos propios: `XmlContract`, `ValueType`, `ValidationReport`, `ValidationIssue`, `ValidationSeverity` y `XsdContractAdapter`. |
| `src/security/mod.rs` | Security | Define `SecurityLimits`, `EntityPolicy`, `ParserSecurityConfig`, `QuerySecurityConfig` y `TransformSecurityConfig`. |
## Signature
| `src/signature/mod.rs` | Signature | Reexporta la API publica de canonicalizacion, digest, XMLDSig, XAdES, providers y validacion. |
| `src/signature/algorithms.rs` | Signature/algorithms | Define `CanonicalizationAlgorithm`, `DigestAlgorithm`, `SignatureAlgorithm` y URIs XMLDSig/XAdES. |
| `src/signature/base64.rs` | Signature/base64 | Encapsula encode/decode base64 estandar con errores `XmlError`. |
| `src/signature/digest.rs` | Signature/digest | Calcula digest binario y base64 con `digest_bytes` y `digest_base64`. |
| `src/signature/ids.rs` | Signature/ids | Resuelve IDs, politicas de atributos ID y unicidad con `find_element_by_id` y `ensure_unique_ids`. |
| `src/signature/canonicalization.rs` | Signature/c14n | Canonicaliza documentos o nodos con C14N 1.0/1.1 inclusivo sin comentarios. |
| `src/signature/xmldsig.rs` | Signature/XMLDSig | Firma/verifica XMLDSig enveloped, referencias configurables, placement, `SignedInfo`, `Reference`, `KeyInfo` y reportes. |
| `src/signature/xades.rs` | Signature/XAdES | Construye/verifica XAdES BES, EPES y Baseline-B generico sobre XMLDSig. |
| `src/signature/profiles.rs` | Signature/XAdES | Define `XadesProfile` y `SigningCertificateMode`. |
| `src/signature/policy.rs` | Signature/policy | Modela `SignaturePolicy`, `SignaturePolicyId`, qualifiers y roles de firmante. |
| `src/signature/key.rs` | Signature/keys | Define `SigningProvider`, provider RSA-SHA256, credenciales PFX, metadatos de certificado y provider deterministico. |
| `src/signature/timestamp.rs` | Signature/timestamp | Define cliente TSA abstracto, timestamp deterministico, `XadesTimestampConfig` y operaciones de `SignatureTimeStamp`. |
| `src/signature/validation_data.rs` | Signature/validation data | Inserta/verifica `CertificateValues` y `RevocationValues` con provider de material externo. |
| `src/signature/archive.rs` | Signature/archive | Inserta/verifica `ArchiveTimeStamp` generico para flujos LTA-like. |
| `src/signature/validation_profile.rs` | Signature/profile validation | Valida requisitos estructurales/criptograficos parametrizados con `SignatureValidationProfile`. |
| `src/signature/signer.rs` | Signature/high-level | Implementa `XadesSigner`, `XadesSigningOptions`, `XadesSignedDocument` y reporte de firma. |
| `src/signature/verifier.rs` | Signature/high-level | Implementa `XadesVerifier` para verificacion XAdES con provider/config. |
## Proc-macro `xdoc-macros`
| `crates/xdoc-macros/Cargo.toml` | Macro crate | Define la crate proc-macro auxiliar permitida para `xml!`. |
| `crates/xdoc-macros/src/lib.rs` | Macro entry | Expone `#[proc_macro] pub fn xml` y convierte errores a compile errors. |
| `crates/xdoc-macros/src/ast.rs` | Macro AST | Define la representacion interna de elementos, atributos, texto, expresiones y componentes. |
| `crates/xdoc-macros/src/parser.rs` | Macro parser | Parsea el token stream de la sintaxis tipo XML/JSX. |
| `crates/xdoc-macros/src/codegen.rs` | Macro codegen | Genera llamadas a `xdoc::builder`, `xdoc::component` y `XmlTemplate`, resolviendo el nombre real de la dependencia. |
## CLI
| `crates/xdoc-cli/Cargo.toml` | CLI crate | Define package `xdoc-cli` y binario `xdoc`. |
| `crates/xdoc-cli/src/main.rs` | CLI | Implementa comandos `format`, `compact`, `parse`, `query`, `validate`, `validate-wellformed` y `canonicalize`. |
## Ejemplos
| `examples/generate_xml.rs` | Example/generic | Ejemplo generico de `xml!`, componentes, props, children, listas y namespaces. |
| `examples/dian_signature.rs` | Example/signature interoperability | Ejemplo externo de interoperabilidad de firma, fuera del motor y sin reglas de dominio en `src/`. |
## Tests y fixtures
| `tests/README.md` | Testing docs | Documenta fixtures, goldens y convenciones de pruebas. |
| `tests/support/mod.rs` | Testing support | Wrappers de soporte para tests de integracion. |
| `tests/testing_infrastructure.rs` | Testing | Pruebas de helpers, roundtrip y property tests de escaping. |
| `tests/compile.rs` | Macro tests | Ejecuta compile tests de `xml!` con `trybuild`. |
| `tests/compile/pass/xml_macro_pass.rs` | Macro tests | Casos validos de `xml!`: tags, atributos, namespaces y componentes. |
| `tests/compile/fail/*.rs` | Macro tests | Casos invalidos esperados de `xml!`. |
| `tests/compile/fail/*.stderr` | Macro tests | Salidas esperadas de errores de compilacion de `xml!`. |
| `tests/fixtures/xml/*.xml` | Parser/testing | XML validos e invalidos para parser, writer y helpers. |
| `tests/fixtures/contracts/simple-list.toml` | Schema/CLI | Contrato minimo usado por el comando `xdoc validate`. |
| `tests/golden/writer_*.xml` | Writer/golden | Salidas esperadas del writer. |
| `tests/golden/signature/*.xml` | Signature/golden | Salidas esperadas de canonicalizacion y XAdES generico. |
| `fuzz/README.md` | Fuzz | Documenta el harness inicial de fuzzing. |
| `fuzz/fuzz_targets/parser.rs` | Fuzz/parser | Harness inicial para ejercitar parser con entradas arbitrarias. |
## Documentacion operativa
| `README.md` | Project overview | Resume alcance, estado de modulos, publicacion y documentos operativos. |
| `plan_libreria_xml_generica_rust.md` | Source of truth | Fuente de verdad del proyecto. |
| `docs/context.md` | Process | Contexto de alcance, arquitectura y direccion de API. |
| `docs/instructions.md` | Process | Reglas de trabajo, Definition of Done y verificacion. |
| `docs/tasks/README.md` | Process/tasks | Indice del backlog y dependencias. |
| `docs/worklogs.md` | Process/worklog | Registro cronologico de avances, decisiones y verificacion. |
## Documentacion de usuario por feature
| `docs/library/README.md` | User docs | Entrada de aprendizaje para usuarios finales de la libreria. |
| `docs/library/features.md` | User docs/index | Indice de archivos por feature y rutas de aprendizaje. |
| `docs/library/core.md` | Core docs | Explica el modelo `Document`, `QName`, namespaces, nodos y errores. |
| `docs/library/builder.md` | Builder docs | Guia practica para construir XML con API Rust explicita. |
| `docs/library/component.md` | Component docs | Guia para props tipadas, children y composicion de XML grande. |
| `docs/library/macros.md` | Macro docs | Guia de `xml!`, interpolacion, namespaces, componentes y listas. |
| `docs/library/writer.md` | Writer docs | Guia de serializacion compacta/pretty, escaping y mixed content. |
| `docs/library/parser.md` | Parser docs | Guia de parsing seguro, entidades, namespaces y errores. |
| `docs/library/query.md` | Query docs | Guia de consultas tipo XPath subset, atributos, texto y namespaces. |
| `docs/library/transform.md` | Transform docs | Guia de templates XML a XML, parametros, repeat y seguridad. |
| `docs/library/schema.md` | Schema docs | Guia de contratos propios, required, cardinality, tipos y reglas custom. |
| `docs/library/security.md` | Security docs | Guia de limites y politicas seguras para parser/query/transform. |
| `docs/library/signature.md` | Signature docs | Guia practica y referencia de canonicalizacion, XMLDSig y XAdES generico. |
| `docs/library/testing.md` | Testing docs | Guia de helpers de prueba, fixtures, goldens y roundtrip. |
| `docs/library/cli.md` | CLI docs | Guia de comandos `xdoc` para inspeccion local. |
| `docs/library/files.md` | File map | Mapa por archivo del repositorio y responsabilidades. |
## Reglas de lectura por archivo
Para entender una feature desde cero:
[] Leer primero `docs/library/features.md`.
[] Luego leer el archivo Markdown propio de la feature.
[] Luego leer tests asociados si se necesita comportamiento exacto.
[] Para firma, leer tambien `docs/library/signature.md`.
Para modificar una feature:
[] Confirmar que el cambio no introduce dominio en `src/`.
[] Mantener el cambio en el archivo de responsabilidad mas cercana.
[] Agregar o ajustar tests del area afectada.
[] Actualizar esta documentacion cuando cambie una API publica o limite importante.