alran 0.0.0-stage → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (506) hide show
  1. package/ALRAN_TOOLS_NOTICES.md +64 -0
  2. package/LICENSE +27 -0
  3. package/LICENSE-STATUS.md +21 -0
  4. package/NOTICE +6 -0
  5. package/README.md +289 -2
  6. package/THIRD_PARTY_NOTICES.md +113 -0
  7. package/alran-tools.js +3 -0
  8. package/assets/agents/_default/prompt-auto_classifier.md +185 -0
  9. package/assets/agents/_default/prompt-auto_classifier_extras.md +17 -0
  10. package/assets/agents/_default/prompt-base-all.md +133 -0
  11. package/assets/agents/_default/prompt-base-all.md.hbs +228 -0
  12. package/assets/agents/_default/prompt-base-windows.md +5 -0
  13. package/assets/agents/_default/prompt-base-windows.md.hbs +5 -0
  14. package/assets/agents/_default/prompt-base-worker.md +10 -0
  15. package/assets/agents/_default/prompt-base-worker.md.hbs +27 -0
  16. package/assets/agents/_default/prompt-compact.md +76 -0
  17. package/assets/agents/_default/prompt-compact_continue.md +9 -0
  18. package/assets/agents/_default/prompt-git.md +8 -0
  19. package/assets/agents/_default/prompt-goal.md +13 -0
  20. package/assets/agents/_default/prompt-session-branch.md +3 -0
  21. package/assets/agents/_default/prompt-session-branch.md.hbs +30 -0
  22. package/assets/agents/_default/prompt-session-root.md +3 -0
  23. package/assets/agents/_default/prompt-session-root.md.hbs +32 -0
  24. package/assets/agents/_default/prompt-title.md +11 -0
  25. package/assets/agents/_default/prompt-tool_agent.md +22 -0
  26. package/assets/agents/_migration/README.md +20 -0
  27. package/assets/agents/_migration/coder/PERSONA.md +11 -0
  28. package/assets/agents/_migration/coder/system-prompt.md.hbs +42 -0
  29. package/assets/agents/_migration/general/PERSONA.md +11 -0
  30. package/assets/agents/_migration/general/system-prompt.md.hbs +49 -0
  31. package/assets/agents/_v2/AGENT_CONTEXT.md.hbs +245 -0
  32. package/assets/agents/_v2/PTC_TOOL_CALLS.md.hbs +35 -0
  33. package/assets/agents/_v2/coding/SYSTEM.md.hbs +173 -0
  34. package/assets/agents/_v2/explore.md.hbs +38 -0
  35. package/assets/agents/_v2/tui/SYSTEM.md.hbs +211 -0
  36. package/assets/agents/_v2/verifier.md.hbs +32 -0
  37. package/assets/agents/_v2/work/SYSTEM.md.hbs +186 -0
  38. package/assets/agents/_v2/worker.md.hbs +27 -0
  39. package/assets/agents/alran/PERSONA.md +7 -0
  40. package/assets/agents/alran/features/cron.md.hbs +0 -0
  41. package/assets/agents/alran/features/delegation.md.hbs +56 -0
  42. package/assets/agents/alran/features/memory.md.hbs +61 -0
  43. package/assets/agents/alran/features/recoverable-deletion.md.hbs +10 -0
  44. package/assets/agents/alran/features/task-management.md.hbs +11 -0
  45. package/assets/agents/alran/features/web-search.md.hbs +11 -0
  46. package/assets/agents/alran/modes/coding/online/PERSONA.md.hbs +20 -0
  47. package/assets/agents/alran/modes/coding/online/SYSTEM.md.hbs +158 -0
  48. package/assets/agents/alran/modes/work/online/PERSONA.md.hbs +20 -0
  49. package/assets/agents/alran/modes/work/online/SYSTEM.md.hbs +160 -0
  50. package/assets/agents/alran/prompt-session-root.md +4 -0
  51. package/assets/agents/alran/prompt-session-root.md.hbs +4 -0
  52. package/assets/agents/alran/skills/alran-code-product/SKILL.md +72 -0
  53. package/assets/agents/alran/skills/alran-code-product/references/account-models.md +61 -0
  54. package/assets/agents/alran/skills/alran-code-product/references/agents.md +34 -0
  55. package/assets/agents/alran/skills/alran-code-product/references/extensions.md +46 -0
  56. package/assets/agents/alran/skills/alran-code-product/references/workflows.md +56 -0
  57. package/assets/agents/alran/skills/control-in-app-browser/SKILL.md +590 -0
  58. package/assets/agents/alran/system-prompt.md.hbs +97 -0
  59. package/assets/agents/builtin-agents.json +1 -0
  60. package/assets/agents/desktop-task/archive-title/system-en.md +1 -0
  61. package/assets/agents/desktop-task/checkpoint/system.md +19 -0
  62. package/assets/agents/desktop-task/output-revision/system.md +1 -0
  63. package/assets/agents/desktop-task/retry/continuation.md +4 -0
  64. package/assets/agents/desktop-task/session-title/system.md +41 -0
  65. package/assets/agents/explore/PERSONA.md +8 -0
  66. package/assets/agents/explore/agent.md +14 -0
  67. package/assets/agents/explore/system-prompt.md.hbs +35 -0
  68. package/assets/agents/greeting.md +61 -0
  69. package/assets/agents/managed-prompts.json +47 -0
  70. package/assets/agents/prompt-exemptions.json +36 -0
  71. package/assets/agents/verifier/PERSONA.md +8 -0
  72. package/assets/agents/verifier/agent.md +17 -0
  73. package/assets/agents/verifier/system-prompt.md.hbs +28 -0
  74. package/assets/agents/worker/PERSONA.md +8 -0
  75. package/assets/agents/worker/agent.md +18 -0
  76. package/assets/agents/worker/system-prompt.md.hbs +22 -0
  77. package/assets/agents/workflow/code-review/review-candidates.md +120 -0
  78. package/assets/agents/workflow/code-review/reviewer-system.md +75 -0
  79. package/assets/agents/workflow/goal/budget-limit.md +16 -0
  80. package/assets/agents/workflow/goal/continuation.md +62 -0
  81. package/assets/agents/workflow/goal/objective-updated.md +16 -0
  82. package/assets/agents/workflow/goal/recovery-terminal-audit.md +13 -0
  83. package/assets/agents/workflow/goal/recovery.md +11 -0
  84. package/assets/agents/workflow/goal/terminal-audit.md +10 -0
  85. package/assets/agents/workflow/plan-mode/agent-entry.md +72 -0
  86. package/assets/agents/workflow/prompt-hook/system.md +0 -0
  87. package/assets/models-dev-catalog.json.gz +0 -0
  88. package/assets/prompts/code-review/review-candidates.md +120 -0
  89. package/assets/prompts/code-review/reviewer-system.md +75 -0
  90. package/assets/skills/alran-tools-master/SKILL.md +127 -0
  91. package/assets/skills/code-review/SKILL.md +51 -0
  92. package/assets/skills/cu-desktop/SKILL.md +255 -0
  93. package/assets/skills/deep-research/SKILL.md +30 -0
  94. package/assets/skills/deploy-website/SKILL.md +52 -0
  95. package/assets/skills/docx/LICENSE +21 -0
  96. package/assets/skills/docx/SKILL.md +259 -0
  97. package/assets/skills/docx/assets/styles/academic_styles.xml +250 -0
  98. package/assets/skills/docx/assets/styles/corporate_styles.xml +284 -0
  99. package/assets/skills/docx/assets/styles/default_styles.xml +449 -0
  100. package/assets/skills/docx/assets/xsd/aesthetic-rules.xsd +470 -0
  101. package/assets/skills/docx/assets/xsd/business-rules.xsd +130 -0
  102. package/assets/skills/docx/assets/xsd/common-types.xsd +159 -0
  103. package/assets/skills/docx/assets/xsd/wml-subset.xsd +589 -0
  104. package/assets/skills/docx/docs/acceptance-checklists/create.md +7 -0
  105. package/assets/skills/docx/docs/acceptance-checklists/edit.md +6 -0
  106. package/assets/skills/docx/docs/acceptance-checklists/layout-repair.md +7 -0
  107. package/assets/skills/docx/docs/acceptance-checklists/template.md +6 -0
  108. package/assets/skills/docx/docs/acceptance.md +139 -0
  109. package/assets/skills/docx/docs/anti-patterns.md +14 -0
  110. package/assets/skills/docx/docs/backends.md +116 -0
  111. package/assets/skills/docx/docs/evidence.md +73 -0
  112. package/assets/skills/docx/docs/failure-taxonomy.md +71 -0
  113. package/assets/skills/docx/docs/index.md +50 -0
  114. package/assets/skills/docx/docs/rendered-delivery.md +125 -0
  115. package/assets/skills/docx/docs/router.md +122 -0
  116. package/assets/skills/docx/docs/tables-and-numbering.md +27 -0
  117. package/assets/skills/docx/docs/task-apply-template.md +141 -0
  118. package/assets/skills/docx/docs/task-compare-two-docx.md +48 -0
  119. package/assets/skills/docx/docs/task-create.md +124 -0
  120. package/assets/skills/docx/docs/task-edit-fill.md +69 -0
  121. package/assets/skills/docx/docs/task-read-content.md +148 -0
  122. package/assets/skills/docx/docs/task-read-rendered.md +78 -0
  123. package/assets/skills/docx/docs/task-read-structure.md +93 -0
  124. package/assets/skills/docx/docs/task-repair-layout.md +70 -0
  125. package/assets/skills/docx/docs/template-dsl.md +32 -0
  126. package/assets/skills/docx/docs/track-changes.md +15 -0
  127. package/assets/skills/docx/docs/xml-patch-dsl.md +33 -0
  128. package/assets/skills/docx/references/cjk_typography.md +357 -0
  129. package/assets/skills/docx/references/cjk_university_template_guide.md +184 -0
  130. package/assets/skills/docx/references/comments_guide.md +191 -0
  131. package/assets/skills/docx/references/design_good_bad_examples.md +829 -0
  132. package/assets/skills/docx/references/design_principles.md +819 -0
  133. package/assets/skills/docx/references/openxml_element_order.md +308 -0
  134. package/assets/skills/docx/references/openxml_encyclopedia_part1.md +4061 -0
  135. package/assets/skills/docx/references/openxml_encyclopedia_part2.md +2820 -0
  136. package/assets/skills/docx/references/openxml_encyclopedia_part3.md +3381 -0
  137. package/assets/skills/docx/references/openxml_namespaces.md +82 -0
  138. package/assets/skills/docx/references/openxml_units.md +72 -0
  139. package/assets/skills/docx/references/sample-patch-plans.json +22 -0
  140. package/assets/skills/docx/references/sample-task-intents.json +5 -0
  141. package/assets/skills/docx/references/sample-template-manifests.json +21 -0
  142. package/assets/skills/docx/references/scenario_a_create.md +284 -0
  143. package/assets/skills/docx/references/scenario_b_edit_content.md +295 -0
  144. package/assets/skills/docx/references/scenario_c_apply_template.md +456 -0
  145. package/assets/skills/docx/references/track_changes_guide.md +200 -0
  146. package/assets/skills/docx/references/troubleshooting.md +506 -0
  147. package/assets/skills/docx/references/typography_guide.md +294 -0
  148. package/assets/skills/docx/references/xsd_validation_guide.md +158 -0
  149. package/assets/skills/docx/scripts/build_patch_plan.py +29 -0
  150. package/assets/skills/docx/scripts/diff_docx_structure.py +61 -0
  151. package/assets/skills/docx/scripts/doc_to_docx.ps1 +85 -0
  152. package/assets/skills/docx/scripts/doc_to_docx.sh +40 -0
  153. package/assets/skills/docx/scripts/docx_preview.ps1 +76 -0
  154. package/assets/skills/docx/scripts/docx_preview.sh +37 -0
  155. package/assets/skills/docx/scripts/docx_to_pdf.py +87 -0
  156. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/AlranAIDocx.Cli.csproj +19 -0
  157. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Cli/Program.cs +18 -0
  158. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/AlranAIDocx.Core.csproj +15 -0
  159. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/AnalyzeCommand.cs +147 -0
  160. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ApplyTemplateCommand.cs +322 -0
  161. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/CreateCommand.cs +324 -0
  162. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/DiffCommand.cs +155 -0
  163. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/EditContentCommand.cs +487 -0
  164. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/FixOrderCommand.cs +108 -0
  165. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/MergeRunsCommand.cs +122 -0
  166. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Commands/ValidateCommand.cs +107 -0
  167. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/CommentSynchronizer.cs +169 -0
  168. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/ElementOrder.cs +80 -0
  169. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/NamespaceConstants.cs +42 -0
  170. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/RunMerger.cs +81 -0
  171. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/StyleAnalyzer.cs +81 -0
  172. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/TrackChangesHelper.cs +99 -0
  173. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/OpenXml/UnitConverter.cs +23 -0
  174. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples.cs +1832 -0
  175. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch1.cs +910 -0
  176. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch2.cs +999 -0
  177. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch3.cs +1048 -0
  178. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/AestheticRecipeSamples_Batch4.cs +1038 -0
  179. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/CharacterFormattingSamples.cs +1020 -0
  180. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/DocumentCreationSamples.cs +1121 -0
  181. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FieldAndTocSamples.cs +624 -0
  182. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/FootnoteAndCommentSamples.cs +675 -0
  183. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/HeaderFooterSamples.cs +838 -0
  184. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ImageSamples.cs +917 -0
  185. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ListAndNumberingSamples.cs +826 -0
  186. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/ParagraphFormattingSamples.cs +1199 -0
  187. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/StyleSystemSamples.cs +1487 -0
  188. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TableSamples.cs +1163 -0
  189. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Samples/TrackChangesSamples.cs +595 -0
  190. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/CjkHelper.cs +39 -0
  191. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/FontDefaults.cs +24 -0
  192. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Typography/PageSizes.cs +20 -0
  193. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/BusinessRuleValidator.cs +224 -0
  194. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/GateCheckValidator.cs +148 -0
  195. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/ValidationResult.cs +23 -0
  196. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.Core/Validation/XsdValidator.cs +69 -0
  197. package/assets/skills/docx/scripts/dotnet/AlranAIDocx.slnx +4 -0
  198. package/assets/skills/docx/scripts/env_check.ps1 +327 -0
  199. package/assets/skills/docx/scripts/env_check.sh +340 -0
  200. package/assets/skills/docx/scripts/extract_docx_text.py +1075 -0
  201. package/assets/skills/docx/scripts/pack_docx.py +31 -0
  202. package/assets/skills/docx/scripts/read_docx_structure.py +1032 -0
  203. package/assets/skills/docx/scripts/render_docx_pages.py +147 -0
  204. package/assets/skills/docx/scripts/rendered_report.py +609 -0
  205. package/assets/skills/docx/scripts/setup.ps1 +542 -0
  206. package/assets/skills/docx/scripts/setup.sh +537 -0
  207. package/assets/skills/docx/scripts/unpack_docx.py +29 -0
  208. package/assets/skills/docx/scripts/validate_template_manifest.py +60 -0
  209. package/assets/skills/docx/scripts/verify_anchor_atomicity.py +87 -0
  210. package/assets/skills/edit-deployed-website/SKILL.md +27 -0
  211. package/assets/skills/init/SKILL.md +135 -0
  212. package/assets/skills/llm-call/SKILL.md +48 -0
  213. package/assets/skills/llm-call/scripts/llm_call.py +458 -0
  214. package/assets/skills/pdf/SKILL.md +280 -0
  215. package/assets/skills/pdf/docs/advanced-reference.md +711 -0
  216. package/assets/skills/pdf/docs/create-guide.md +437 -0
  217. package/assets/skills/pdf/docs/design-guide.md +204 -0
  218. package/assets/skills/pdf/docs/forms-guide.md +462 -0
  219. package/assets/skills/pdf/docs/html-pdf-spec.md +500 -0
  220. package/assets/skills/pdf/docs/latex-academic-thesis-guide.md +233 -0
  221. package/assets/skills/pdf/docs/latex-technical-book-guide.md +112 -0
  222. package/assets/skills/pdf/docs/pitfalls-index.md +792 -0
  223. package/assets/skills/pdf/docs/read-guide.md +358 -0
  224. package/assets/skills/pdf/docs/reformat-guide.md +238 -0
  225. package/assets/skills/pdf/docs/skill-readme-archive.md +151 -0
  226. package/assets/skills/pdf/docs/troubleshooting.md +86 -0
  227. package/assets/skills/pdf/docs/vision-guide.md +188 -0
  228. package/assets/skills/pdf/scripts/__init__.py +0 -0
  229. package/assets/skills/pdf/scripts/_pdf_read_lib.py +284 -0
  230. package/assets/skills/pdf/scripts/fill/__init__.py +0 -0
  231. package/assets/skills/pdf/scripts/fill/acroform_apply.py +153 -0
  232. package/assets/skills/pdf/scripts/fill/overlay_apply.py +109 -0
  233. package/assets/skills/pdf/scripts/lib/__init__.py +0 -0
  234. package/assets/skills/pdf/scripts/lib/acroform_io.py +170 -0
  235. package/assets/skills/pdf/scripts/lib/cli_utils.py +41 -0
  236. package/assets/skills/pdf/scripts/lib/geometry.py +79 -0
  237. package/assets/skills/pdf/scripts/make.sh +388 -0
  238. package/assets/skills/pdf/scripts/merge.py +112 -0
  239. package/assets/skills/pdf/scripts/pdf_inspect/__init__.py +0 -0
  240. package/assets/skills/pdf/scripts/pdf_inspect/acroform_inspect.py +52 -0
  241. package/assets/skills/pdf/scripts/pdf_inspect/acroform_probe.py +57 -0
  242. package/assets/skills/pdf/scripts/pdf_inspect/layout_scan.py +164 -0
  243. package/assets/skills/pdf/scripts/read_pdf_vision.py +473 -0
  244. package/assets/skills/pdf/scripts/reformat_parse.py +181 -0
  245. package/assets/skills/pdf/scripts/render/__init__.py +0 -0
  246. package/assets/skills/pdf/scripts/render/overlay_preview.py +86 -0
  247. package/assets/skills/pdf/scripts/render/page_rasterize.py +85 -0
  248. package/assets/skills/pdf/scripts/render_html.cjs +205 -0
  249. package/assets/skills/pdf/scripts/validate/__init__.py +0 -0
  250. package/assets/skills/pdf/scripts/validate/geometry_lint.py +124 -0
  251. package/assets/skills/pdf/templates/INDEX.md +90 -0
  252. package/assets/skills/pdf/templates/bilingual-menu-premium/README.md +175 -0
  253. package/assets/skills/pdf/templates/bilingual-menu-premium/skeleton.html +343 -0
  254. package/assets/skills/pdf/templates/brand-guide-2page/README.md +140 -0
  255. package/assets/skills/pdf/templates/brand-guide-2page/skeleton.html +264 -0
  256. package/assets/skills/pdf/templates/data-viz-report/README.md +234 -0
  257. package/assets/skills/pdf/templates/data-viz-report/skeleton.html +835 -0
  258. package/assets/skills/pdf/templates/form-fill-acroform/README.md +195 -0
  259. package/assets/skills/pdf/templates/form-fill-acroform/field_values.template.json +118 -0
  260. package/assets/skills/pdf/templates/latex-academic-thesis/README.md +146 -0
  261. package/assets/skills/pdf/templates/latex-academic-thesis/source.tex +334 -0
  262. package/assets/skills/pdf/templates/latex-technical-book/README.md +130 -0
  263. package/assets/skills/pdf/templates/latex-technical-book/README.template-source.md +62 -0
  264. package/assets/skills/pdf/templates/latex-technical-book/source.tex +439 -0
  265. package/assets/skills/pdf/templates/multi-article-aggregator/README.md +148 -0
  266. package/assets/skills/pdf/templates/multi-article-aggregator/pipeline.md +223 -0
  267. package/assets/skills/pdf/templates/multilang-research-report/README.md +136 -0
  268. package/assets/skills/pdf/templates/multilang-research-report/skeleton.html +242 -0
  269. package/assets/skills/pdf/templates/reformat-default/README.md +136 -0
  270. package/assets/skills/pdf/templates/reformat-default/skeleton.html +204 -0
  271. package/assets/skills/pdf/templates/translate-preserve-layout/README.md +136 -0
  272. package/assets/skills/pdf/templates/translate-preserve-layout/skeleton.html +96 -0
  273. package/assets/skills/pdf/templates/translate-preserve-layout/terminology.template.json +66 -0
  274. package/assets/skills/pptx/SKILL.md +283 -0
  275. package/assets/skills/pptx/references/design-system.md +424 -0
  276. package/assets/skills/pptx/references/editing.md +162 -0
  277. package/assets/skills/pptx/references/element-map.md +229 -0
  278. package/assets/skills/pptx/references/pitfalls.md +205 -0
  279. package/assets/skills/pptx/references/pptxgenjs.md +420 -0
  280. package/assets/skills/pptx/references/preview-selection-writeback.md +65 -0
  281. package/assets/skills/pptx/references/python-pptx-recipes.md +63 -0
  282. package/assets/skills/pptx/references/slide-types.md +413 -0
  283. package/assets/skills/pptx/scripts/alran-ppt-map.cjs +280 -0
  284. package/assets/skills/pptx/scripts/audit_pptx.py +708 -0
  285. package/assets/skills/pptx/scripts/extract_comments.py +468 -0
  286. package/assets/skills/pptx/scripts/extract_images.py +226 -0
  287. package/assets/skills/pptx/scripts/extract_pptx.py +285 -0
  288. package/assets/skills/pptx/scripts/pdf2png.swift +203 -0
  289. package/assets/skills/pptx/scripts/pptx-screenshot.sh +105 -0
  290. package/assets/skills/resume-codex/SKILL.md +53 -0
  291. package/assets/skills/resume-codex/scripts/session-reader.mjs +445 -0
  292. package/assets/skills/skill-creator/SKILL.md +188 -0
  293. package/assets/skills/skill-creator/references/anti-patterns.md +149 -0
  294. package/assets/skills/skill-creator/references/commands-macos-linux.md +38 -0
  295. package/assets/skills/skill-creator/references/commands-windows-powershell.md +48 -0
  296. package/assets/skills/skill-creator/references/description-rubric.md +83 -0
  297. package/assets/skills/skill-creator/references/skill-template.md +101 -0
  298. package/assets/skills/skill-creator/references/when-to-bundle-scripts.md +139 -0
  299. package/assets/skills/skill-creator/scripts/lint-skill.js +226 -0
  300. package/assets/skills/skill-refiner/SKILL.md +137 -0
  301. package/assets/skills/visual-page/SKILL.md +194 -0
  302. package/assets/skills/x-link-reader/SKILL.md +108 -0
  303. package/assets/skills/xlsx/SKILL.md +498 -0
  304. package/assets/skills/xlsx/docs/advanced-reference.md +410 -0
  305. package/assets/skills/xlsx/docs/conventions-guide.md +217 -0
  306. package/assets/skills/xlsx/docs/create-edit-guide.md +410 -0
  307. package/assets/skills/xlsx/docs/pitfalls-index.md +759 -0
  308. package/assets/skills/xlsx/docs/raw-xml-escape-hatch.md +201 -0
  309. package/assets/skills/xlsx/docs/recalc-guide.md +295 -0
  310. package/assets/skills/xlsx/scripts/office/helpers/__init__.py +0 -0
  311. package/assets/skills/xlsx/scripts/office/helpers/merge_runs.py +199 -0
  312. package/assets/skills/xlsx/scripts/office/helpers/simplify_redlines.py +197 -0
  313. package/assets/skills/xlsx/scripts/office/pack.py +159 -0
  314. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  315. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  316. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  317. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  318. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  319. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  320. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  321. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  322. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  323. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  324. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  325. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  326. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  327. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  328. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  329. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  330. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  331. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  332. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  333. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  334. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  335. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  336. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  337. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  338. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  339. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  340. package/assets/skills/xlsx/scripts/office/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  341. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  342. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  343. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  344. package/assets/skills/xlsx/scripts/office/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  345. package/assets/skills/xlsx/scripts/office/schemas/mce/mc.xsd +75 -0
  346. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2010.xsd +560 -0
  347. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2012.xsd +67 -0
  348. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-2018.xsd +14 -0
  349. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cex-2018.xsd +20 -0
  350. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-cid-2016.xsd +13 -0
  351. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  352. package/assets/skills/xlsx/scripts/office/schemas/microsoft/wml-symex-2015.xsd +8 -0
  353. package/assets/skills/xlsx/scripts/office/soffice.py +191 -0
  354. package/assets/skills/xlsx/scripts/office/unpack.py +132 -0
  355. package/assets/skills/xlsx/scripts/office/validate.py +117 -0
  356. package/assets/skills/xlsx/scripts/office/validators/__init__.py +15 -0
  357. package/assets/skills/xlsx/scripts/office/validators/base.py +851 -0
  358. package/assets/skills/xlsx/scripts/office/validators/docx.py +446 -0
  359. package/assets/skills/xlsx/scripts/office/validators/pptx.py +275 -0
  360. package/assets/skills/xlsx/scripts/office/validators/redlining.py +247 -0
  361. package/assets/skills/xlsx/scripts/recalc.py +450 -0
  362. package/chunks/account-commands-JZ6NXTTK.js +2 -0
  363. package/chunks/anthropic-MN33DP4E.js +2 -0
  364. package/chunks/application-ITGAJ4HC.js +2 -0
  365. package/chunks/auth-command-V3RVPLZO.js +2 -0
  366. package/chunks/azure-openai-responses-OWHMUNKC.js +2 -0
  367. package/chunks/chunk-2TF6JAQM.js +2 -0
  368. package/chunks/chunk-33CNY6GP.js +2 -0
  369. package/chunks/chunk-3AODGLMF.js +2 -0
  370. package/chunks/chunk-44VPC5LA.js +38 -0
  371. package/chunks/chunk-4CN3IJFH.js +2 -0
  372. package/chunks/chunk-4PDIO3M6.js +2 -0
  373. package/chunks/chunk-4X22UJQH.js +164 -0
  374. package/chunks/chunk-6255CZPL.js +2 -0
  375. package/chunks/chunk-6P4UKHGR.js +2 -0
  376. package/chunks/chunk-7QLAXRD2.js +1085 -0
  377. package/chunks/chunk-7XYOYZX2.js +2 -0
  378. package/chunks/chunk-A7GMJNA2.js +29 -0
  379. package/chunks/chunk-AGUSPIUP.js +2 -0
  380. package/chunks/chunk-BQ3CF3KE.js +2 -0
  381. package/chunks/chunk-C3CMJAAV.js +3 -0
  382. package/chunks/chunk-CJM7ZJ6W.js +7 -0
  383. package/chunks/chunk-CSOUJVKM.js +2 -0
  384. package/chunks/chunk-D66ZSHXR.js +2 -0
  385. package/chunks/chunk-D7MGU75P.js +2 -0
  386. package/chunks/chunk-E3GLGDGC.js +5 -0
  387. package/chunks/chunk-ENHOPPS7.js +16 -0
  388. package/chunks/chunk-EOR6EDNR.js +2 -0
  389. package/chunks/chunk-EYK25HWR.js +2 -0
  390. package/chunks/chunk-F46IELF5.js +2 -0
  391. package/chunks/chunk-FC4M2B7E.js +2 -0
  392. package/chunks/chunk-FSNYOJPJ.js +2 -0
  393. package/chunks/chunk-FUERW2DW.js +3 -0
  394. package/chunks/chunk-FXOH6TEQ.js +21 -0
  395. package/chunks/chunk-GP52JZMY.js +2 -0
  396. package/chunks/chunk-GRXX6I72.js +2 -0
  397. package/chunks/chunk-GSYHBK5Q.js +6 -0
  398. package/chunks/chunk-HNWBFJNO.js +2 -0
  399. package/chunks/chunk-IIE366LR.js +6706 -0
  400. package/chunks/chunk-IWK7PZP7.js +207 -0
  401. package/chunks/chunk-J3KCPYZT.js +2 -0
  402. package/chunks/chunk-KCLRJQ53.js +59 -0
  403. package/chunks/chunk-LU4RPLJ3.js +2 -0
  404. package/chunks/chunk-LZJYNT32.js +2 -0
  405. package/chunks/chunk-M7GW4VMR.js +27 -0
  406. package/chunks/chunk-MACBL5HF.js +2 -0
  407. package/chunks/chunk-N5NTXCJI.js +2 -0
  408. package/chunks/chunk-N5SVBCUB.js +7 -0
  409. package/chunks/chunk-N6W7ZL26.js +2 -0
  410. package/chunks/chunk-NWB7LFOK.js +131 -0
  411. package/chunks/chunk-OIQ336YE.js +16 -0
  412. package/chunks/chunk-OQNU3VPS.js +30 -0
  413. package/chunks/chunk-OTDNOWXG.js +16 -0
  414. package/chunks/chunk-PNXZWSWT.js +3 -0
  415. package/chunks/chunk-QFUV5PX6.js +2 -0
  416. package/chunks/chunk-QIN5ZBE2.js +2 -0
  417. package/chunks/chunk-QKBN5CGI.js +2 -0
  418. package/chunks/chunk-QPGTKSIQ.js +2 -0
  419. package/chunks/chunk-SIOLUFGG.js +2 -0
  420. package/chunks/chunk-TW23QKAD.js +3 -0
  421. package/chunks/chunk-U3RMPDXU.js +2 -0
  422. package/chunks/chunk-U7U3DJHF.js +2 -0
  423. package/chunks/chunk-VLXX22YO.js +2 -0
  424. package/chunks/chunk-WHD2XVT2.js +2 -0
  425. package/chunks/chunk-WTAJMYF2.js +249 -0
  426. package/chunks/chunk-WWNUAU4P.js +29 -0
  427. package/chunks/chunk-WYANV3IX.js +4 -0
  428. package/chunks/chunk-XAGZ6ZEU.js +9 -0
  429. package/chunks/chunk-XFCC2CI2.js +24 -0
  430. package/chunks/chunk-XQK7JM66.js +2 -0
  431. package/chunks/chunk-YLQXZBEL.js +2 -0
  432. package/chunks/chunk-YPV2X2RG.js +2 -0
  433. package/chunks/chunk-Z6BHCXKT.js +25 -0
  434. package/chunks/chunk-Z6HBNJCA.js +8 -0
  435. package/chunks/chunk-ZQKVUPKA.js +2 -0
  436. package/chunks/chunk-ZQOALVGL.js +2 -0
  437. package/chunks/clipboard-image-PQPC4EHR.js +2 -0
  438. package/chunks/data-dir-LDVKDCJ2.js +2 -0
  439. package/chunks/dist-2BRD4JFU.js +11 -0
  440. package/chunks/dist-EXKHRFQO.js +5 -0
  441. package/chunks/emscripten-module-RD6P2XH5.js +2 -0
  442. package/chunks/emscripten-module-WYNDFH3N.js +2 -0
  443. package/chunks/emscripten-module-XPTEOIWW.js +2 -0
  444. package/chunks/emscripten-module-ZS3PMSDF.js +2 -0
  445. package/chunks/ffi-IO7WZQNG.js +2 -0
  446. package/chunks/ffi-M5UP5J6C.js +2 -0
  447. package/chunks/ffi-ORLOPBB3.js +2 -0
  448. package/chunks/ffi-OUPK6AY6.js +2 -0
  449. package/chunks/google-UJAPMFAB.js +2 -0
  450. package/chunks/google-vertex-VLSF55PW.js +2 -0
  451. package/chunks/install-source-JTIUC4G4.js +2 -0
  452. package/chunks/launcher-FCZ3EDBF.js +61 -0
  453. package/chunks/lifecycle-GY435YMF.js +2 -0
  454. package/chunks/main-TQGGRHTS.js +13 -0
  455. package/chunks/mistral-ZJZUEF2X.js +3 -0
  456. package/chunks/module-6F3E5H7Y-BN7QWGYB.js +2 -0
  457. package/chunks/module-asyncify-R6PWJ6ZV-P4FWSBAY.js +2 -0
  458. package/chunks/multipart-parser-L6M455MS.js +2 -0
  459. package/chunks/network-proxy-U72JCK2I.js +2 -0
  460. package/chunks/openai-codex-responses-FPCDNRL5.js +2 -0
  461. package/chunks/openai-completions-D32YW6KL.js +2 -0
  462. package/chunks/openai-responses-ZCGSENM4.js +2 -0
  463. package/chunks/openrouter-G2EHY5BD.js +2 -0
  464. package/chunks/otel-OHXIZ666.js +2 -0
  465. package/chunks/package-contract-GVXTMJ3N.js +2 -0
  466. package/chunks/pdfjs-SHZAF7PF.js +107 -0
  467. package/chunks/photon_rs-C52RL4CI.js +3 -0
  468. package/chunks/plugin-command-OSAFHS7C.js +2 -0
  469. package/chunks/provider-command-SKTCHD4E.js +2 -0
  470. package/chunks/questionnaire-bridge-ISQOCYWY.js +2 -0
  471. package/chunks/run-acp-command-SG2BDMFJ.js +2 -0
  472. package/chunks/run-exec-command-5ADSQR2Z.js +15 -0
  473. package/chunks/skills-command-XXXEZAG6.js +2 -0
  474. package/chunks/src-DNIDEMVV.js +2 -0
  475. package/chunks/src-IBHIRTD7.js +2 -0
  476. package/chunks/telemetry-J7ZLGF5X.js +2 -0
  477. package/chunks/telemetry-command-COQG2AKK.js +5 -0
  478. package/chunks/tools-WDBB2JKV.js +2 -0
  479. package/chunks/undici-TUGHZJSA.js +2 -0
  480. package/chunks/update-NB6OD572.js +14 -0
  481. package/chunks/update-hint-ED7O67WU.js +3 -0
  482. package/chunks/wechat-onboard-UWXQW2HT.js +2 -0
  483. package/cli.js +5 -0
  484. package/configs/data-minimal.yaml +50 -0
  485. package/embedded/alran-tools/cli.mjs +4961 -0
  486. package/embedded/alran-tools/manifest.json +25 -0
  487. package/emscripten-module.wasm +0 -0
  488. package/image-preview-worker.js +2 -0
  489. package/internal-bin/alran-tools +9 -0
  490. package/internal-bin/alran-tools.cmd +8 -0
  491. package/matrix-mcp-stdio.js +4 -0
  492. package/native/darwin/prebuilds/darwin-arm64/darwin-modifiers.node +0 -0
  493. package/native/darwin/prebuilds/darwin-x64/darwin-modifiers.node +0 -0
  494. package/native/win32/prebuilds/win32-arm64/win32-console-mode.node +0 -0
  495. package/native/win32/prebuilds/win32-x64/win32-console-mode.node +0 -0
  496. package/package.json +38 -4
  497. package/photon_rs_bg.wasm +0 -0
  498. package/quickjs-worker.js +152 -0
  499. package/vendor/java-proxy-agent/build.ts +97 -0
  500. package/vendor/java-proxy-agent/srt-proxy-agent.jar +0 -0
  501. package/vendor/seccomp/arm64/apply-seccomp +0 -0
  502. package/vendor/seccomp/build.ts +74 -0
  503. package/vendor/seccomp/x64/apply-seccomp +0 -0
  504. package/vendor/srt-win/arm64/srt-win.exe +0 -0
  505. package/vendor/srt-win/build.ts +40 -0
  506. package/vendor/srt-win/x64/srt-win.exe +0 -0
