feat(types): harden package shape (SD-2978) (#3251)

* feat(types): harden package shape (SD-2978)

* fix(types): gate stable release with same package-shape checks (SD-2978)

The original SD-2978 commit only added consumer matrix + package-shape
gates to release-superdoc.yml. Between sessions, release-stable.yml
landed as the new central orchestrator for the npm `latest` publish
lane, and SuperDoc's stable releases now route through that workflow
instead of release-superdoc.yml (which is now `@next` only).

Without this patch the stable lane would publish without the matrix or
publint/attw gates running, defeating the purpose of "package-shape
honest in CI" because the most-consumed dist-tag would still be
unverified at publish time.

Adds the same three steps (matrix, deep-type-audit, package-shape-gate)
between Build packages and the orchestrator step in release-stable.yml.

* fix(types): teach deep audit to read nested types: { import, require } (SD-2978)

The deep audit assumed `entry.types` is always a string. SD-2978's
manifest changes nest it as `{ import: '...d.ts', require: '...d.cts' }`
for the three entries that publish CJS. The audit threw
ERR_INVALID_ARG_TYPE on `path.resolve(root, entry.types)` when entry.types
was an object.

Add a small helper that picks the ESM target from either shape (string
or condition object). Walking the .d.ts side is sufficient because the
.d.cts is a generated shim of the same surface.

Verified: audit now exits 0 with the same 1799 findings as pre-fix.

* fix(types): make sanitizer re-entrant + route pack:local through pack:es (SD-2978)

Code review found that `pnpm run pack` was broken by the new
prepack/postpack lifecycle. pnpm wraps prepack/postpack around scripts
named exactly `pack`, and the user `pack` script itself invokes
`pnpm pack` which triggers a second prepack. The inner prepack hit the
"backup exists" guard and exited 1, the outer postpack was skipped, and
the workspace was left with `package.json` mutated and
`.package.json.prepack-backup` orphaned.

Two changes:

1. Make `prepare` re-entrant. If the backup file exists AND the current
   manifest already looks sanitized (no `source` conditions, no `unpkg`
   or `jsdelivr` fields), no-op so the inner prepack falls through and
   the inner postpack can restore cleanly. If the backup exists but the
   manifest is NOT sanitized, fail loudly with a clear message — that
   means the workspace is in an inconsistent state from a previous
   failed pack and the developer needs to clean up. `restore` was
   already idempotent (no-op when backup missing).

2. Route `pack:local` through `pack:es` directly. Both ultimately do
   the same thing, but going through `pack:es` (whose name does not
   collide with the lifecycle trigger) avoids the double-fire on the
   common local-pack path.

Verified with a synthetic harness covering 5 cases: clean run,
double-fire (outer + inner), failed run (state inspection), retry after
failure (self-heal), inconsistent state (loud refusal). All pass.

Verified live in the worktree:
- pnpm run pack:es: tarball created, manifest restored, no orphan backup
- pnpm run pack: same (was broken before this commit, now works)

Author: caio-pizzol

.github/workflows/ci-superdoc.yml

@@ -147,6 +147,13 @@ jobs:
           cd tests/consumer-typecheck
           node deep-type-audit.mjs
 
+      - name: Package shape gates
+        # External package-shape linters (publint + attw) running against
+        # the packed tarball. Catches manifest issues that the in-repo
+        # consumer matrix does not see: condition ordering, masquerading
+        # ESM, missing CDN files, unpublished `source` paths.
+        run: node tests/consumer-typecheck/package-shape-gate.mjs
+
   unit-tests:
     needs: build
     runs-on: ubuntu-latest

.github/workflows/release-stable.yml

@@ -106,6 +106,24 @@ jobs:
       - name: Build packages
         run: pnpm run build
 
+      # Public-type contract gates: same gates as PR CI and
+      # release-superdoc.yml. The stable orchestrator publishes the npm
+      # `latest` tag, so a regression that bypassed PR CI would otherwise
+      # ship to every consumer pinned to `^1` or `latest`. Run identical
+      # checks here so the stable lane cannot silently relax the gate.
+      - name: Consumer typecheck (matrix)
+        run: |
+          cd tests/consumer-typecheck
+          node typecheck-matrix.mjs
+
+      - name: Deep public-type audit (report-only)
+        run: |
+          cd tests/consumer-typecheck
+          node deep-type-audit.mjs
+
+      - name: Package shape gates
+        run: node tests/consumer-typecheck/package-shape-gate.mjs
+
       - name: Release stable packages (orchestrator)
         id: stable_release
         env:

.github/workflows/release-superdoc.yml

@@ -118,7 +118,7 @@ jobs:
       - name: Build packages
         run: pnpm run build
 
-      # Public-type contract gate: same gates as PR CI (ci-superdoc.yml).
+      # Public-type contract gates: same gates as PR CI (ci-superdoc.yml).
       # Runs before publishing so a release cannot ship a regression that
       # bypassed PR CI (manual republish, hotfix branch, recovery flow).
       - name: Consumer typecheck (matrix)
@@ -134,6 +134,11 @@ jobs:
           cd tests/consumer-typecheck
           node deep-type-audit.mjs
 
+      - name: Package shape gates
+        # External package-shape linters (publint + attw) running against
+        # the packed tarball. Same step as PR CI.
+        run: node tests/consumer-typecheck/package-shape-gate.mjs
+
       # PR preview: publish with pr-<number> dist-tag
       - name: Publish PR preview
         if: inputs.pr_number

packages/superdoc/package.json

@@ -19,13 +19,19 @@
   ],
   "exports": {
     ".": {
-      "types": "./dist/superdoc/src/index.d.ts",
+      "types": {
+        "import": "./dist/superdoc/src/index.d.ts",
+        "require": "./dist/superdoc/src/index.d.cts"
+      },
       "source": "./src/index.js",
       "import": "./dist/superdoc.es.js",
       "require": "./dist/superdoc.cjs"
     },
     "./types": {
-      "types": "./dist/super-editor/src/types.d.ts",
+      "types": {
+        "import": "./dist/super-editor/src/types.d.ts",
+        "require": "./dist/super-editor/src/types.d.cts"
+      },
       "source": "./src/types.ts",
       "import": "./dist/types.es.js",
       "require": "./dist/types.cjs"
@@ -39,8 +45,11 @@
       "import": "./dist/super-editor/docx-zipper.es.js"
     },
     "./super-editor": {
+      "types": {
+        "import": "./dist/superdoc/src/super-editor.d.ts",
+        "require": "./dist/superdoc/src/super-editor.d.cts"
+      },
       "source": "./src/super-editor.js",
-      "types": "./dist/superdoc/src/super-editor.d.ts",
       "import": "./dist/super-editor.es.js",
       "require": "./dist/super-editor.cjs"
     },
@@ -112,8 +121,6 @@
   },
   "main": "./dist/superdoc.cjs",
   "module": "./dist/superdoc.es.js",
