The .docx import path calls mammoth.convertToMarkdown, which mammoth deprecated and does
not publish types for. apps/api/src/articles/article-import.ts:32-40 documents this and casts
through a locally declared MammothMarkdown interface to get past the compiler.
apps/api/package.json:44 pins mammoth at ^1.12.0. A caret range accepts any 1.x minor, and
the markdown writer is deprecated — so a routine dependency update can remove the function this
code depends on.
Why this matters
Because the call site is a cast, the type system cannot see the removal. bunx tsc --noEmit
stays green, every test that does not exercise a real .docx stays green, and CI passes. The
failure surfaces in production, on an operator upgrading in place, as a runtime TypeError the
first time somebody imports a Word document.
This is the same dependency-range class of problem as #1288.
Options
- Pin
mammoth to an exact version so the removal can only arrive via a deliberate, reviewed
bump. Cheapest, but leaves the cast.
- Take the escape hatch the code comment already names:
convertToHtml plus an HTML→markdown
step (turndown). Removes the dependence on a deprecated API, adds a dependency.
- Add a test that runs a real
.docx fixture through parseImportFile and asserts on the
extracted markdown, so the breakage is caught by CI rather than by an operator.
Options 1 and 3 are complementary and both cheap. Option 2 is the durable fix and should be
weighed against the cost of a new dependency.
Notes
- No schema change, no migration. Whichever option is taken is write-path only; existing
articles are unaffected.
.docx support is decided in ADR-0021. This issue is about how it is wired, not whether it
should exist.
- Found while investigating the knowledge-base work of this session; not a regression from it.
The
.docximport path callsmammoth.convertToMarkdown, which mammoth deprecated and doesnot publish types for.
apps/api/src/articles/article-import.ts:32-40documents this and caststhrough a locally declared
MammothMarkdowninterface to get past the compiler.apps/api/package.json:44pinsmammothat^1.12.0. A caret range accepts any 1.x minor, andthe markdown writer is deprecated — so a routine dependency update can remove the function this
code depends on.
Why this matters
Because the call site is a cast, the type system cannot see the removal.
bunx tsc --noEmitstays green, every test that does not exercise a real
.docxstays green, and CI passes. Thefailure surfaces in production, on an operator upgrading in place, as a runtime
TypeErrorthefirst time somebody imports a Word document.
This is the same dependency-range class of problem as #1288.
Options
mammothto an exact version so the removal can only arrive via a deliberate, reviewedbump. Cheapest, but leaves the cast.
convertToHtmlplus an HTML→markdownstep (turndown). Removes the dependence on a deprecated API, adds a dependency.
.docxfixture throughparseImportFileand asserts on theextracted markdown, so the breakage is caught by CI rather than by an operator.
Options 1 and 3 are complementary and both cheap. Option 2 is the durable fix and should be
weighed against the cost of a new dependency.
Notes
articles are unaffected.
.docxsupport is decided in ADR-0021. This issue is about how it is wired, not whether itshould exist.