@@ -0,0 +1,1032 @@
1
+ #!/usr/bin/env python3
2
+ """Deep DOCX structure analyzer.
3
+
4
+ This script is the **primary** structure-truth implementation for the docx
5
+ skill. It is intentionally not "a summarizer that needs dotnet to corroborate" —
6
+ it parses the OOXML parts directly (stdlib only) and produces an independent,
7
+ self-contained structure report covering:
8
+
9
+ * parts inventory + Content-Types vs rels cross-check
10
+ * relationship graph (document, headers, footers)
11
+ * section graph with page geometry, header/footer references and titlePg
12
+ * numbering chain (numId -> abstractNumId -> level definitions) plus usage
13
+ * field topology (simple + complex fields, instruction text, dirty/locked)
14
+ * bookmark topology (start/end pairing, orphan detection, reserved names)
15
+ * hyperlink topology (internal anchors + external URLs resolved via rels)
16
+ * comments topology (definitions, in-document ranges, parent links, orphans)
17
+ * revisions topology (kinds, actors, date range)
18
+ * styles inventory + cross-reference audit (defined/used/missing/contaminated)
19
+ * direct-formatting contamination heatmap
20
+ * a `diagnostics` array of categorized findings (template diagnosis aid)
21
+
22
+ The dotnet `analyze` command remains useful as an **independent confirmation**
23
+ shot (different parser, different runtime), but it is not the structure-truth
24
+ oracle. This script is.
25
+
26
+ Run:
27
+ python3 read_docx_structure.py path/to/file.docx --json
28
+ python3 read_docx_structure.py path/to/file.docx --section sections,numbering
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ import argparse
34
+ import json
35
+ import re
36
+ import sys
37
+ import xml.etree.ElementTree as ET
38
+ from collections import Counter, defaultdict
39
+ from datetime import datetime
40
+ from pathlib import Path
41
+ from typing import Any, Dict, Iterable, List, Optional, Tuple
42
+ from zipfile import ZipFile
43
+
44
+ # -- namespaces ----------------------------------------------------------------
45
+
46
+ NS = {
47
+ "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
48
+ "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
49
+ "rel": "http://schemas.openxmlformats.org/package/2006/relationships",
50
+ "ct": "http://schemas.openxmlformats.org/package/2006/content-types",
51
+ "w14": "http://schemas.microsoft.com/office/word/2010/wordml",
52
+ "w15": "http://schemas.microsoft.com/office/word/2012/wordml",
53
+ }
54
+
55
+ W = NS["w"]
56
+ R = NS["r"]
57
+ REL = NS["rel"]
58
+ CT = NS["ct"]
59
+
60
+
61
+ def qn(prefix: str, name: str) -> str:
62
+ return f"{{{NS[prefix]}}}{name}"
63
+
64
+
65
+ WVAL = qn("w", "val")
66
+ WTYPE = qn("w", "type")
67
+ WSTYLEID = qn("w", "styleId")
68
+ WCUSTOM = qn("w", "customStyle")
69
+ WDEFAULT = qn("w", "default")
70
+ RID = qn("r", "id")
71
+ WAUTHOR = qn("w", "author")
72
+ WDATE = qn("w", "date")
73
+
74
+
75
+ # -- XML helpers ---------------------------------------------------------------
76
+
77
+ def load_xml(archive: ZipFile, entry_name: str) -> Optional[ET.Element]:
78
+ try:
79
+ with archive.open(entry_name) as handle:
80
+ return ET.fromstring(handle.read())
81
+ except KeyError:
82
+ return None
83
+ except ET.ParseError as exc:
84
+ # Surface as diagnostic but do not crash the whole analysis.
85
+ return ET.fromstring(f"<broken xmlns='urn:broken'>{exc}</broken>")
86
+
87
+
88
+ def text_of(node: ET.Element) -> str:
89
+ return "".join(part.text or "" for part in node.findall(".//w:t", NS)).strip()
90
+
91
+
92
+ def attr(elem: ET.Element, name: str) -> Optional[str]:
93
+ """Return attribute by prefixed-or-bare name."""
94
+ return elem.get(name) or elem.get(name.split("}", 1)[-1] if "}" in name else name)
95
+
96
+
97
+ def w_attr(elem: ET.Element, local: str) -> Optional[str]:
98
+ return elem.get(qn("w", local)) or elem.get(local)
99
+
100
+
101
+ # -- conversion helpers --------------------------------------------------------
102
+
103
+ def twips_to_mm(value: Optional[str]) -> Optional[float]:
104
+ if value is None:
105
+ return None
106
+ try:
107
+ return round(int(value) / 1440.0 * 25.4, 2)
108
+ except (TypeError, ValueError):
109
+ return None
110
+
111
+
112
+ # -- packaging layer -----------------------------------------------------------
113
+
114
+ def parse_content_types(archive: ZipFile) -> Dict[str, Any]:
115
+ elem = load_xml(archive, "[Content_Types].xml")
116
+ if elem is None:
117
+ return {"defaults": {}, "overrides": {}, "missing": True}
118
+ defaults: Dict[str, str] = {}
119
+ overrides: Dict[str, str] = {}
120
+ for child in elem.findall(qn("ct", "Default")):
121
+ defaults[child.get("Extension", "")] = child.get("ContentType", "")
122
+ for child in elem.findall(qn("ct", "Override")):
123
+ overrides[child.get("PartName", "")] = child.get("ContentType", "")
124
+ return {"defaults": defaults, "overrides": overrides, "missing": False}
125
+
126
+
127
+ def parse_rels(archive: ZipFile, rels_path: str) -> List[Dict[str, str]]:
128
+ elem = load_xml(archive, rels_path)
129
+ if elem is None:
130
+ return []
131
+ rels: List[Dict[str, str]] = []
132
+ for child in elem.findall(qn("rel", "Relationship")):
133
+ rels.append({
134
+ "id": child.get("Id", ""),
135
+ "type": child.get("Type", ""),
136
+ "target": child.get("Target", ""),
137
+ "targetMode": child.get("TargetMode", "Internal"),
138
+ })
139
+ return rels
140
+
141
+
142
+ def collect_parts_inventory(archive: ZipFile) -> Dict[str, Any]:
143
+ parts = []
144
+ for info in archive.infolist():
145
+ parts.append({
146
+ "name": info.filename,
147
+ "size": info.file_size,
148
+ "compressed": info.compress_size,
149
+ })
150
+ return {
151
+ "count": len(parts),
152
+ "totalUncompressed": sum(p["size"] for p in parts),
153
+ "items": parts,
154
+ }
155
+
156
+
157
+ # -- styles --------------------------------------------------------------------
158
+
159
+ def parse_styles(styles_doc: Optional[ET.Element]) -> Dict[str, Any]:
160
+ if styles_doc is None:
161
+ return {"missing": True, "byId": {}, "defaults": {}}
162
+ by_id: Dict[str, Dict[str, Any]] = {}
163
+ defaults: Dict[str, str] = {}
164
+ for style in styles_doc.findall(qn("w", "style")):
165
+ style_id = w_attr(style, "styleId")
166
+ if not style_id:
167
+ continue
168
+ name_node = style.find(qn("w", "name"))
169
+ based_on = style.find(qn("w", "basedOn"))
170
+ link = style.find(qn("w", "link"))
171
+ next_style = style.find(qn("w", "next"))
172
+ ppr = style.find(qn("w", "pPr"))
173
+ outline_lvl = ppr.find(qn("w", "outlineLvl")) if ppr is not None else None
174
+ num_pr = ppr.find(qn("w", "numPr")) if ppr is not None else None
175
+ num_id = None
176
+ if num_pr is not None:
177
+ num_id_node = num_pr.find(qn("w", "numId"))
178
+ if num_id_node is not None:
179
+ num_id = w_attr(num_id_node, "val")
180
+ info = {
181
+ "styleId": style_id,
182
+ "type": w_attr(style, "type"),
183
+ "name": w_attr(name_node, "val") if name_node is not None else None,
184
+ "basedOn": w_attr(based_on, "val") if based_on is not None else None,
185
+ "linked": w_attr(link, "val") if link is not None else None,
186
+ "next": w_attr(next_style, "val") if next_style is not None else None,
187
+ "isDefault": w_attr(style, "default") == "1",
188
+ "isCustom": w_attr(style, "customStyle") == "1",
189
+ "outlineLvl": w_attr(outline_lvl, "val") if outline_lvl is not None else None,
190
+ "numId": num_id,
191
+ }
192
+ if info["isDefault"] and info["type"]:
193
+ defaults[info["type"]] = style_id
194
+ by_id[style_id] = info
195
+ return {"missing": False, "byId": by_id, "defaults": defaults}
196
+
197
+
198
+ def style_inheritance_chain(styles: Dict[str, Any], style_id: str) -> List[str]:
199
+ chain: List[str] = []
200
+ seen = set()
201
+ cursor = style_id
202
+ while cursor and cursor not in seen:
203
+ seen.add(cursor)
204
+ chain.append(cursor)
205
+ info = styles["byId"].get(cursor)
206
+ if not info:
207
+ break
208
+ cursor = info.get("basedOn")
209
+ return chain
210
+
211
+
212
+ # -- numbering -----------------------------------------------------------------
213
+
214
+ def parse_numbering(numbering_doc: Optional[ET.Element]) -> Dict[str, Any]:
215
+ if numbering_doc is None:
216
+ return {"missing": True, "abstractNums": {}, "nums": {}}
217
+ abstract: Dict[str, Dict[str, Any]] = {}
218
+ for an in numbering_doc.findall(qn("w", "abstractNum")):
219
+ an_id = w_attr(an, "abstractNumId")
220
+ multi = an.find(qn("w", "multiLevelType"))
221
+ levels: List[Dict[str, Any]] = []
222
+ for lvl in an.findall(qn("w", "lvl")):
223
+ num_fmt = lvl.find(qn("w", "numFmt"))
224
+ lvl_text = lvl.find(qn("w", "lvlText"))
225
+ start = lvl.find(qn("w", "start"))
226
+ p_style = lvl.find(qn("w", "pStyle"))
227
+ levels.append({
228
+ "ilvl": w_attr(lvl, "ilvl"),
229
+ "numFmt": w_attr(num_fmt, "val") if num_fmt is not None else None,
230
+ "lvlText": w_attr(lvl_text, "val") if lvl_text is not None else None,
231
+ "start": w_attr(start, "val") if start is not None else None,
232
+ "pStyle": w_attr(p_style, "val") if p_style is not None else None,
233
+ })
234
+ abstract[an_id or ""] = {
235
+ "abstractNumId": an_id,
236
+ "multiLevelType": w_attr(multi, "val") if multi is not None else None,
237
+ "levels": levels,
238
+ }
239
+ nums: Dict[str, Dict[str, Any]] = {}
240
+ for num in numbering_doc.findall(qn("w", "num")):
241
+ num_id = w_attr(num, "numId")
242
+ an_ref = num.find(qn("w", "abstractNumId"))
243
+ overrides = []
244
+ for ov in num.findall(qn("w", "lvlOverride")):
245
+ overrides.append({"ilvl": w_attr(ov, "ilvl")})
246
+ nums[num_id or ""] = {
247
+ "numId": num_id,
248
+ "abstractNumId": w_attr(an_ref, "val") if an_ref is not None else None,
249
+ "lvlOverrides": overrides,
250
+ }
251
+ return {"missing": False, "abstractNums": abstract, "nums": nums}
252
+
253
+
254
+ # -- comments ------------------------------------------------------------------
255
+
256
+ def parse_comments(comments_doc: Optional[ET.Element]) -> List[Dict[str, Any]]:
257
+ if comments_doc is None:
258
+ return []
259
+ items: List[Dict[str, Any]] = []
260
+ for comment in comments_doc.findall(qn("w", "comment")):
261
+ items.append({
262
+ "id": w_attr(comment, "id"),
263
+ "author": w_attr(comment, "author"),
264
+ "initials": w_attr(comment, "initials"),
265
+ "date": w_attr(comment, "date"),
266
+ "text": text_of(comment),
267
+ })
268
+ return items
269
+
270
+
271
+ def parse_comments_extended(doc: Optional[ET.Element]) -> List[Dict[str, Any]]:
272
+ if doc is None:
273
+ return []
274
+ items: List[Dict[str, Any]] = []
275
+ for entry in doc.findall(qn("w15", "commentEx")):
276
+ items.append({
277
+ "paraId": entry.get(qn("w15", "paraId")) or entry.get("paraId"),
278
+ "paraIdParent": entry.get(qn("w15", "paraIdParent")) or entry.get("paraIdParent"),
279
+ "done": (entry.get(qn("w15", "done")) or entry.get("done")) == "1",
280
+ })
281
+ return items
282
+
283
+
284
+ # -- field state machine -------------------------------------------------------
285
+
286
+ FIELD_KIND = re.compile(r"^\s*([A-Z]+)")
287
+
288
+
289
+ def classify_field(instr: str) -> str:
290
+ match = FIELD_KIND.match(instr.strip())
291
+ return match.group(1) if match else "UNKNOWN"
292
+
293
+
294
+ def collect_complex_fields(body: ET.Element) -> List[Dict[str, Any]]:
295
+ """Walk body in document order pairing fldChar begin/separate/end."""
296
+ out: List[Dict[str, Any]] = []
297
+ stack: List[Dict[str, Any]] = []
298
+ for run in body.iter(qn("w", "r")):
299
+ fld_char = run.find(qn("w", "fldChar"))
300
+ instr = run.find(qn("w", "instrText"))
301
+ text = run.find(qn("w", "t"))
302
+ if fld_char is not None:
303
+ kind = w_attr(fld_char, "fldCharType")
304
+ if kind == "begin":
305
+ stack.append({
306
+ "instr": "",
307
+ "result": "",
308
+ "dirty": w_attr(fld_char, "dirty") == "1",
309
+ "locked": w_attr(fld_char, "fldLock") == "1",
310
+ "phase": "instr",
311
+ })
312
+ elif kind == "separate" and stack:
313
+ stack[-1]["phase"] = "result"
314
+ elif kind == "end" and stack:
315
+ completed = stack.pop()
316
+ completed["kind"] = classify_field(completed["instr"])
317
+ completed.pop("phase", None)
318
+ if stack:
319
+ # Field-in-field (rare); treat outer result as still being captured.
320
+ stack[-1]["result"] += completed.get("result", "")
321
+ out.append(completed)
322
+ elif instr is not None and stack and stack[-1].get("phase") == "instr":
323
+ stack[-1]["instr"] += instr.text or ""
324
+ elif text is not None and stack and stack[-1].get("phase") == "result":
325
+ stack[-1]["result"] += text.text or ""
326
+ return out
327
+
328
+
329
+ def collect_simple_fields(body: ET.Element) -> List[Dict[str, Any]]:
330
+ out: List[Dict[str, Any]] = []
331
+ for fld in body.iter(qn("w", "fldSimple")):
332
+ instr = w_attr(fld, "instr") or ""
333
+ out.append({
334
+ "instr": instr.strip(),
335
+ "kind": classify_field(instr),
336
+ "dirty": w_attr(fld, "dirty") == "1",
337
+ "result": text_of(fld),
338
+ })
339
+ return out
340
+
341
+
342
+ # -- bookmarks -----------------------------------------------------------------
343
+
344
+ def collect_bookmarks(body: ET.Element) -> Dict[str, Any]:
345
+ starts: Dict[str, Dict[str, Any]] = {}
346
+ ends_seen: List[str] = []
347
+ paragraph_seq: List[ET.Element] = list(body.iter(qn("w", "p")))
348
+ para_index_by_id = {id(p): idx for idx, p in enumerate(paragraph_seq)}
349
+
350
+ def parent_paragraph_index(elem: ET.Element) -> Optional[int]:
351
+ # Walk through the tree to find the enclosing <w:p>; ET has no parent
352
+ # pointer, so we precomputed paragraph identity below.
353
+ return None
354
+
355
+ # Instead of walking ancestors we walk paragraphs and record bookmark anchors
356
+ # encountered inside each paragraph. This still provides a correct paragraph-
357
+ # span for any bookmark whose start/end are inside the body's paragraph tree.
358
+ para_index: Dict[str, Dict[str, int]] = {}
359
+ for idx, paragraph in enumerate(paragraph_seq):
360
+ for bm in paragraph.iter(qn("w", "bookmarkStart")):
361
+ bm_id = w_attr(bm, "id")
362
+ if bm_id is not None:
363
+ para_index.setdefault(bm_id, {})["startPara"] = idx
364
+ for bm in paragraph.iter(qn("w", "bookmarkEnd")):
365
+ bm_id = w_attr(bm, "id")
366
+ if bm_id is not None:
367
+ para_index.setdefault(bm_id, {})["endPara"] = idx
368
+
369
+ for bm in body.iter(qn("w", "bookmarkStart")):
370
+ bm_id = w_attr(bm, "id")
371
+ name = w_attr(bm, "name") or ""
372
+ starts[bm_id or ""] = {
373
+ "id": bm_id,
374
+ "name": name,
375
+ "reserved": name.startswith("_"),
376
+ "startPara": para_index.get(bm_id or "", {}).get("startPara"),
377
+ }
378
+ for bm in body.iter(qn("w", "bookmarkEnd")):
379
+ bm_id = w_attr(bm, "id")
380
+ ends_seen.append(bm_id or "")
381
+ if bm_id and bm_id in starts:
382
+ starts[bm_id]["endPara"] = para_index.get(bm_id, {}).get("endPara")
383
+ end_counter = Counter(ends_seen)
384
+ pairs: List[Dict[str, Any]] = []
385
+ orphan_starts: List[Dict[str, Any]] = []
386
+ for bm_id, info in starts.items():
387
+ if end_counter.get(bm_id, 0) >= 1:
388
+ pairs.append(info)
389
+ else:
390
+ orphan_starts.append(info)
391
+ orphan_ends = [bm_id for bm_id in end_counter if bm_id not in starts]
392
+ return {
393
+ "pairs": pairs,
394
+ "orphanStarts": orphan_starts,
395
+ "orphanEnds": orphan_ends,
396
+ }
397
+
398
+
399
+ # -- hyperlinks ----------------------------------------------------------------
400
+
401
+ def collect_hyperlinks(body: ET.Element, rels_by_id: Dict[str, Dict[str, str]]) -> List[Dict[str, Any]]:
402
+ items: List[Dict[str, Any]] = []
403
+ for hl in body.iter(qn("w", "hyperlink")):
404
+ anchor = w_attr(hl, "anchor")
405
+ rid = hl.get(RID)
406
+ target_url = None
407
+ target_mode = None
408
+ if rid and rid in rels_by_id:
409
+ target_url = rels_by_id[rid].get("target")
410
+ target_mode = rels_by_id[rid].get("targetMode")
411
+ items.append({
412
+ "anchor": anchor,
413
+ "rId": rid,
414
+ "url": target_url,
415
+ "external": target_mode == "External",
416
+ "text": text_of(hl)[:200] or None,
417
+ })
418
+ return items
419
+
420
+
421
+ # -- sections / page setup -----------------------------------------------------
422
+
423
+ def parse_section(sect_pr: ET.Element) -> Dict[str, Any]:
424
+ pg_sz = sect_pr.find(qn("w", "pgSz"))
425
+ pg_mar = sect_pr.find(qn("w", "pgMar"))
426
+ type_node = sect_pr.find(qn("w", "type"))
427
+ cols = sect_pr.find(qn("w", "cols"))
428
+ title_pg = sect_pr.find(qn("w", "titlePg"))
429
+ line_num = sect_pr.find(qn("w", "lnNumType"))
430
+ pg_borders = sect_pr.find(qn("w", "pgBorders"))
431
+ headers = []
432
+ footers = []
433
+ for ref in sect_pr.findall(qn("w", "headerReference")):
434
+ headers.append({"type": w_attr(ref, "type"), "rId": ref.get(RID)})
435
+ for ref in sect_pr.findall(qn("w", "footerReference")):
436
+ footers.append({"type": w_attr(ref, "type"), "rId": ref.get(RID)})
437
+
438
+ page_size = None
439
+ if pg_sz is not None:
440
+ page_size = {
441
+ "widthMm": twips_to_mm(w_attr(pg_sz, "w")),
442
+ "heightMm": twips_to_mm(w_attr(pg_sz, "h")),
443
+ "orient": w_attr(pg_sz, "orient") or "portrait",
444
+ }
445
+ margins = None
446
+ if pg_mar is not None:
447
+ margins = {
448
+ side: twips_to_mm(w_attr(pg_mar, side))
449
+ for side in ("top", "right", "bottom", "left", "header", "footer", "gutter")
450
+ }
451
+ return {
452
+ "type": (w_attr(type_node, "val") if type_node is not None else None) or "nextPage",
453
+ "pageSize": page_size,
454
+ "margins": margins,
455
+ "columns": (int(w_attr(cols, "num")) if cols is not None and (w_attr(cols, "num") or "").isdigit() else 1),
456
+ "titlePg": title_pg is not None,
457
+ "lineNumbering": line_num is not None,
458
+ "pageBorders": pg_borders is not None,
459
+ "headerReferences": headers,
460
+ "footerReferences": footers,
461
+ }
462
+
463
+
464
+ # -- direct-formatting contamination ------------------------------------------
465
+
466
+ NON_REF_PPR_CHILDREN = {
467
+ qn("w", "rPr"), qn("w", "sectPr"),
468
+ }
469
+ ALLOWED_PPR_REF_CHILDREN = {qn("w", "pStyle"), qn("w", "numPr")}
470
+
471
+
472
+ def paragraph_contamination(paragraph: ET.Element) -> Dict[str, int]:
473
+ info = {"pPrDirect": 0, "rPrDirectRuns": 0, "totalRuns": 0}
474
+ ppr = paragraph.find(qn("w", "pPr"))
475
+ if ppr is not None:
476
+ for child in list(ppr):
477
+ if child.tag not in ALLOWED_PPR_REF_CHILDREN and child.tag not in NON_REF_PPR_CHILDREN:
478
+ info["pPrDirect"] += 1
479
+ # rPr inside pPr (paragraph-mark formatting) also counts as direct
480
+ run_ppr = ppr.find(qn("w", "rPr"))
481
+ if run_ppr is not None and len(list(run_ppr)) > 0:
482
+ info["pPrDirect"] += 1
483
+ for run in paragraph.findall(qn("w", "r")):
484
+ info["totalRuns"] += 1
485
+ rpr = run.find(qn("w", "rPr"))
486
+ if rpr is not None:
487
+ non_style = [c for c in list(rpr) if c.tag != qn("w", "rStyle")]
488
+ if non_style:
489
+ info["rPrDirectRuns"] += 1
490
+ return info
491
+
492
+
493
+ # -- main analyze --------------------------------------------------------------
494
+
495
+ def analyze(path: Path) -> Dict[str, Any]:
496
+ diagnostics: List[Dict[str, str]] = []
497
+
498
+ def diag(severity: str, code: str, message: str, **extra: Any) -> None:
499
+ item = {"severity": severity, "code": code, "message": message}
500
+ item.update(extra)
501
+ diagnostics.append(item)
502
+
503
+ with ZipFile(path, "r") as archive:
504
+ document = load_xml(archive, "word/document.xml")
505
+ if document is None:
506
+ raise RuntimeError("Not a valid DOCX: word/document.xml missing")
507
+ body = document.find(qn("w", "body"))
508
+ if body is None:
509
+ raise RuntimeError("Document body missing")
510
+
511
+ styles_doc = load_xml(archive, "word/styles.xml")
512
+ numbering_doc = load_xml(archive, "word/numbering.xml")
513
+ comments_doc = load_xml(archive, "word/comments.xml")
514
+ comments_ext_doc = load_xml(archive, "word/commentsExtended.xml")
515
+ footnotes_doc = load_xml(archive, "word/footnotes.xml")
516
+ endnotes_doc = load_xml(archive, "word/endnotes.xml")
517
+ settings_doc = load_xml(archive, "word/settings.xml")
518
+
519
+ content_types = parse_content_types(archive)
520
+ rels_doc = parse_rels(archive, "word/_rels/document.xml.rels")
521
+ package_rels = parse_rels(archive, "_rels/.rels")
522
+ rels_by_id = {r["id"]: r for r in rels_doc}
523
+
524
+ styles = parse_styles(styles_doc)
525
+ numbering = parse_numbering(numbering_doc)
526
+ comments = parse_comments(comments_doc)
527
+ comments_ext = parse_comments_extended(comments_ext_doc)
528
+
529
+ # --- traverse body --------------------------------------------------
530
+
531
+ paragraphs = list(body.iter(qn("w", "p")))
532
+ tables = list(body.iter(qn("w", "tbl")))
533
+ sect_prs = list(body.iter(qn("w", "sectPr")))
534
+ drawings = list(body.iter(qn("w", "drawing")))
535
+
536
+ used_para_styles: Counter = Counter()
537
+ used_run_styles: Counter = Counter()
538
+ numbered_paragraphs: List[Dict[str, Any]] = []
539
+ contamination_total = {"pPrDirect": 0, "rPrDirectRuns": 0, "paragraphsDirty": 0, "totalRuns": 0}
540
+ heading_paragraphs: List[Dict[str, Any]] = []
541
+ para_ids: List[str] = []
542
+
543
+ for index, paragraph in enumerate(paragraphs):
544
+ ppr = paragraph.find(qn("w", "pPr"))
545
+ style_node = ppr.find(qn("w", "pStyle")) if ppr is not None else None
546
+ style_id = w_attr(style_node, "val") if style_node is not None else None
547
+ if style_id:
548
+ used_para_styles[style_id] += 1
549
+ for run in paragraph.findall(qn("w", "r")):
550
+ rpr = run.find(qn("w", "rPr"))
551
+ if rpr is not None:
552
+ rstyle = rpr.find(qn("w", "rStyle"))
553
+ if rstyle is not None:
554
+ rs_val = w_attr(rstyle, "val")
555
+ if rs_val:
556
+ used_run_styles[rs_val] += 1
557
+ num_pr = ppr.find(qn("w", "numPr")) if ppr is not None else None
558
+ if num_pr is not None:
559
+ num_id_node = num_pr.find(qn("w", "numId"))
560
+ ilvl_node = num_pr.find(qn("w", "ilvl"))
561
+ numbered_paragraphs.append({
562
+ "index": index,
563
+ "numId": w_attr(num_id_node, "val") if num_id_node is not None else None,
564
+ "ilvl": w_attr(ilvl_node, "val") if ilvl_node is not None else None,
565
+ "styleId": style_id,
566
+ })
567
+
568
+ para_id = paragraph.get(qn("w14", "paraId"))
569
+ if para_id:
570
+ para_ids.append(para_id)
571
+
572
+ cont = paragraph_contamination(paragraph)
573
+ contamination_total["pPrDirect"] += cont["pPrDirect"]
574
+ contamination_total["rPrDirectRuns"] += cont["rPrDirectRuns"]
575
+ contamination_total["totalRuns"] += cont["totalRuns"]
576
+ if cont["pPrDirect"] or cont["rPrDirectRuns"]:
577
+ contamination_total["paragraphsDirty"] += 1
578
+
579
+ text = text_of(paragraph)
580
+ outline_lvl = None
581
+ if style_id and style_id in styles["byId"]:
582
+ outline_lvl = styles["byId"][style_id].get("outlineLvl")
583
+ if outline_lvl is None and ppr is not None:
584
+ outline_node = ppr.find(qn("w", "outlineLvl"))
585
+ if outline_node is not None:
586
+ outline_lvl = w_attr(outline_node, "val")
587
+ heading_like = bool(style_id and (
588
+ "heading" in style_id.lower() or style_id.lower() in {"title", "subtitle"}
589
+ ))
590
+ if text and (outline_lvl is not None or heading_like):
591
+ heading_paragraphs.append({
592
+ "paraIndex": index,
593
+ "styleId": style_id,
594
+ "outlineLvl": int(outline_lvl) if outline_lvl and str(outline_lvl).isdigit() else None,
595
+ "text": text[:240],
596
+ })
597
+
598
+ # --- sections -------------------------------------------------------
599
+
600
+ sections: List[Dict[str, Any]] = []
601
+ for sect_index, sect_pr in enumerate(sect_prs, start=1):
602
+ entry = parse_section(sect_pr)
603
+ entry["index"] = sect_index
604
+ sections.append(entry)
605
+
606
+ # --- header/footer parts via rels ----------------------------------
607
+
608
+ header_footer_parts = []
609
+ for rel in rels_doc:
610
+ if rel["type"].endswith("/header") or rel["type"].endswith("/footer"):
611
+ target = rel["target"]
612
+ if not target.startswith("/"):
613
+ full = f"word/{target.lstrip('./')}"
614
+ else:
615
+ full = target.lstrip("/")
616
+ part_xml = load_xml(archive, full)
617
+ if part_xml is None:
618
+ diag("error", "missing-header-footer-part",
619
+ f"rel {rel['id']} -> {target} but part not found", target=target)
620
+ continue
621
+ paragraphs_in_part = list(part_xml.iter(qn("w", "p")))
622
+ simple_in_part = collect_simple_fields(part_xml)
623
+ complex_in_part = collect_complex_fields(part_xml)
624
+ part_fields = simple_in_part + complex_in_part
625
+ images_in_part = sum(1 for _ in part_xml.iter(qn("w", "drawing")))
626
+ hyperlinks_in_part = sum(1 for _ in part_xml.iter(qn("w", "hyperlink")))
627
+ header_footer_parts.append({
628
+ "kind": "header" if rel["type"].endswith("/header") else "footer",
629
+ "rId": rel["id"],
630
+ "target": target,
631
+ "paragraphs": len(paragraphs_in_part),
632
+ "fields": len(part_fields),
633
+ "fieldKinds": dict(Counter(f["kind"] for f in part_fields)),
634
+ "drawings": images_in_part,
635
+ "hyperlinks": hyperlinks_in_part,
636
+ })
637
+
638
+ # Cross-check: every header/footerReference in any section MUST resolve.
639
+ ref_rids = set()
640
+ for sect in sections:
641
+ for ref in sect["headerReferences"] + sect["footerReferences"]:
642
+ rid = ref.get("rId")
643
+ if rid:
644
+ ref_rids.add(rid)
645
+ if rid not in rels_by_id:
646
+ diag("error", "section-ref-broken",
647
+ f"section {sect['index']} references rId {rid} but rels has no such id",
648
+ sectionIndex=sect["index"], rId=rid)
649
+
650
+ # --- numbering analysis --------------------------------------------
651
+
652
+ num_usage: Counter = Counter()
653
+ num_per_level: Dict[Tuple[str, str], int] = defaultdict(int)
654
+ for entry in numbered_paragraphs:
655
+ nid = entry.get("numId") or ""
656
+ num_usage[nid] += 1
657
+ ilvl = entry.get("ilvl") or "0"
658
+ num_per_level[(nid, ilvl)] += 1
659
+ numbering_usage = {
660
+ "perNumId": dict(num_usage),
661
+ "perNumIdLevel": [
662
+ {"numId": k[0], "ilvl": k[1], "paragraphs": v}
663
+ for k, v in sorted(num_per_level.items())
664
+ ],
665
+ }
666
+
667
+ for nid in num_usage:
668
+ if nid not in numbering["nums"]:
669
+ diag("error", "numbering-numid-missing",
670
+ f"numId {nid} used in body but not defined in numbering.xml",
671
+ numId=nid)
672
+ else:
673
+ an_id = numbering["nums"][nid].get("abstractNumId")
674
+ if an_id and an_id not in numbering["abstractNums"]:
675
+ diag("error", "numbering-abstractnum-missing",
676
+ f"numId {nid} -> abstractNumId {an_id} (definition missing)",
677
+ numId=nid, abstractNumId=an_id)
678
+ for nid, info in numbering["nums"].items():
679
+ if nid not in num_usage:
680
+ diag("info", "numbering-numid-unused",
681
+ f"numId {nid} defined in numbering.xml but not referenced in document body",
682
+ numId=nid)
683
+
684
+ # --- styles audit ---------------------------------------------------
685
+
686
+ defined_ids = set(styles["byId"].keys())
687
+ referenced_para_styles = set(used_para_styles)
688
+ referenced_run_styles = set(used_run_styles)
689
+ # styles linked from numbering pStyle pull
690
+ for an in numbering["abstractNums"].values():
691
+ for lvl in an["levels"]:
692
+ if lvl.get("pStyle"):
693
+ referenced_para_styles.add(lvl["pStyle"])
694
+ all_referenced = referenced_para_styles | referenced_run_styles
695
+ missing_styles = sorted(s for s in all_referenced if s not in defined_ids)
696
+ for s in missing_styles:
697
+ diag("error", "style-missing",
698
+ f"style '{s}' is referenced but not defined in styles.xml",
699
+ styleId=s)
700
+ unused_defined = sorted(s for s in defined_ids if s not in all_referenced)
701
+
702
+ heading_outline_audit = []
703
+ for sid, info in styles["byId"].items():
704
+ name = (info.get("name") or "").lower()
705
+ if "heading" in (sid.lower() + name) and info.get("outlineLvl") is None:
706
+ heading_outline_audit.append(sid)
707
+ diag("warn", "heading-style-without-outline",
708
+ f"heading-like style '{sid}' has no <w:outlineLvl/>; TOC and nav pane will misbehave",
709
+ styleId=sid)
710
+
711
+ # --- references -----------------------------------------------------
712
+
713
+ complex_fields = collect_complex_fields(body)
714
+ simple_fields = collect_simple_fields(body)
715
+ all_fields = simple_fields + complex_fields
716
+ field_kinds = Counter(f["kind"] for f in all_fields)
717
+ dirty_fields = sum(1 for f in all_fields if f.get("dirty"))
718
+
719
+ bookmarks = collect_bookmarks(body)
720
+ if bookmarks["orphanStarts"]:
721
+ diag("warn", "bookmark-orphan-start",
722
+ f"{len(bookmarks['orphanStarts'])} bookmarkStart without matching bookmarkEnd",
723
+ ids=[b.get("id") for b in bookmarks["orphanStarts"]])
724
+ if bookmarks["orphanEnds"]:
725
+ diag("warn", "bookmark-orphan-end",
726
+ f"{len(bookmarks['orphanEnds'])} bookmarkEnd without matching bookmarkStart",
727
+ ids=bookmarks["orphanEnds"])
728
+
729
+ hyperlinks = collect_hyperlinks(body, rels_by_id)
730
+ for hl in hyperlinks:
731
+ if hl["rId"] and hl["url"] is None:
732
+ diag("error", "hyperlink-rel-broken",
733
+ f"hyperlink references rId {hl['rId']} but rel target missing",
734
+ rId=hl["rId"])
735
+
736
+ # --- comments topology ---------------------------------------------
737
+
738
+ comment_starts = list(body.iter(qn("w", "commentRangeStart")))
739
+ comment_ends = list(body.iter(qn("w", "commentRangeEnd")))
740
+ comment_refs = list(body.iter(qn("w", "commentReference")))
741
+ comment_ids_in_body = {w_attr(c, "id") for c in comment_starts}
742
+ comment_ids_defined = {c["id"] for c in comments}
743
+ comment_orphan_in_body = sorted(comment_ids_in_body - comment_ids_defined)
744
+ comment_orphan_in_defs = sorted(comment_ids_defined - comment_ids_in_body)
745
+ for cid in comment_orphan_in_body:
746
+ diag("error", "comment-id-undefined",
747
+ f"commentRangeStart id={cid} not defined in comments.xml",
748
+ commentId=cid)
749
+ for cid in comment_orphan_in_defs:
750
+ diag("info", "comment-defined-not-anchored",
751
+ f"comment {cid} defined but no commentRangeStart in document body",
752
+ commentId=cid)
753
+
754
+ # --- revisions ------------------------------------------------------
755
+
756
+ revision_kinds = [
757
+ "ins", "del", "moveFrom", "moveTo",
758
+ "cellIns", "cellDel", "cellMerge",
759
+ "rPrChange", "pPrChange", "tblPrChange",
760
+ "trPrChange", "tcPrChange", "sectPrChange", "numberingChange",
761
+ ]
762
+ revision_counts: Dict[str, int] = {}
763
+ revision_actors: Counter = Counter()
764
+ revision_dates: List[str] = []
765
+ for kind in revision_kinds:
766
+ elems = list(body.iter(qn("w", kind)))
767
+ revision_counts[kind] = len(elems)
768
+ for el in elems:
769
+ author = el.get(WAUTHOR)
770
+ if author:
771
+ revision_actors[author] += 1
772
+ date = el.get(WDATE)
773
+ if date:
774
+ revision_dates.append(date)
775
+ date_min = min(revision_dates) if revision_dates else None
776
+ date_max = max(revision_dates) if revision_dates else None
777
+
778
+ # --- footnotes / endnotes ------------------------------------------
779
+
780
+ def count_notes(doc: Optional[ET.Element], tag: str) -> int:
781
+ if doc is None:
782
+ return 0
783
+ return sum(1 for n in doc.findall(qn("w", tag))
784
+ if w_attr(n, "type") not in {"separator", "continuationSeparator"})
785
+
786
+ footnotes_count = count_notes(footnotes_doc, "footnote")
787
+ endnotes_count = count_notes(endnotes_doc, "endnote")
788
+
789
+ # --- settings flags relevant to structure --------------------------
790
+
791
+ settings_flags: Dict[str, Any] = {}
792
+ if settings_doc is not None:
793
+ for flag in ("trackChanges", "evenAndOddHeaders", "mirrorMargins",
794
+ "updateFields", "compatSetting", "footnotePr", "endnotePr"):
795
+ node = settings_doc.find(qn("w", flag))
796
+ settings_flags[flag] = node is not None
797
+
798
+ # --- packaging audit ------------------------------------------------
799
+
800
+ overrides = content_types["overrides"]
801
+ rel_targets = set()
802
+ for rel in rels_doc:
803
+ if rel["targetMode"] == "Internal":
804
+ target = rel["target"]
805
+ full = "word/" + target.lstrip("./") if not target.startswith("/") else target.lstrip("/")
806
+ rel_targets.add(full)
807
+ overrides_paths = {p.lstrip("/") for p in overrides.keys()}
808
+ for tgt in rel_targets:
809
+ if tgt not in overrides_paths and tgt + "" not in overrides_paths:
810
+ # allow non-override parts (e.g. images, fonts handled by Default content type)
811
+ pass
812
+
813
+ # ------------------------------------------------------------------
814
+ return {
815
+ "file": str(path),
816
+ "summary": {
817
+ "paragraphs": len(paragraphs),
818
+ "tables": len(tables),
819
+ "drawings": len(drawings),
820
+ "sections": len(sections),
821
+ "definedStyles": len(styles["byId"]),
822
+ "fields": len(all_fields),
823
+ "bookmarks": len(bookmarks["pairs"]) + len(bookmarks["orphanStarts"]),
824
+ "hyperlinks": len(hyperlinks),
825
+ "comments": len(comments),
826
+ "footnotes": footnotes_count,
827
+ "endnotes": endnotes_count,
828
+ "diagnostics": len(diagnostics),
829
+ },
830
+ "packaging": {
831
+ "contentTypes": content_types,
832
+ "packageRels": package_rels,
833
+ "documentRels": rels_doc,
834
+ "parts": collect_parts_inventory(archive),
835
+ },
836
+ "sections": sections,
837
+ "headerFooterParts": header_footer_parts,
838
+ "styles": {
839
+ "byId": styles["byId"],
840
+ "defaults": styles["defaults"],
841
+ "usedParagraphStyles": used_para_styles.most_common(),
842
+ "usedRunStyles": used_run_styles.most_common(),
843
+ "missingReferenced": missing_styles,
844
+ "definedButUnused": unused_defined,
845
+ "headingsWithoutOutlineLvl": heading_outline_audit,
846
+ "missing": styles["missing"],
847
+ },
848
+ "numbering": {
849
+ "abstractNums": numbering["abstractNums"],
850
+ "nums": numbering["nums"],
851
+ "usage": numbering_usage,
852
+ "missing": numbering["missing"],
853
+ },
854
+ "headings": heading_paragraphs,
855
+ "fields": {
856
+ "simple": simple_fields,
857
+ "complex": complex_fields,
858
+ "kindCounts": dict(field_kinds),
859
+ "kindCountsAllParts": dict(
860
+ field_kinds + sum(
861
+ (Counter(p.get("fieldKinds", {})) for p in header_footer_parts),
862
+ Counter(),
863
+ )
864
+ ),
865
+ "dirty": dirty_fields,
866
+ },
867
+ "bookmarks": bookmarks,
868
+ "hyperlinks": hyperlinks,
869
+ "comments": {
870
+ "definitions": comments,
871
+ "extended": comments_ext,
872
+ "rangeStartsInBody": len(comment_starts),
873
+ "rangeEndsInBody": len(comment_ends),
874
+ "referencesInBody": len(comment_refs),
875
+ "orphansInBody": comment_orphan_in_body,
876
+ "definedNotAnchored": comment_orphan_in_defs,
877
+ },
878
+ "revisions": {
879
+ "counts": revision_counts,
880
+ "actors": dict(revision_actors),
881
+ "dateRange": {"min": date_min, "max": date_max},
882
+ },
883
+ "contamination": {
884
+ **contamination_total,
885
+ "paragraphTotal": len(paragraphs),
886
+ "dirtyRatio": round(
887
+ contamination_total["paragraphsDirty"] / len(paragraphs), 4
888
+ ) if paragraphs else 0.0,
889
+ },
890
+ "settingsFlags": settings_flags,
891
+ "diagnostics": diagnostics,
892
+ }
893
+
894
+
895
+ # -- text rendering ------------------------------------------------------------
896
+
897
+ def render_text(report: Dict[str, Any]) -> str:
898
+ out: List[str] = []
899
+ s = report["summary"]
900
+ out.append(f"File: {report['file']}")
901
+ out.append(f"Paragraphs: {s['paragraphs']} Tables: {s['tables']} Drawings: {s['drawings']}")
902
+ out.append(f"Sections: {s['sections']} Defined styles: {s['definedStyles']}")
903
+ out.append(
904
+ f"Fields: {s['fields']} Bookmarks: {s['bookmarks']} Hyperlinks: {s['hyperlinks']}"
905
+ )
906
+ out.append(
907
+ f"Comments: {s['comments']} Footnotes: {s['footnotes']} Endnotes: {s['endnotes']}"
908
+ )
909
+ out.append(f"Diagnostics: {s['diagnostics']}")
910
+ out.append("")
911
+
912
+ out.append("Sections:")
913
+ for sect in report["sections"]:
914
+ margins = sect.get("margins") or {}
915
+ page = sect.get("pageSize") or {}
916
+ out.append(
917
+ f" #{sect['index']} type={sect['type']} "
918
+ f"page={page.get('widthMm')}x{page.get('heightMm')}mm "
919
+ f"margins(top/right/bottom/left)={margins.get('top')}/{margins.get('right')}/{margins.get('bottom')}/{margins.get('left')} "
920
+ f"titlePg={sect['titlePg']} cols={sect['columns']}"
921
+ )
922
+ for ref in sect["headerReferences"]:
923
+ out.append(f" header[{ref['type']}] -> {ref['rId']}")
924
+ for ref in sect["footerReferences"]:
925
+ out.append(f" footer[{ref['type']}] -> {ref['rId']}")
926
+ if report["headerFooterParts"]:
927
+ out.append("Header/footer parts:")
928
+ for p in report["headerFooterParts"]:
929
+ out.append(
930
+ f" {p['kind']:<6} rId={p['rId']:<6} target={p['target']} "
931
+ f"paragraphs={p['paragraphs']} fields={p['fields']} drawings={p['drawings']}"
932
+ )
933
+
934
+ out.append("")
935
+ out.append("Styles audit:")
936
+ out.append(f" used paragraph styles: {len(report['styles']['usedParagraphStyles'])}")
937
+ out.append(f" used run styles: {len(report['styles']['usedRunStyles'])}")
938
+ out.append(f" missing referenced: {report['styles']['missingReferenced']}")
939
+ out.append(f" defined-but-unused: {len(report['styles']['definedButUnused'])}")
940
+ out.append(f" headings missing outlineLvl: {report['styles']['headingsWithoutOutlineLvl']}")
941
+
942
+ out.append("")
943
+ out.append("Numbering:")
944
+ out.append(f" abstractNums: {len(report['numbering']['abstractNums'])}")
945
+ out.append(f" nums: {len(report['numbering']['nums'])}")
946
+ out.append(f" numbered paragraphs by numId: {report['numbering']['usage']['perNumId']}")
947
+
948
+ out.append("")
949
+ out.append("Field kinds: " + ", ".join(f"{k}={v}" for k, v in report["fields"]["kindCounts"].items()))
950
+ out.append(f"Dirty fields: {report['fields']['dirty']}")
951
+
952
+ out.append("")
953
+ out.append("Comments:")
954
+ out.append(
955
+ f" definitions={len(report['comments']['definitions'])} "
956
+ f"rangeStartsInBody={report['comments']['rangeStartsInBody']} "
957
+ f"orphansInBody={report['comments']['orphansInBody']}"
958
+ )
959
+
960
+ out.append("")
961
+ out.append("Contamination:")
962
+ c = report["contamination"]
963
+ out.append(
964
+ f" paragraphsDirty={c['paragraphsDirty']}/{c['paragraphTotal']} "
965
+ f"({c['dirtyRatio']*100:.1f}%) pPrDirect={c['pPrDirect']} rPrDirectRuns={c['rPrDirectRuns']}"
966
+ )
967
+
968
+ out.append("")
969
+ out.append("Diagnostics:")
970
+ if not report["diagnostics"]:
971
+ out.append(" (none)")
972
+ for d in report["diagnostics"]:
973
+ out.append(f" [{d['severity']}] {d['code']}: {d['message']}")
974
+
975
+ return "\n".join(out)
976
+
977
+
978
+ # -- CLI -----------------------------------------------------------------------
979
+
980
+ SECTION_KEYS = {
981
+ "summary", "packaging", "sections", "headerFooterParts", "styles",
982
+ "numbering", "headings", "fields", "bookmarks", "hyperlinks",
983
+ "comments", "revisions", "contamination", "settingsFlags", "diagnostics",
984
+ }
985
+
986
+
987
+ def main(argv: Optional[List[str]] = None) -> int:
988
+ parser = argparse.ArgumentParser(
989
+ description=(
990
+ "Deep DOCX structure analyzer. Primary structure-truth implementation; "
991
+ "no dotnet required."
992
+ )
993
+ )
994
+ parser.add_argument("input_path", help="Path to the .docx file")
995
+ parser.add_argument("--json", action="store_true", help="Emit JSON instead of text")
996
+ parser.add_argument(
997
+ "--section", default="",
998
+ help=(
999
+ "Comma-separated subset of top-level keys to include. "
1000
+ "Allowed: " + ",".join(sorted(SECTION_KEYS))
1001
+ ),
1002
+ )
1003
+ args = parser.parse_args(argv)
1004
+
1005
+ input_path = Path(args.input_path).expanduser().resolve()
1006
+ if not input_path.exists():
1007
+ raise RuntimeError(f"Input file does not exist: {input_path}")
1008
+ if input_path.suffix.lower() != ".docx":
1009
+ raise RuntimeError("read_docx_structure.py currently supports .docx only")
1010
+
1011
+ report = analyze(input_path)
1012
+
1013
+ if args.section:
1014
+ wanted = {s.strip() for s in args.section.split(",") if s.strip()}
1015
+ unknown = wanted - SECTION_KEYS
1016
+ if unknown:
1017
+ raise RuntimeError(f"Unknown --section keys: {sorted(unknown)}")
1018
+ report = {k: v for k, v in report.items() if k in wanted or k == "file"}
1019
+
1020
+ if args.json:
1021
+ print(json.dumps(report, ensure_ascii=False, indent=2))
1022
+ else:
1023
+ print(render_text(report))
1024
+ return 0
1025
+
1026
+
1027
+ if __name__ == "__main__":
1028
+ try:
1029
+ raise SystemExit(main())
1030
+ except Exception as exc: # pragma: no cover - CLI error path
1031
+ print(f"read_docx_structure.py failed: {exc}", file=sys.stderr)
1032
+ raise SystemExit(1)