-  "unpkg": "./dist/superdoc.min.js",
-  "jsdelivr": "./dist/superdoc.min.js",
   "scripts": {
     "dev": "concurrently -k -n VITE,WORD -c cyan,magenta \"vite\" \"node ../../devtools/word-benchmark-sidecar/server.js --stay-alive-on-reuse\"",
     "dev:collab": "concurrently -k -n VITE,COLLAB,WORD -c cyan,green,magenta \"vite\" \"pnpm run collab-server\" \"node ../../devtools/word-benchmark-sidecar/server.js --stay-alive-on-reuse\"",
@@ -130,7 +137,9 @@
     "build:cdn": "vite build --config vite.config.cdn.js",
     "watch:cdn": "vite build --watch --config vite.config.cdn.js",
     "clean": "rm -rf dist",
-    "pack:local": "pnpm run pack",
+    "prepack": "node ./scripts/sanitize-pack-manifest.cjs prepare",
+    "postpack": "node ./scripts/sanitize-pack-manifest.cjs restore",
+    "pack:local": "pnpm run pack:es",
     "pack": "pnpm run build:es && pnpm pack && mv $(ls superdoc-*.tgz) ./superdoc.tgz",
     "pack:es": "pnpm run build:es && pnpm pack && mv $(ls superdoc-*.tgz) ./superdoc.tgz",
     "test": "vitest"

packages/superdoc/scripts/audit-declarations.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Audit the published declaration surface for leaks the package boundary RFC
- * (SD-2829) classifies as forbidden. Walks every `.d.ts` file under `dist/`
+ * (SD-2829) classifies as forbidden. Walks every declaration file under `dist/`
  * and reports:
  *
  *  Rule 1 (FAIL in strict mode): private workspace specifier in an emitted
@@ -90,7 +90,7 @@ function collectDtsFiles(dir) {
       files.push(...collectDtsFiles(fullPath));
       continue;
     }
-    if (entry.name.endsWith('.d.ts')) {
+    if (entry.name.endsWith('.d.ts') || entry.name.endsWith('.d.cts')) {
       files.push(fullPath);
     }
   }
@@ -159,7 +159,7 @@ const relocatedInShim = RELOCATION_GUARD_PACKAGES.filter((pkg) =>
 
 console.log('[audit-declarations] Declaration surface audit');
 console.log('='.repeat(72));
-console.log(`Scanned: ${dtsFiles.length} .d.ts files under ${path.relative(process.cwd(), distRoot)}/`);
+console.log(`Scanned: ${dtsFiles.length} declaration files under ${path.relative(process.cwd(), distRoot)}/`);
 console.log();
 
 const violations = [];

packages/superdoc/scripts/check-export-coverage.cjs

@@ -33,14 +33,14 @@ function entryAllowlistedAsset(value) {
 }
 
 function entryHasTypes(value) {
-  if (typeof value === 'string') return false;
-  if (typeof value !== 'object' || value === null) return false;
-  return typeof value.types === 'string';
+  return collectTypesTargets(value).length > 0;
 }
 
-function typesTargetExists(value) {
-  if (!entryHasTypes(value)) return false;
-  return fs.existsSync(path.resolve(packageRoot, value.types));
+function collectTypesTargets(value) {
+  if (typeof value !== 'object' || value === null) return [];
+  if (typeof value.types === 'string') return [value.types];
+  if (typeof value.types !== 'object' || value.types === null) return [];
+  return Object.values(value.types).filter((target) => typeof target === 'string');
 }
 
 const violations = [];
@@ -53,8 +53,10 @@ for (const [subpath, value] of Object.entries(packageJson.exports || {})) {
     violations.push({ subpath, reason: 'missing `types` field in conditional exports' });
     continue;
   }
-  if (!typesTargetExists(value)) {
-    violations.push({ subpath, reason: `\`types\` target does not exist: ${value.types}` });
+  for (const target of collectTypesTargets(value)) {
+    if (!fs.existsSync(path.resolve(packageRoot, target))) {
+      violations.push({ subpath, reason: `\`types\` target does not exist: ${target}` });
+    }
   }
 }
 

packages/superdoc/scripts/ensure-types.cjs

@@ -93,14 +93,84 @@ const SHARED_COMMON_DTS_TARGETS = typeSurface.sharedCommonDtsTargets;
   console.log(`[ensure-types] ✓ Emitted ${SHARED_COMMON_DTS_TARGETS.length} shared/common declarations`);
 }
 
-const requiredEntryPoints = typeSurface.requiredEntryPoints;
+// SD-2978: the package advertises CJS runtime entry points for `.`, `./types`,
+// and `./super-editor`. Node16/NodeNext TypeScript consumers resolving those
+// entries through `require` need CJS declaration entry points (`.d.cts`) so the
+// type graph is honest about the runtime module kind. Generate named CJS
+// declaration shims from the ESM entry declarations. A plain
+// `export * from './entry.js'` is not valid here: TypeScript still treats that
+// as a CJS declaration importing an ESM declaration and raises TS1479.
+const cjsDeclarationShims = [
+  {
+    file: path.join(distRoot, 'superdoc/src/index.d.cts'),
+    source: path.join(distRoot, 'superdoc/src/index.d.ts'),
+    target: './index.js',
+  },
+  {
+    file: path.join(distRoot, 'super-editor/src/types.d.cts'),
+    source: path.join(distRoot, 'super-editor/src/types.d.ts'),
+    target: './types.js',
+  },
+  {
+    file: path.join(distRoot, 'superdoc/src/super-editor.d.cts'),
+    source: path.join(distRoot, 'superdoc/src/super-editor.d.ts'),
+    target: './super-editor.js',
+  },
+];
+
+function isValidIdentifier(name) {
+  return /^[$A-Z_a-z][$\w]*$/.test(name);
+}
 
-for (const entry of requiredEntryPoints) {
-  const fullPath = path.join(distRoot, entry);
-  if (!fs.existsSync(fullPath)) {
-    console.error(`[ensure-types] Missing ${entry}`);
+function emitCjsDeclarationShim({ file, source, target }) {
+  const ts = require('typescript');
+  const program = ts.createProgram([source], {
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.Node16,
+    moduleResolution: ts.ModuleResolutionKind.Node16,
+    skipLibCheck: true,
+    noEmit: true,
+  });
+  const checker = program.getTypeChecker();
+  const sourceFile = program.getSourceFile(source);
+  const moduleSymbol = sourceFile && checker.getSymbolAtLocation(sourceFile);
+
+  if (!moduleSymbol) {
+    console.error(`[ensure-types] Could not inspect exports for ${path.relative(distRoot, source)}`);
     process.exit(1);
   }
+
+  const importRef = `import('${target}', { with: { "resolution-mode": "import" } })`;
+  const importLines = [
+    '// Generated by scripts/ensure-types.cjs. Do not edit by hand.',
+  ];
+  const exportLines = [];
+
+  for (const symbol of checker.getExportsOfModule(moduleSymbol).sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = symbol.getName();
+    if (name === 'default' || !isValidIdentifier(name)) continue;
+
+    const resolved = (symbol.flags & ts.SymbolFlags.Alias) ? checker.getAliasedSymbol(symbol) : symbol;
+    const hasValue = Boolean(resolved.flags & ts.SymbolFlags.Value);
+    const hasType = Boolean(resolved.flags & ts.SymbolFlags.Type);
+
+    if (hasType) {
+      const typeAlias = `__Cjs_${name}`;
+      importLines.push(`import type { ${name} as ${typeAlias} } from '${target}' with { "resolution-mode": "import" };`);
+      if (hasValue) {
+        exportLines.push(`export type ${name} = ${typeAlias};`);
+      } else {
+        exportLines.push(`export type { ${typeAlias} as ${name} };`);
+      }
+    }
+
+    if (hasValue) {
+      exportLines.push(`export declare const ${name}: typeof ${importRef}.${name};`);
+    }
+  }
+
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${importLines.concat(exportLines).join('\n')}\n`);
 }
 
 const indexPath = path.join(distRoot, 'superdoc/src/index.d.ts');
@@ -416,6 +486,22 @@ if (fs.readFileSync(superEditorFacadePath, 'utf8') !== expectedSuperEditorFacade
   console.log('[ensure-types] ✓ Normalized superdoc/super-editor facade types');
 }
 
+for (const shim of cjsDeclarationShims) {
+  emitCjsDeclarationShim(shim);
+}
+console.log(`[ensure-types] ✓ Emitted ${cjsDeclarationShims.length} CJS declaration shims`);
+
+const requiredEntryPoints = typeSurface.requiredEntryPoints;
+
+for (const entry of requiredEntryPoints) {
+  const fullPath = path.join(distRoot, entry);
+  if (!fs.existsSync(fullPath)) {
+    console.error(`[ensure-types] Missing ${entry}`);
+    process.exit(1);
+  }
+}
+console.log('[ensure-types] ✓ Verified type entry points');
+
 // ---------------------------------------------------------------------------
 // SD-2942: the auto-generated `_internal-shims.d.ts` mechanism was removed
 // after SD-2893 drained every shim entry to zero. Previously this script
@@ -447,5 +533,3 @@ if (fs.existsSync(legacyShimPath)) {
   fs.unlinkSync(legacyShimPath);
   console.log('[ensure-types] ✓ Removed legacy _internal-shims.d.ts');
 }
-
-console.log('[ensure-types] ✓ Verified type entry points');