Skip to content

chore(api): .docx import rides a deprecated, untyped mammoth API under a caret range #1290

Description

@joacominatel

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

  1. Pin mammoth to an exact version so the removal can only arrive via a deliberate, reviewed
    bump. Cheapest, but leaves the cast.
  2. 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.
  3. 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:backendBackend — NestJS API, Prisma, domain logicauto-generatedOpened by an agent — review mepriority:normalDefault prioritytype:choreMaintenance, configuration, tooling

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions