Fases 0 y 1: fundamentos, IR y lectura DOCX → DocMark

[digiogithub]

Implementa las dos primeras fases de docs/plan-desarrollo.md. El repositorio pasa de sólo documentación a un binario que convierte .docx a DocMark.

cargo run -p docsai-cli -- convert informe.docx -o informe.dmk.md

Fase 0 — Fundamentos

• Workspace con los siete crates de arquitectura.md §2. docsai-odf y docsai-mcp van vacíos a propósito: así el compilador impone las reglas de dependencia desde el primer día en vez de descubrirlas rotas en la Fase 4.
• docsai-model: Length en EMU, cascada de estilos de cuatro niveles con semántica referencia + delta, ListCatalog, el modelo normalizado de imágenes, AssetStore con deduplicación por contenido, ConversionReport tipado y el validador de invariantes del IR.
• Spike R1 ejecutado y documentado en docs/spikes/R1-estrategia-docx.md.
• Corpus de 14 docx + 6 xlsx generado por corpus/generate.py, reproducible byte a byte.
• Spec DocMark congelada en v1.0, anexo A (tablas complejas) resuelto y registro de cambios en §10.
• CI en las tres plataformas: build, test, corpus al día, fmt, clippy y rustdoc, todo con warnings como errores.

El spike R1, que cambió el plan

El plan contemplaba docx-rs con un complemento propio. Lo medí sobre el corpus en vez de suponerlo, y el resultado fue concluyente:

• Pierde casi todo el modelo de imagen: wrap y lado, behindDoc, recorte, volteos, texto alternativo, título, nombre del objeto, hipervínculo e imágenes enlazadas. La rotación tiene campo pero devuelve 0 para rot="2700000".
• Descarta w:footnoteReference y el w:instr de w:fldSimple.
• El VML se colapsa a un nodo genérico sin r:id, sin estilo y sin alt.
• No conserva elementos desconocidos, que es justo lo que necesita el raw-block.
• 204 pánicos de 903 entradas corruptas (23 %), contra un criterio de aceptación que exige siempre Err.

Decisión: parser propio sobre zip + quick-xml. Sigue siendo candidato para el writer de la Fase 2; eso es una decisión aparte y aún abierta.

Fase 1 — Lectura DOCX → DocMark

Lector completo: estilos con docDefaults y cadena basedOn, listas reconstruidas en árbol desde los pares planos (numId, ilvl), tablas con gridSpan/vMerge resueltos a colspan/rowspan, imágenes DrawingML y VML heredado con la geometría entera, secciones partidas en cada sectPr con cabeceras y pies por ámbito, notas al pie insertadas en su referencia, campos simples y complejos con su instrucción, y raw-blocks con los bytes exactos de todo lo no reconocido.

Serializador DocMark determinista con los tres modos de --fidelity, orquestación en docsai-convert y CLI con convert y formats.

Un detalle que sostiene la fidelidad: cada nodo del árbol XML recuerda su rango de bytes en el origen, así que un raw-block cita los bytes originales en lugar de una re-serialización.

Tres defectos que el corpus destapó

Ninguno se habría visto sin pasar documentos por el pipeline completo:

1. Formato de longitudes con pérdida. Un margen de Word de 1417 twips se escribía 2.499cm y al releerlo daba otro valor: habría movido márgenes e imágenes en cada ida y vuelta, poniendo un suelo artificial a la métrica de fidelidad de la Fase 2. Ahora se elige la primera unidad exacta (px → cm → pt → emu), con test que lo verifica caso a caso.
2. Párrafos vacíos desaparecían en silencio, contra la regla de no degradar sin avisar.
3. Estilo de hipervínculo emitido dos veces, dentro y fuera de la etiqueta.

El propio spike destapó además un error en el generador del corpus (w:drawing fuera de un w:r, OOXML inválido) antes de que contaminara ningún golden.

Verificación

164 tests, clippy -D warnings y fmt limpios. Los cuatro criterios de aceptación de cada fase están cubiertos por tests, no por inspección:

• Goldens de los 14 documentos del corpus, como ficheros .expected.dmk.md revisables junto al corpus.
• Cero pánicos con 900+ entradas corruptas (truncados y volteos de byte): siempre Err.
• Documento de 50+ páginas en < 1 s con < 10 raw-blocks.
• --fidelity plain verificado parseándolo con comrak.
• Round-trip JSON del IR con proptest, y determinismo del serializador.

Documentación

Nueva carpeta kb/ con cuatro documentos: resumen de lo entregado, estructura real del código, las decisiones técnicas no obvias con su motivo y su coste, y lo que espera a las fases siguientes. docs/ dice qué se quiere construir; kb/ dice qué hay hoy.

También quedan registradas en docs/analisis-tecnico.md las decisiones de dependencias que exige AGENTS.md §2: docx-rs fuera del camino de lectura, y insta, image y serde_yaml sin usar, cada una con su razón.

Alcance deliberado

No hay nada de la Fase 2: ni parser DocMark, ni writer docx, ni roundtrip.

Queda fuera, anotado en el plan:

• Documentos reales anonimizados (Fase 1, tarea 10): requiere disponer de ellos. No bloquea la Fase 2.
• Cuadros de texto DrawingML: viajan como raw-block. El tipo del IR y la sintaxis de la spec existen, pero emitirlos sin el writer que los reconstruya sería adelantar trabajo.
• Validación en Word y LibreOffice: criterio de la Fase 2, y no hay LibreOffice en el entorno.

Revisión sugerida

Los goldens (corpus/docx/*.expected.dmk.md) son la salida real del conversor y el mejor sitio para juzgar el resultado. kb/03-decisiones-tecnicas.md explica lo que no se deduce del código.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SgqYJYCmrfL21w585SQFkR

---

Generated by Claude Code