From 41a5f71164946729b7871f6175061952accb500f Mon Sep 17 00:00:00 2001
From: Caio Pizzol <caio@superdoc.dev>
Date: Tue, 5 May 2026 10:09:07 -0300
Subject: [PATCH] fix(types): drain bare @superdoc/common shim, reach zero
 shims (SD-2893)

The remaining @superdoc/common shim is referenced by three internal
dist d.ts files for four Comment* types (Comment, CommentContent,
CommentJSON, CommentThreadingProfile). All four live in
shared/common/comments-types.ts.

Approach matches the list-marker-utils pattern from #3150: tsc-emit
just comments-types.ts into dist/shared/common/, then rewrite bare
@superdoc/common imports to that file. matchSubpaths: false because
only the bare specifier is referenced; any future
@superdoc/common/<other-subpath> import falls through to the shim
generator and audit Rule 3 fires (because @superdoc/common is now
in RELOCATION_GUARD_PACKAGES, the regex matches the subpath).

Verified end-to-end: a synthetic
@superdoc/common/some-other-subpath probe is left unchanged by
ensure-types, the shim generator captures it, audit Rule 3 fails
with exit 1.

The existing inline-replacement step at ensure-types.cjs:89-119
that handles the main entry's runtime-value imports (DOCX, PDF,
HTML, getFileObject, compareVersions, BlankDOCX) stays as-is. Two
paths through the script address different concerns:

- Inline-replacement: runtime values from @superdoc/common in
  superdoc/src/index.d.ts (handles those 6 specific imports)
- Relocation rule: bare @superdoc/common type imports in three
  internal dist d.ts files (resolves to comments-types.d.ts)

Shim count: 1 to 0. Final shim drain. _internal-shims.d.ts has no
declare-module entries; all originally-shimmed @superdoc/* packages
have been relocated, removed from the public surface, or guarded.

Verified: build:es clean (10 guarded packages, 0 shim modules),
consumer matrix 47/0/0, runtime smoke 4/4, dist has the relocation
target at shared/common/comments-types.d.ts, the three consumer
d.ts files now import from a relative path. Negative test confirms
the audit gate catches future @superdoc/common subpath leaks.
---
 .../superdoc/scripts/audit-declarations.cjs   |  1 +
 packages/superdoc/scripts/ensure-types.cjs    | 23 ++++++++++++++++---
 2 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/packages/superdoc/scripts/audit-declarations.cjs b/packages/superdoc/scripts/audit-declarations.cjs
index ba928eef16..20d76e6811 100644
--- a/packages/superdoc/scripts/audit-declarations.cjs
+++ b/packages/superdoc/scripts/audit-declarations.cjs
@@ -73,6 +73,7 @@ const RELOCATION_GUARD_PACKAGES = [
   '@superdoc/painter-dom',
   '@superdoc/pm-adapter',
   '@superdoc/style-engine',
+  '@superdoc/common',
   '@superdoc/common/list-marker-utils',
 ];
 
diff --git a/packages/superdoc/scripts/ensure-types.cjs b/packages/superdoc/scripts/ensure-types.cjs
index 66a92455bb..61e7bed913 100644
--- a/packages/superdoc/scripts/ensure-types.cjs
+++ b/packages/superdoc/scripts/ensure-types.cjs
@@ -66,9 +66,11 @@ if (handwrittenCopiedSuperEditor > 0) {
 // public surface. Adding shared/ to vite-plugin-dts's `include` would shift the
 // common-ancestor of all source files to the repo root and reorganise the
 // entire dist tree, so we run tsc directly for just the files we relocate.
-// Today: list-marker-utils plus its sibling layout-constants. Add new entries
-// here in lockstep with `RELOCATION_RULES` below.
-const SHARED_COMMON_DTS_TARGETS = ['list-marker-utils.ts', 'layout-constants.ts'];
+// Today: list-marker-utils plus its sibling layout-constants, and
+// comments-types (the four Comment* types referenced via bare @superdoc/common
+// imports in three internal-only dist d.ts files). Add new entries here in
+// lockstep with `RELOCATION_RULES` below.
+const SHARED_COMMON_DTS_TARGETS = ['list-marker-utils.ts', 'layout-constants.ts', 'comments-types.ts'];
 {
   const { spawnSync: _spawnSync } = require('node:child_process');
   const tscBin = path.join(repoRoot, 'node_modules', '.bin', 'tsc');
@@ -285,6 +287,20 @@ const RELOCATION_RULES = [
     distEntry: 'layout-engine/style-engine/src/ooxml/index.d.ts',
     matchSubpaths: false,
   },
+  // SD-2893: bare @superdoc/common appears in three internal-only dist d.ts
+  // files for the four Comment* types (Comment, CommentContent, CommentJSON,
+  // CommentThreadingProfile). Point the bare specifier at comments-types.d.ts
+  // (emitted via SHARED_COMMON_DTS_TARGETS) so the rewrite resolves to a real
+  // file. matchSubpaths: false because only the bare specifier is referenced;
+  // any future @superdoc/common/<other-subpath> import would not be auto-
+  // rewritten, falling through to the audit gate. The runtime-value imports
+  // from the main entry (DOCX, PDF, HTML, getFileObject, compareVersions,
+  // BlankDOCX) are still handled by the inline-replacement step above.
+  {
+    pkg: '@superdoc/common',
+    distEntry: 'shared/common/comments-types.d.ts',
+    matchSubpaths: false,
+  },
 ];
 
 // Guard packages that must never fall back to `_internal-shims.d.ts`.
@@ -300,6 +316,7 @@ const RELOCATION_GUARD_PACKAGES = [
   '@superdoc/painter-dom',
   '@superdoc/pm-adapter',
   '@superdoc/style-engine',
+  '@superdoc/common',
   '@superdoc/common/list-marker-utils',
 ];