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,1075 @@
1
+ """Content-truth extractor for DOCX files.
2
+
3
+ This script lifts ``READ_CONTENT`` from "concatenated paragraph text" to a real
4
+ content-truth view. It walks ``word/document.xml`` (and the supporting parts:
5
+ ``footnotes.xml``, ``endnotes.xml``, ``comments.xml``, ``header*.xml``,
6
+ ``footer*.xml`` plus the document relationships) and emits the body content in
7
+ reading order while keeping side channels addressable.
8
+
9
+ Output formats
10
+ ==============
11
+
12
+ ``--format text`` (default, back-compatible with the previous behaviour but
13
+ richer):
14
+
15
+ * one paragraph per line, with hyperlink targets shown as ``text (→ url)``
16
+ * footnote / endnote / comment markers shown inline as ``[fn:1]`` / ``[en:1]``
17
+ / ``[cmt:0]``
18
+ * tables rendered as ``cell | cell`` rows, one row per line
19
+ * tracked changes resolved by ``--revisions`` (default ``accept``: insertions
20
+ in, deletions out)
21
+ * a trailing "FOOTNOTES", "ENDNOTES", "COMMENTS", "HEADERS", "FOOTERS" and
22
+ "TEXT BOXES" section when those parts contain anything. These can be turned
23
+ off individually with ``--no-*`` flags.
24
+
25
+ ``--format json`` produces a structured document suitable for downstream
26
+ consumers (RAG, audit, diff). Schema (top-level keys):
27
+
28
+ * ``file`` — absolute path
29
+ * ``options`` — the options actually applied
30
+ * ``body`` — list of block dicts (``paragraph`` or ``table``) in reading order
31
+ * ``footnotes`` / ``endnotes`` / ``comments`` — lists with id, author, text
32
+ * ``hyperlinks`` — every external hyperlink reference with ``text`` + ``target``
33
+ * ``textboxes`` — text inside ``w:txbxContent`` / drawing shapes
34
+ * ``headers`` / ``footers`` — text per header/footer part with ``role`` (``default``/
35
+ ``first``/``even``)
36
+ * ``revisions`` — ``{policy, insertions, deletions, retainedInsertions,
37
+ retainedDeletions}``
38
+ * ``warnings`` — anything we deliberately did not silently drop
39
+
40
+ ``--format markdown`` produces a lightweight, human-readable Markdown digest.
41
+
42
+ The script is stdlib-only (zipfile + xml.etree) so it has no dependency on
43
+ ``python-docx`` and never silently degrades when that package is missing.
44
+ """
45
+
46
+ from __future__ import annotations
47
+
48
+ import argparse
49
+ import json
50
+ import sys
51
+ import xml.etree.ElementTree as ET
52
+ from dataclasses import dataclass, field
53
+ from pathlib import Path
54
+ from typing import Iterable, Optional
55
+ from zipfile import ZipFile
56
+
57
+ W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
58
+ R_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"
59
+ PKG_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
60
+ V_NS = "urn:schemas-microsoft-com:vml"
61
+ WPS_NS = "http://schemas.microsoft.com/office/word/2010/wordprocessingShape"
62
+ MC_NS = "http://schemas.openxmlformats.org/markup-compatibility/2006"
63
+
64
+ NS = {
65
+ "w": W_NS,
66
+ "r": R_NS,
67
+ "v": V_NS,
68
+ "wps": WPS_NS,
69
+ "mc": MC_NS,
70
+ "pkg": PKG_REL_NS,
71
+ }
72
+
73
+ W_TAGS = {
74
+ "p": f"{{{W_NS}}}p",
75
+ "tbl": f"{{{W_NS}}}tbl",
76
+ "tr": f"{{{W_NS}}}tr",
77
+ "tc": f"{{{W_NS}}}tc",
78
+ "r": f"{{{W_NS}}}r",
79
+ "t": f"{{{W_NS}}}t",
80
+ "delText": f"{{{W_NS}}}delText",
81
+ "tab": f"{{{W_NS}}}tab",
82
+ "br": f"{{{W_NS}}}br",
83
+ "ins": f"{{{W_NS}}}ins",
84
+ "del": f"{{{W_NS}}}del",
85
+ "hyperlink": f"{{{W_NS}}}hyperlink",
86
+ "footnoteReference": f"{{{W_NS}}}footnoteReference",
87
+ "endnoteReference": f"{{{W_NS}}}endnoteReference",
88
+ "commentRangeStart": f"{{{W_NS}}}commentRangeStart",
89
+ "commentRangeEnd": f"{{{W_NS}}}commentRangeEnd",
90
+ "commentReference": f"{{{W_NS}}}commentReference",
91
+ "fldSimple": f"{{{W_NS}}}fldSimple",
92
+ "instrText": f"{{{W_NS}}}instrText",
93
+ "txbxContent": f"{{{W_NS}}}txbxContent",
94
+ "drawing": f"{{{W_NS}}}drawing",
95
+ "pStyle": f"{{{W_NS}}}pStyle",
96
+ "pPr": f"{{{W_NS}}}pPr",
97
+ "rPr": f"{{{W_NS}}}rPr",
98
+ "sectPr": f"{{{W_NS}}}sectPr",
99
+ "type": f"{{{W_NS}}}type",
100
+ "headerReference": f"{{{W_NS}}}headerReference",
101
+ "footerReference": f"{{{W_NS}}}footerReference",
102
+ }
103
+
104
+ W_ATTR = {
105
+ "val": f"{{{W_NS}}}val",
106
+ "id": f"{{{W_NS}}}id",
107
+ "author": f"{{{W_NS}}}author",
108
+ "date": f"{{{W_NS}}}date",
109
+ "type": f"{{{W_NS}}}type",
110
+ "anchor": f"{{{W_NS}}}anchor",
111
+ "tooltip": f"{{{W_NS}}}tooltip",
112
+ "history": f"{{{W_NS}}}history",
113
+ "fldCharType": f"{{{W_NS}}}fldCharType",
114
+ }
115
+
116
+ R_ATTR = {
117
+ "id": f"{{{R_NS}}}id",
118
+ }
119
+
120
+
121
+ # ---------------------------------------------------------------------------
122
+ # Options
123
+ # ---------------------------------------------------------------------------
124
+
125
+
126
+ @dataclass
127
+ class Options:
128
+ fmt: str = "text"
129
+ revisions: str = "accept" # accept | reject | raw
130
+ include_footnotes: bool = True
131
+ include_endnotes: bool = True
132
+ include_comments: bool = True
133
+ include_hyperlinks: bool = True
134
+ include_textboxes: bool = True
135
+ include_headers: bool = False
136
+ include_footers: bool = False
137
+ inline_comment_marker: bool = True
138
+
139
+ def to_dict(self) -> dict:
140
+ return {
141
+ "format": self.fmt,
142
+ "revisions": self.revisions,
143
+ "includeFootnotes": self.include_footnotes,
144
+ "includeEndnotes": self.include_endnotes,
145
+ "includeComments": self.include_comments,
146
+ "includeHyperlinks": self.include_hyperlinks,
147
+ "includeTextboxes": self.include_textboxes,
148
+ "includeHeaders": self.include_headers,
149
+ "includeFooters": self.include_footers,
150
+ }
151
+
152
+
153
+ # ---------------------------------------------------------------------------
154
+ # Low-level helpers
155
+ # ---------------------------------------------------------------------------
156
+
157
+
158
+ def _read_xml(archive: ZipFile, name: str) -> Optional[ET.Element]:
159
+ try:
160
+ with archive.open(name) as handle:
161
+ return ET.fromstring(handle.read())
162
+ except KeyError:
163
+ return None
164
+ except ET.ParseError:
165
+ return None
166
+
167
+
168
+ def _wval(node: Optional[ET.Element], default: Optional[str] = None) -> Optional[str]:
169
+ if node is None:
170
+ return default
171
+ return node.get(W_ATTR["val"]) or node.get("val") or default
172
+
173
+
174
+ def _strip_alternate_content(root: ET.Element) -> None:
175
+ """Resolve mc:AlternateContent so we walk the WML choice (preferred) and skip
176
+ fallback duplicates. Without this, drawing text inside ``mc:Fallback`` gets
177
+ counted twice. Loops until no AlternateContent remains (handles nesting)."""
178
+
179
+ while True:
180
+ parent_map = {child: parent for parent in root.iter() for child in parent}
181
+ targets = [el for el in root.iter() if el.tag == f"{{{MC_NS}}}AlternateContent"]
182
+ if not targets:
183
+ return
184
+ for ac in targets:
185
+ parent = parent_map.get(ac)
186
+ if parent is None:
187
+ continue
188
+ idx = list(parent).index(ac)
189
+ choice = ac.find(f"{{{MC_NS}}}Choice")
190
+ chosen = choice if choice is not None else ac.find(f"{{{MC_NS}}}Fallback")
191
+ replacements = list(chosen) if chosen is not None else []
192
+ parent.remove(ac)
193
+ for offset, child in enumerate(replacements):
194
+ parent.insert(idx + offset, child)
195
+
196
+
197
+ def _load_relationships(archive: ZipFile, part_path: str) -> dict[str, dict]:
198
+ """Return {rId: {"target": str, "type": str, "mode": str}} for a given part."""
199
+
200
+ rel_path = _rel_path_for(part_path)
201
+ root = _read_xml(archive, rel_path)
202
+ if root is None:
203
+ return {}
204
+ rels: dict[str, dict] = {}
205
+ for rel in root.findall(f"{{{PKG_REL_NS}}}Relationship"):
206
+ rid = rel.get("Id")
207
+ if not rid:
208
+ continue
209
+ rels[rid] = {
210
+ "target": rel.get("Target") or "",
211
+ "type": rel.get("Type") or "",
212
+ "mode": rel.get("TargetMode") or "Internal",
213
+ }
214
+ return rels
215
+
216
+
217
+ def _rel_path_for(part_path: str) -> str:
218
+ parts = part_path.rsplit("/", 1)
219
+ if len(parts) == 1:
220
+ return f"_rels/{part_path}.rels"
221
+ return f"{parts[0]}/_rels/{parts[1]}.rels"
222
+
223
+
224
+ # ---------------------------------------------------------------------------
225
+ # Run-level extraction (revisions, hyperlinks, footnotes, comments)
226
+ # ---------------------------------------------------------------------------
227
+
228
+
229
+ @dataclass
230
+ class ParagraphRun:
231
+ text: str
232
+ revision: str = "none" # none | ins | del
233
+ in_hyperlink: Optional[str] = None # hyperlink id key (for grouping)
234
+
235
+
236
+ @dataclass
237
+ class Hyperlink:
238
+ text: str
239
+ target: str
240
+ anchor: Optional[str] = None
241
+ tooltip: Optional[str] = None
242
+
243
+
244
+ @dataclass
245
+ class FieldEvent:
246
+ kind: str # field-begin | field-instr | field-end
247
+ text: str = ""
248
+
249
+
250
+ @dataclass
251
+ class ParagraphBlock:
252
+ style: Optional[str]
253
+ style_name: Optional[str]
254
+ text: str
255
+ runs: list[dict]
256
+ hyperlinks: list[Hyperlink] = field(default_factory=list)
257
+ footnote_refs: list[str] = field(default_factory=list)
258
+ endnote_refs: list[str] = field(default_factory=list)
259
+ comment_refs: list[str] = field(default_factory=list)
260
+ fields: list[str] = field(default_factory=list)
261
+
262
+
263
+ @dataclass
264
+ class TableBlock:
265
+ rows: list[list[ParagraphBlock]]
266
+
267
+
268
+ @dataclass
269
+ class ExtractionResult:
270
+ body: list[object]
271
+ footnotes: list[dict]
272
+ endnotes: list[dict]
273
+ comments: list[dict]
274
+ hyperlinks: list[Hyperlink]
275
+ textboxes: list[dict]
276
+ headers: list[dict]
277
+ footers: list[dict]
278
+ revisions: dict
279
+ warnings: list[str]
280
+ style_names: dict[str, str]
281
+
282
+
283
+ # ---------------------------------------------------------------------------
284
+ # Paragraph walker
285
+ # ---------------------------------------------------------------------------
286
+
287
+
288
+ class ParagraphWalker:
289
+ """Walk a ``w:p`` element and emit a structured ``ParagraphBlock``.
290
+
291
+ The walker honours the requested revision policy and reports inline side
292
+ channels (hyperlinks, footnote/endnote/comment references) via the
293
+ paragraph's lists. Text from drawing shapes / text boxes is *not* inlined
294
+ here — the caller harvests those globally so they are addressable on their
295
+ own.
296
+ """
297
+
298
+ def __init__(self, options: Options, rels: dict[str, dict], style_names: dict[str, str]):
299
+ self.options = options
300
+ self.rels = rels
301
+ self.style_names = style_names
302
+
303
+ # ------------------------------------------------------------------ runs
304
+
305
+ def _emit_text(self, runs: list[ParagraphRun], text: str, revision: str, link_key: Optional[str]) -> None:
306
+ if text == "":
307
+ return
308
+ # merge with previous run when revision/link unchanged
309
+ if runs and runs[-1].revision == revision and runs[-1].in_hyperlink == link_key:
310
+ runs[-1].text += text
311
+ return
312
+ runs.append(ParagraphRun(text=text, revision=revision, in_hyperlink=link_key))
313
+
314
+ def _walk_run(
315
+ self,
316
+ run: ET.Element,
317
+ runs: list[ParagraphRun],
318
+ revision: str,
319
+ link_key: Optional[str],
320
+ block: ParagraphBlock,
321
+ ) -> None:
322
+ for child in run:
323
+ tag = child.tag
324
+ if tag == W_TAGS["t"]:
325
+ self._emit_text(runs, child.text or "", revision, link_key)
326
+ elif tag == W_TAGS["delText"]:
327
+ # only surface deletion text when caller asked for raw or reject
328
+ if revision == "del" and self.options.revisions in {"raw", "reject"}:
329
+ self._emit_text(runs, child.text or "", "del", link_key)
330
+ elif tag == W_TAGS["tab"]:
331
+ self._emit_text(runs, "\t", revision, link_key)
332
+ elif tag == W_TAGS["br"]:
333
+ self._emit_text(runs, "\n", revision, link_key)
334
+ elif tag == W_TAGS["footnoteReference"]:
335
+ fid = child.get(W_ATTR["id"])
336
+ if fid:
337
+ block.footnote_refs.append(fid)
338
+ if self.options.include_footnotes:
339
+ self._emit_text(runs, f"[fn:{fid}]", revision, link_key)
340
+ elif tag == W_TAGS["endnoteReference"]:
341
+ eid = child.get(W_ATTR["id"])
342
+ if eid:
343
+ block.endnote_refs.append(eid)
344
+ if self.options.include_endnotes:
345
+ self._emit_text(runs, f"[en:{eid}]", revision, link_key)
346
+ elif tag == W_TAGS["commentReference"]:
347
+ cid = child.get(W_ATTR["id"])
348
+ if cid:
349
+ block.comment_refs.append(cid)
350
+ if self.options.include_comments and self.options.inline_comment_marker:
351
+ self._emit_text(runs, f"[cmt:{cid}]", revision, link_key)
352
+ elif tag == W_TAGS["instrText"]:
353
+ instr = (child.text or "").strip()
354
+ if instr:
355
+ block.fields.append(instr)
356
+ else:
357
+ # ignore unknown run children silently — they cannot carry text
358
+ pass
359
+
360
+ # -------------------------------------------------------------- paragraph
361
+
362
+ def _walk_paragraph_children(
363
+ self,
364
+ node: ET.Element,
365
+ runs: list[ParagraphRun],
366
+ revision: str,
367
+ link_key: Optional[str],
368
+ block: ParagraphBlock,
369
+ ) -> None:
370
+ for child in node:
371
+ tag = child.tag
372
+ if tag == W_TAGS["pPr"]:
373
+ continue
374
+ if tag == W_TAGS["r"]:
375
+ self._walk_run(child, runs, revision, link_key, block)
376
+ elif tag == W_TAGS["ins"]:
377
+ if self.options.revisions == "reject":
378
+ # discard inserted text in reject mode
379
+ continue
380
+ self._walk_paragraph_children(child, runs, "ins", link_key, block)
381
+ elif tag == W_TAGS["del"]:
382
+ if self.options.revisions == "accept":
383
+ # accepted means deletions are gone
384
+ continue
385
+ self._walk_paragraph_children(child, runs, "del", link_key, block)
386
+ elif tag == W_TAGS["hyperlink"]:
387
+ rid = child.get(R_ATTR["id"])
388
+ anchor = child.get(W_ATTR["anchor"])
389
+ tooltip = child.get(W_ATTR["tooltip"])
390
+ target: Optional[str] = None
391
+ if rid and rid in self.rels:
392
+ target = self.rels[rid].get("target")
393
+ if anchor and not target:
394
+ target = f"#{anchor}"
395
+ key = f"{rid or ''}|{anchor or ''}"
396
+ # collect text that lives inside this hyperlink
397
+ inner_runs: list[ParagraphRun] = []
398
+ self._walk_paragraph_children(child, inner_runs, revision, key, block)
399
+ # merge into outer run list with hyperlink marker
400
+ for run in inner_runs:
401
+ self._emit_text(runs, run.text, run.revision, key)
402
+ # record hyperlink entry once
403
+ hl_text = "".join(r.text for r in inner_runs)
404
+ if hl_text or target:
405
+ block.hyperlinks.append(
406
+ Hyperlink(text=hl_text, target=target or "", anchor=anchor, tooltip=tooltip)
407
+ )
408
+ elif tag == W_TAGS["fldSimple"]:
409
+ instr = child.get(f"{{{W_NS}}}instr") or ""
410
+ if instr.strip():
411
+ block.fields.append(instr.strip())
412
+ # field result lives as run children below
413
+ self._walk_paragraph_children(child, runs, revision, link_key, block)
414
+ elif tag == W_TAGS["drawing"]:
415
+ # Drawing-shape text (text boxes) is harvested globally so it can
416
+ # be addressed on its own. Skip the subtree here to avoid double
417
+ # counting.
418
+ continue
419
+ elif tag == W_TAGS["txbxContent"]:
420
+ continue
421
+ else:
422
+ # recurse so that <w:smartTag>, <w:bdo>, <w:dir>, etc. surface their text
423
+ self._walk_paragraph_children(child, runs, revision, link_key, block)
424
+
425
+ def walk(self, paragraph: ET.Element) -> ParagraphBlock:
426
+ ppr = paragraph.find(W_TAGS["pPr"])
427
+ style_id: Optional[str] = None
428
+ if ppr is not None:
429
+ pstyle = ppr.find(W_TAGS["pStyle"])
430
+ style_id = _wval(pstyle)
431
+ style_name = self.style_names.get(style_id or "")
432
+ block = ParagraphBlock(style=style_id, style_name=style_name, text="", runs=[])
433
+ runs: list[ParagraphRun] = []
434
+ self._walk_paragraph_children(paragraph, runs, "none", None, block)
435
+ block.runs = [
436
+ {"text": r.text, "revision": r.revision, "hyperlinkKey": r.in_hyperlink}
437
+ for r in runs
438
+ if r.text
439
+ ]
440
+ block.text = "".join(r.text for r in runs)
441
+ return block
442
+
443
+
444
+ # ---------------------------------------------------------------------------
445
+ # Side-channel parts: footnotes / endnotes / comments / headers / footers
446
+ # ---------------------------------------------------------------------------
447
+
448
+
449
+ def _collect_footnote_like(
450
+ archive: ZipFile,
451
+ part_name: str,
452
+ container_local: str,
453
+ options: Options,
454
+ style_names: dict[str, str],
455
+ ) -> list[dict]:
456
+ root = _read_xml(archive, part_name)
457
+ if root is None:
458
+ return []
459
+ _strip_alternate_content(root)
460
+ rels = _load_relationships(archive, part_name)
461
+ walker = ParagraphWalker(options, rels, style_names)
462
+ out: list[dict] = []
463
+ container_tag = f"{{{W_NS}}}{container_local}"
464
+ for entry in root.findall(container_tag):
465
+ fid = entry.get(W_ATTR["id"])
466
+ ftype = entry.get(W_ATTR["type"]) # "separator" / "continuationSeparator" / "normal"
467
+ if ftype in {"separator", "continuationSeparator"}:
468
+ continue
469
+ paragraphs = entry.findall(f".//{W_TAGS['p']}")
470
+ text = "\n".join(walker.walk(p).text.strip() for p in paragraphs).strip()
471
+ if not text:
472
+ continue
473
+ out.append({"id": fid, "type": ftype or "normal", "text": text})
474
+ return out
475
+
476
+
477
+ def _collect_comments(
478
+ archive: ZipFile, options: Options, style_names: dict[str, str]
479
+ ) -> list[dict]:
480
+ root = _read_xml(archive, "word/comments.xml")
481
+ if root is None:
482
+ return []
483
+ _strip_alternate_content(root)
484
+ rels = _load_relationships(archive, "word/comments.xml")
485
+ walker = ParagraphWalker(options, rels, style_names)
486
+ out: list[dict] = []
487
+ for entry in root.findall(f"{{{W_NS}}}comment"):
488
+ cid = entry.get(W_ATTR["id"])
489
+ author = entry.get(W_ATTR["author"])
490
+ date = entry.get(W_ATTR["date"])
491
+ paragraphs = entry.findall(f".//{W_TAGS['p']}")
492
+ text = "\n".join(walker.walk(p).text.strip() for p in paragraphs).strip()
493
+ out.append(
494
+ {
495
+ "id": cid,
496
+ "author": author,
497
+ "date": date,
498
+ "text": text,
499
+ }
500
+ )
501
+ return out
502
+
503
+
504
+ def _collect_headers_or_footers(
505
+ archive: ZipFile,
506
+ document_rels: dict[str, dict],
507
+ document_root: ET.Element,
508
+ kind: str, # "header" or "footer"
509
+ options: Options,
510
+ style_names: dict[str, str],
511
+ ) -> list[dict]:
512
+ """Walk every header/footer part referenced by every section, preserving
513
+ section index and reference type (default/first/even)."""
514
+
515
+ ref_tag = W_TAGS["headerReference" if kind == "header" else "footerReference"]
516
+ parts: list[dict] = []
517
+ for sect_idx, sect in enumerate(document_root.findall(f".//{W_TAGS['sectPr']}")):
518
+ for ref in sect.findall(ref_tag):
519
+ rid = ref.get(R_ATTR["id"])
520
+ ref_type = ref.get(W_ATTR["type"]) or "default"
521
+ if not rid or rid not in document_rels:
522
+ continue
523
+ target = document_rels[rid]["target"]
524
+ part_name = _resolve_target("word/document.xml", target)
525
+ root = _read_xml(archive, part_name)
526
+ if root is None:
527
+ continue
528
+ _strip_alternate_content(root)
529
+ rels = _load_relationships(archive, part_name)
530
+ walker = ParagraphWalker(options, rels, style_names)
531
+ paragraphs = root.findall(f".//{W_TAGS['p']}")
532
+ text = "\n".join(walker.walk(p).text.strip() for p in paragraphs).strip()
533
+ parts.append(
534
+ {
535
+ "section": sect_idx,
536
+ "kind": kind,
537
+ "role": ref_type,
538
+ "part": part_name,
539
+ "text": text,
540
+ }
541
+ )
542
+ return parts
543
+
544
+
545
+ def _resolve_target(source_part: str, target: str) -> str:
546
+ if target.startswith("/"):
547
+ return target.lstrip("/")
548
+ base = source_part.rsplit("/", 1)[0]
549
+ pieces = []
550
+ for piece in (base + "/" + target).split("/"):
551
+ if piece in {"", "."}:
552
+ continue
553
+ if piece == "..":
554
+ if pieces:
555
+ pieces.pop()
556
+ else:
557
+ pieces.append(piece)
558
+ return "/".join(pieces)
559
+
560
+
561
+ # ---------------------------------------------------------------------------
562
+ # Body walker
563
+ # ---------------------------------------------------------------------------
564
+
565
+
566
+ def _collect_textboxes(root: ET.Element, walker: ParagraphWalker, location: str) -> list[dict]:
567
+ out: list[dict] = []
568
+ for txbx in root.findall(f".//{W_TAGS['txbxContent']}"):
569
+ paragraphs = txbx.findall(f".//{W_TAGS['p']}")
570
+ text = "\n".join(walker.walk(p).text.strip() for p in paragraphs).strip()
571
+ if text:
572
+ out.append({"location": location, "text": text})
573
+ return out
574
+
575
+
576
+ def _walk_body(
577
+ body: ET.Element, walker: ParagraphWalker
578
+ ) -> tuple[list[object], int, int, int, int]:
579
+ """Walk body in order. Returns (blocks, raw_ins_count, raw_del_count,
580
+ retained_ins, retained_del)."""
581
+
582
+ blocks: list[object] = []
583
+ raw_ins = len(body.findall(f".//{W_TAGS['ins']}"))
584
+ raw_del = len(body.findall(f".//{W_TAGS['del']}"))
585
+
586
+ # we count "retained" by re-walking with a probe walker after the main walk
587
+ # (cheap because each paragraph is small). Actual retention happens inline
588
+ # inside walker.walk based on options.revisions.
589
+ retained_ins = 0
590
+ retained_del = 0
591
+
592
+ def _on_paragraph(p: ET.Element) -> ParagraphBlock:
593
+ nonlocal retained_ins, retained_del
594
+ block = walker.walk(p)
595
+ retained_ins += sum(1 for r in block.runs if r["revision"] == "ins")
596
+ retained_del += sum(1 for r in block.runs if r["revision"] == "del")
597
+ return block
598
+
599
+ for child in body:
600
+ if child.tag == W_TAGS["p"]:
601
+ blocks.append({"kind": "paragraph", "block": _on_paragraph(child)})
602
+ elif child.tag == W_TAGS["tbl"]:
603
+ rows: list[list[ParagraphBlock]] = []
604
+ for tr in child.findall(W_TAGS["tr"]):
605
+ row: list[ParagraphBlock] = []
606
+ for tc in tr.findall(W_TAGS["tc"]):
607
+ cell_blocks: list[ParagraphBlock] = []
608
+ for cp in tc.findall(W_TAGS["p"]):
609
+ cell_blocks.append(_on_paragraph(cp))
610
+ row.append(cell_blocks)
611
+ rows.append(row)
612
+ blocks.append({"kind": "table", "rows": rows})
613
+ elif child.tag == W_TAGS["sectPr"]:
614
+ continue
615
+ else:
616
+ # fall back: collect any paragraphs nested inside (e.g. SDT containers)
617
+ for p in child.findall(f".//{W_TAGS['p']}"):
618
+ blocks.append({"kind": "paragraph", "block": _on_paragraph(p)})
619
+
620
+ return blocks, raw_ins, raw_del, retained_ins, retained_del
621
+
622
+
623
+ def _load_style_names(archive: ZipFile) -> dict[str, str]:
624
+ root = _read_xml(archive, "word/styles.xml")
625
+ if root is None:
626
+ return {}
627
+ out: dict[str, str] = {}
628
+ for style in root.findall(f"{{{W_NS}}}style"):
629
+ sid = style.get(f"{{{W_NS}}}styleId") or style.get("styleId")
630
+ if not sid:
631
+ continue
632
+ name_el = style.find(f"{{{W_NS}}}name")
633
+ name = _wval(name_el)
634
+ if name:
635
+ out[sid] = name
636
+ return out
637
+
638
+
639
+ # ---------------------------------------------------------------------------
640
+ # Top-level extraction
641
+ # ---------------------------------------------------------------------------
642
+
643
+
644
+ def extract(path: Path, options: Options) -> ExtractionResult:
645
+ warnings: list[str] = []
646
+ with ZipFile(path, "r") as archive:
647
+ document_root = _read_xml(archive, "word/document.xml")
648
+ if document_root is None:
649
+ raise RuntimeError("Not a valid DOCX: word/document.xml missing")
650
+ _strip_alternate_content(document_root)
651
+ body = document_root.find(f"{{{W_NS}}}body")
652
+ if body is None:
653
+ raise RuntimeError("Document body missing")
654
+
655
+ style_names = _load_style_names(archive)
656
+ document_rels = _load_relationships(archive, "word/document.xml")
657
+
658
+ walker = ParagraphWalker(options, document_rels, style_names)
659
+ body_blocks, raw_ins, raw_del, ret_ins, ret_del = _walk_body(body, walker)
660
+
661
+ # gather hyperlinks across body in walk order (for stable id-less listing)
662
+ all_hyperlinks: list[Hyperlink] = []
663
+ for entry in body_blocks:
664
+ if entry["kind"] == "paragraph":
665
+ all_hyperlinks.extend(entry["block"].hyperlinks)
666
+ else:
667
+ for row in entry["rows"]:
668
+ for cell in row:
669
+ for cp in cell:
670
+ all_hyperlinks.extend(cp.hyperlinks)
671
+
672
+ textboxes: list[dict] = []
673
+ if options.include_textboxes:
674
+ textboxes = _collect_textboxes(document_root, walker, "body")
675
+
676
+ footnotes: list[dict] = []
677
+ if options.include_footnotes:
678
+ footnotes = _collect_footnote_like(
679
+ archive, "word/footnotes.xml", "footnote", options, style_names
680
+ )
681
+
682
+ endnotes: list[dict] = []
683
+ if options.include_endnotes:
684
+ endnotes = _collect_footnote_like(
685
+ archive, "word/endnotes.xml", "endnote", options, style_names
686
+ )
687
+
688
+ comments: list[dict] = []
689
+ if options.include_comments:
690
+ comments = _collect_comments(archive, options, style_names)
691
+
692
+ headers: list[dict] = []
693
+ if options.include_headers:
694
+ headers = _collect_headers_or_footers(
695
+ archive, document_rels, document_root, "header", options, style_names
696
+ )
697
+
698
+ footers: list[dict] = []
699
+ if options.include_footers:
700
+ footers = _collect_headers_or_footers(
701
+ archive, document_rels, document_root, "footer", options, style_names
702
+ )
703
+
704
+ # warn loudly when we drop something the user might care about
705
+ if options.revisions == "accept" and raw_del > 0:
706
+ warnings.append(
707
+ f"revisions policy 'accept' dropped {raw_del} <w:del> block(s); "
708
+ "use --revisions raw to retain them"
709
+ )
710
+ if options.revisions == "reject" and raw_ins > 0:
711
+ warnings.append(
712
+ f"revisions policy 'reject' dropped {raw_ins} <w:ins> block(s); "
713
+ "use --revisions raw to retain them"
714
+ )
715
+ if not options.include_footnotes and footnotes_referenced(body_blocks):
716
+ warnings.append("footnote references in body were ignored (--no-footnotes)")
717
+ if not options.include_endnotes and endnotes_referenced(body_blocks):
718
+ warnings.append("endnote references in body were ignored (--no-endnotes)")
719
+ if not options.include_comments and comments_referenced(body_blocks):
720
+ warnings.append("comment references in body were ignored (--no-comments)")
721
+
722
+ return ExtractionResult(
723
+ body=body_blocks,
724
+ footnotes=footnotes,
725
+ endnotes=endnotes,
726
+ comments=comments,
727
+ hyperlinks=all_hyperlinks,
728
+ textboxes=textboxes,
729
+ headers=headers,
730
+ footers=footers,
731
+ revisions={
732
+ "policy": options.revisions,
733
+ "rawInsertions": raw_ins,
734
+ "rawDeletions": raw_del,
735
+ "retainedInsertions": ret_ins,
736
+ "retainedDeletions": ret_del,
737
+ },
738
+ warnings=warnings,
739
+ style_names=style_names,
740
+ )
741
+
742
+
743
+ def footnotes_referenced(blocks: Iterable[object]) -> bool:
744
+ for entry in blocks:
745
+ if entry["kind"] == "paragraph" and entry["block"].footnote_refs:
746
+ return True
747
+ if entry["kind"] == "table":
748
+ for row in entry["rows"]:
749
+ for cell in row:
750
+ for cp in cell:
751
+ if cp.footnote_refs:
752
+ return True
753
+ return False
754
+
755
+
756
+ def endnotes_referenced(blocks: Iterable[object]) -> bool:
757
+ for entry in blocks:
758
+ if entry["kind"] == "paragraph" and entry["block"].endnote_refs:
759
+ return True
760
+ if entry["kind"] == "table":
761
+ for row in entry["rows"]:
762
+ for cell in row:
763
+ for cp in cell:
764
+ if cp.endnote_refs:
765
+ return True
766
+ return False
767
+
768
+
769
+ def comments_referenced(blocks: Iterable[object]) -> bool:
770
+ for entry in blocks:
771
+ if entry["kind"] == "paragraph" and entry["block"].comment_refs:
772
+ return True
773
+ if entry["kind"] == "table":
774
+ for row in entry["rows"]:
775
+ for cell in row:
776
+ for cp in cell:
777
+ if cp.comment_refs:
778
+ return True
779
+ return False
780
+
781
+
782
+ # ---------------------------------------------------------------------------
783
+ # Renderers
784
+ # ---------------------------------------------------------------------------
785
+
786
+
787
+ def _paragraph_to_text(p: ParagraphBlock, options: Options) -> str:
788
+ text = p.text
789
+ if options.include_hyperlinks and p.hyperlinks:
790
+ suffix_parts = []
791
+ for hl in p.hyperlinks:
792
+ target = hl.target or (f"#{hl.anchor}" if hl.anchor else "")
793
+ if not target:
794
+ continue
795
+ label = hl.text or target
796
+ # rewrite link inline — replace first occurrence of label with `label (→ target)`
797
+ if label and label in text:
798
+ text = text.replace(label, f"{label} (→ {target})", 1)
799
+ else:
800
+ suffix_parts.append(f"{label} (→ {target})")
801
+ if suffix_parts:
802
+ text = text + " " + " ".join(suffix_parts)
803
+ return text.strip()
804
+
805
+
806
+ def render_text(result: ExtractionResult, options: Options) -> str:
807
+ out: list[str] = []
808
+ for entry in result.body:
809
+ if entry["kind"] == "paragraph":
810
+ line = _paragraph_to_text(entry["block"], options)
811
+ if line:
812
+ out.append(line)
813
+ else:
814
+ for row in entry["rows"]:
815
+ cells = []
816
+ for cell in row:
817
+ cell_text = " ".join(_paragraph_to_text(cp, options) for cp in cell).strip()
818
+ cells.append(cell_text)
819
+ if any(cells):
820
+ out.append(" | ".join(cells))
821
+
822
+ if options.include_footnotes and result.footnotes:
823
+ out.append("")
824
+ out.append("FOOTNOTES")
825
+ for fn in result.footnotes:
826
+ out.append(f" [fn:{fn['id']}] {fn['text']}")
827
+ if options.include_endnotes and result.endnotes:
828
+ out.append("")
829
+ out.append("ENDNOTES")
830
+ for en in result.endnotes:
831
+ out.append(f" [en:{en['id']}] {en['text']}")
832
+ if options.include_comments and result.comments:
833
+ out.append("")
834
+ out.append("COMMENTS")
835
+ for cm in result.comments:
836
+ who = cm.get("author") or "anon"
837
+ when = cm.get("date") or "?"
838
+ out.append(f" [cmt:{cm['id']}] ({who}, {when}) {cm['text']}")
839
+ if options.include_headers and result.headers:
840
+ out.append("")
841
+ out.append("HEADERS")
842
+ for hd in result.headers:
843
+ if hd["text"]:
844
+ out.append(f" section={hd['section']} role={hd['role']} :: {hd['text']}")
845
+ if options.include_footers and result.footers:
846
+ out.append("")
847
+ out.append("FOOTERS")
848
+ for ft in result.footers:
849
+ if ft["text"]:
850
+ out.append(f" section={ft['section']} role={ft['role']} :: {ft['text']}")
851
+ if options.include_textboxes and result.textboxes:
852
+ out.append("")
853
+ out.append("TEXT BOXES")
854
+ for tb in result.textboxes:
855
+ out.append(f" ({tb['location']}) {tb['text']}")
856
+ if result.warnings:
857
+ out.append("")
858
+ out.append("WARNINGS")
859
+ for w in result.warnings:
860
+ out.append(f" {w}")
861
+ return "\n".join(line for line in out).strip() + ("\n" if out else "")
862
+
863
+
864
+ def render_markdown(result: ExtractionResult, options: Options) -> str:
865
+ out: list[str] = []
866
+ for entry in result.body:
867
+ if entry["kind"] == "paragraph":
868
+ block = entry["block"]
869
+ text = _paragraph_to_text(block, options)
870
+ if not text:
871
+ continue
872
+ style = (block.style or "").lower()
873
+ if "heading" in style or style in {"title", "subtitle"}:
874
+ level = 1
875
+ for ch in style[::-1]:
876
+ if ch.isdigit():
877
+ level = int(ch)
878
+ break
879
+ out.append(f"{'#' * max(1, min(level, 6))} {text}")
880
+ else:
881
+ out.append(text)
882
+ out.append("")
883
+ else:
884
+ rows = entry["rows"]
885
+ if not rows:
886
+ continue
887
+ md_rows = []
888
+ for row in rows:
889
+ md_rows.append(
890
+ "| "
891
+ + " | ".join(
892
+ " ".join(_paragraph_to_text(cp, options) for cp in cell).replace("|", "\\|")
893
+ for cell in row
894
+ )
895
+ + " |"
896
+ )
897
+ if md_rows:
898
+ header_cells = len(rows[0])
899
+ out.append(md_rows[0])
900
+ out.append("|" + "|".join([" --- "] * header_cells) + "|")
901
+ out.extend(md_rows[1:])
902
+ out.append("")
903
+
904
+ if options.include_footnotes and result.footnotes:
905
+ out.append("## Footnotes")
906
+ for fn in result.footnotes:
907
+ out.append(f"- **fn:{fn['id']}** — {fn['text']}")
908
+ out.append("")
909
+ if options.include_endnotes and result.endnotes:
910
+ out.append("## Endnotes")
911
+ for en in result.endnotes:
912
+ out.append(f"- **en:{en['id']}** — {en['text']}")
913
+ out.append("")
914
+ if options.include_comments and result.comments:
915
+ out.append("## Comments")
916
+ for cm in result.comments:
917
+ out.append(
918
+ f"- **cmt:{cm['id']}** ({cm.get('author') or 'anon'}, {cm.get('date') or '?'}): {cm['text']}"
919
+ )
920
+ out.append("")
921
+ return "\n".join(out).strip() + "\n"
922
+
923
+
924
+ def render_json(result: ExtractionResult, options: Options, path: Path) -> str:
925
+ body_payload: list[dict] = []
926
+ for entry in result.body:
927
+ if entry["kind"] == "paragraph":
928
+ block: ParagraphBlock = entry["block"]
929
+ body_payload.append(
930
+ {
931
+ "kind": "paragraph",
932
+ "style": block.style,
933
+ "styleName": block.style_name,
934
+ "text": block.text,
935
+ "runs": block.runs,
936
+ "hyperlinks": [hl.__dict__ for hl in block.hyperlinks],
937
+ "footnoteRefs": block.footnote_refs,
938
+ "endnoteRefs": block.endnote_refs,
939
+ "commentRefs": block.comment_refs,
940
+ "fields": block.fields,
941
+ }
942
+ )
943
+ else:
944
+ body_payload.append(
945
+ {
946
+ "kind": "table",
947
+ "rows": [
948
+ [
949
+ [
950
+ {
951
+ "style": cp.style,
952
+ "styleName": cp.style_name,
953
+ "text": cp.text,
954
+ "footnoteRefs": cp.footnote_refs,
955
+ "endnoteRefs": cp.endnote_refs,
956
+ "commentRefs": cp.comment_refs,
957
+ "hyperlinks": [hl.__dict__ for hl in cp.hyperlinks],
958
+ }
959
+ for cp in cell
960
+ ]
961
+ for cell in row
962
+ ]
963
+ for row in entry["rows"]
964
+ ],
965
+ }
966
+ )
967
+ payload = {
968
+ "file": str(path),
969
+ "options": options.to_dict(),
970
+ "body": body_payload,
971
+ "footnotes": result.footnotes,
972
+ "endnotes": result.endnotes,
973
+ "comments": result.comments,
974
+ "hyperlinks": [hl.__dict__ for hl in result.hyperlinks],
975
+ "textboxes": result.textboxes,
976
+ "headers": result.headers,
977
+ "footers": result.footers,
978
+ "revisions": result.revisions,
979
+ "warnings": result.warnings,
980
+ }
981
+ return json.dumps(payload, ensure_ascii=False, indent=2)
982
+
983
+
984
+ # ---------------------------------------------------------------------------
985
+ # CLI
986
+ # ---------------------------------------------------------------------------
987
+
988
+
989
+ def _build_parser() -> argparse.ArgumentParser:
990
+ parser = argparse.ArgumentParser(
991
+ description="Extract content-truth view of a DOCX (text/json/markdown).",
992
+ )
993
+ parser.add_argument("input_path", help="Path to the .docx file")
994
+ parser.add_argument(
995
+ "--format",
996
+ choices=["text", "json", "markdown"],
997
+ default="text",
998
+ help="Output format. Default: text (back-compat).",
999
+ )
1000
+ parser.add_argument(
1001
+ "--revisions",
1002
+ choices=["accept", "reject", "raw"],
1003
+ default="accept",
1004
+ help=(
1005
+ "Track-changes read policy. accept: keep insertions, drop deletions. "
1006
+ "reject: drop insertions, keep deletions. raw: keep both."
1007
+ ),
1008
+ )
1009
+ parser.add_argument("--no-footnotes", action="store_true")
1010
+ parser.add_argument("--no-endnotes", action="store_true")
1011
+ parser.add_argument("--no-comments", action="store_true")
1012
+ parser.add_argument("--no-hyperlinks", action="store_true")
1013
+ parser.add_argument("--no-textboxes", action="store_true")
1014
+ parser.add_argument(
1015
+ "--include-headers",
1016
+ action="store_true",
1017
+ help="Include header text. Off by default to mirror reading-only intent.",
1018
+ )
1019
+ parser.add_argument(
1020
+ "--include-footers",
1021
+ action="store_true",
1022
+ help="Include footer text. Off by default to mirror reading-only intent.",
1023
+ )
1024
+ parser.add_argument(
1025
+ "--no-comment-markers",
1026
+ action="store_true",
1027
+ help="Drop inline [cmt:N] markers; comments still listed in the dedicated section.",
1028
+ )
1029
+ return parser
1030
+
1031
+
1032
+ def _options_from_args(args: argparse.Namespace) -> Options:
1033
+ return Options(
1034
+ fmt=args.format,
1035
+ revisions=args.revisions,
1036
+ include_footnotes=not args.no_footnotes,
1037
+ include_endnotes=not args.no_endnotes,
1038
+ include_comments=not args.no_comments,
1039
+ include_hyperlinks=not args.no_hyperlinks,
1040
+ include_textboxes=not args.no_textboxes,
1041
+ include_headers=args.include_headers,
1042
+ include_footers=args.include_footers,
1043
+ inline_comment_marker=not args.no_comment_markers,
1044
+ )
1045
+
1046
+
1047
+ def main(argv: Optional[list[str]] = None) -> int:
1048
+ parser = _build_parser()
1049
+ args = parser.parse_args(argv)
1050
+
1051
+ input_path = Path(args.input_path).expanduser().resolve()
1052
+ if not input_path.exists():
1053
+ raise RuntimeError(f"Input file does not exist: {input_path}")
1054
+ if input_path.suffix.lower() != ".docx":
1055
+ raise RuntimeError("extract_docx_text.py currently supports .docx only")
1056
+
1057
+ options = _options_from_args(args)
1058
+ result = extract(input_path, options)
1059
+
1060
+ if options.fmt == "json":
1061
+ sys.stdout.write(render_json(result, options, input_path))
1062
+ sys.stdout.write("\n")
1063
+ elif options.fmt == "markdown":
1064
+ sys.stdout.write(render_markdown(result, options))
1065
+ else:
1066
+ sys.stdout.write(render_text(result, options))
1067
+ return 0
1068
+
1069
+
1070
+ if __name__ == "__main__":
1071
+ try:
1072
+ raise SystemExit(main())
1073
+ except Exception as exc: # pragma: no cover - CLI error path
1074
+ print(f"extract_docx_text.py failed: {exc}", file=sys.stderr)
1075
+ raise SystemExit(1)