Merge pull request #3360 from superdoc-dev/caio-pizzol/SD-3180-legacy-leaf-facade-entries

feat(types): legacy leaf facade entries (SD-3180)

Author: caio-pizzol

packages/super-editor/src/editors/v1/core/super-converter/SuperConverter.d.ts

@@ -5,3 +5,7 @@ export class SuperConverter {
   static extractDocumentGuid(...args: any[]): string | null;
   [key: string]: any;
 }
+
+export function hasBodyNumberingReferences(
+  documentXml: { name?: string; elements?: readonly unknown[] } | null | undefined,
+): boolean;

packages/superdoc/scripts/verify-public-facade-emit.cjs

@@ -33,8 +33,15 @@
  *
  * Adding a new facade file:
  *   - Create `packages/superdoc/src/public/<name>.ts` with named exports.
- *   - Wire it into `vite.config.js` (`rollupOptions.input`) and the CJS
- *     shim list in `scripts/ensure-types.cjs`.
+ *   - Wire it into `vite.config.js` (`rollupOptions.input`).
+ *   - If the new entry is intended to ship with both ESM and CJS type
+ *     declarations (i.e. `package.json#exports` will use a `types.import` /
+ *     `types.require` pair), also add it to `cjsDeclarationShims` in
+ *     `scripts/ensure-types.cjs` and set `cjs` on the `FACADE_ENTRIES`
+ *     entry below. If the entry will use a single `types` string instead
+ *     (matching the SD-3180 legacy leaf entries), leave `cjs: null` and
+ *     the parity check is skipped. Phase 4 of SD-3175 owns the contract
+ *     flip and decides per-entry which shape ships.
  *   - Append a `FACADE_ENTRIES` entry below with the expected symbol set.
  *   - If the new entry re-exports `EditorCommands`, set
  *     `runsCommandSignatureProbe: true`.
@@ -97,6 +104,44 @@ const FACADE_ENTRIES = [
     runsCommandSignatureProbe: false,
     ticket: 'SD-3179',
   },
+  // SD-3180: legacy leaf entries. These match the existing single-types
+  // pattern of the live `superdoc/converter` / `superdoc/docx-zipper` /
+  // `superdoc/file-zipper` subpaths, which do not have `.d.cts` shims
+  // today. `cjs: null` skips the ESM/CJS parity check. Phase 4 decides
+  // whether to add CJS shims when the contract flips.
+  {
+    name: 'legacy/converter',
+    esm: path.join(PUBLIC_DIST, 'legacy', 'converter.d.ts'),
+    cjs: null,
+    // AIDEV-NOTE: `hasBodyNumberingReferences` is in the runtime contract
+    // of today's `superdoc/converter` (see
+    // `packages/superdoc/dist/super-editor/converter.es.js`) but missing
+    // from the existing types entry. The facade types both so Phase 4
+    // can flip without regressing JS consumers.
+    expectedNames: ['SuperConverter', 'hasBodyNumberingReferences'],
+    runsCommandSignatureProbe: false,
+    ticket: 'SD-3180',
+  },
+  {
+    name: 'legacy/docx-zipper',
+    esm: path.join(PUBLIC_DIST, 'legacy', 'docx-zipper.d.ts'),
+    cjs: null,
+    // AIDEV-NOTE: `default`, not `DocxZipper`. The current public contract
+    // is `import DocxZipper from 'superdoc/docx-zipper'`. The resolved
+    // exported name is therefore `default`. Changing to a named export
+    // would break consumers.
+    expectedNames: ['default'],
+    runsCommandSignatureProbe: false,
+    ticket: 'SD-3180',
+  },
+  {
+    name: 'legacy/file-zipper',
+    esm: path.join(PUBLIC_DIST, 'legacy', 'file-zipper.d.ts'),
+    cjs: null,
+    expectedNames: ['createZip'],
+    runsCommandSignatureProbe: false,
+    ticket: 'SD-3180',
+  },
 ];
 
 function loadFile(file) {
@@ -108,27 +153,55 @@ function loadFile(file) {
   return fs.readFileSync(file, 'utf8');
 }
 
-function listExportedNames(file) {
+function formatDiagnostic(diagnostic) {
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+  if (!diagnostic.file || diagnostic.start == null) return message;
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+  const relative = path.relative(repoRoot, diagnostic.file.fileName);
+  return `${relative}:${line + 1}:${character + 1} ${message}`;
+}
+
+function listExportedNames(entry, file) {
   const program = ts.createProgram({
     rootNames: [file],
     options: {
       moduleResolution: ts.ModuleResolutionKind.Bundler,
       module: ts.ModuleKind.ESNext,
       target: ts.ScriptTarget.ESNext,
       noEmit: true,
-      skipLibCheck: true,
+      skipLibCheck: false,
     },
   });
+  const diagnostics = [
+    ...program.getSyntacticDiagnostics(),
+    ...program.getSemanticDiagnostics(),
+    ...program.getDeclarationDiagnostics(),
+  ];
+  if (diagnostics.length > 0) {
+    console.error(`[verify-public-facade-emit] ${entry.name}: facade declaration has TypeScript diagnostics.`);
+    for (const diagnostic of diagnostics.slice(0, 10)) {
+      console.error('  - ' + formatDiagnostic(diagnostic));
+    }
+    if (diagnostics.length > 10) {
+      console.error(`  ... ${diagnostics.length - 10} more diagnostics`);
+    }
+    return { ok: false, names: [] };
+  }
   const checker = program.getTypeChecker();
   const src = program.getSourceFile(file);
   const symbol = checker.getSymbolAtLocation(src) ?? (src && src.symbol);
-  if (!symbol) return [];
-  return [...new Set(checker.getExportsOfModule(symbol).map((s) => s.getName()))].sort();
+  if (!symbol) return { ok: true, names: [] };
+  return {
+    ok: true,
+    names: [...new Set(checker.getExportsOfModule(symbol).map((s) => s.getName()))].sort(),
+  };
 }
 
 function checkSymbolSet(entry) {
   const expected = [...entry.expectedNames].sort();
-  const actual = listExportedNames(entry.esm);
+  const result = listExportedNames(entry, entry.esm);
+  if (!result.ok) return { ok: false, actual: result.names };
+  const actual = result.names;
   if (JSON.stringify(actual) === JSON.stringify(expected)) {
     return { ok: true, actual };
   }
@@ -141,7 +214,9 @@ function checkSymbolSet(entry) {
 }
 
 function checkEsmCjsParity(entry, esmNames) {
-  const cjsNames = listExportedNames(entry.cjs);
+  const result = listExportedNames(entry, entry.cjs);
+  if (!result.ok) return false;
+  const cjsNames = result.names;
   if (JSON.stringify(esmNames) === JSON.stringify(cjsNames)) return true;
   const importOnly = esmNames.filter((n) => !cjsNames.includes(n));
   const requireOnly = cjsNames.filter((n) => !esmNames.includes(n));
@@ -218,7 +293,9 @@ const LEAK_PATTERNS = [
 
 function checkLeaks(entry) {
   let ok = true;
-  for (const file of [entry.esm, entry.cjs]) {
+  const files = [entry.esm];
+  if (entry.cjs) files.push(entry.cjs);
+  for (const file of files) {
     const code = stripComments(loadFile(file));
     for (const pattern of LEAK_PATTERNS) {
       const matches = code.match(pattern.re);
@@ -239,7 +316,10 @@ for (const entry of FACADE_ENTRIES) {
   const symbolResult = checkSymbolSet(entry);
   if (!symbolResult.ok) failed = true;
 
-  if (!checkEsmCjsParity(entry, symbolResult.actual)) failed = true;
+  // Entries with `cjs: null` (e.g. SD-3180 legacy leaf entries that match
+  // the existing single-types pattern) skip the parity check until Phase 4
+  // decides whether to add proper CJS shims.
+  if (entry.cjs && !checkEsmCjsParity(entry, symbolResult.actual)) failed = true;
 
   if (entry.runsCommandSignatureProbe && !checkCommandSignatureProbe(entry)) {
     failed = true;

packages/superdoc/src/public/legacy/converter.test.ts

@@ -0,0 +1,17 @@
+import { describe, it, expect } from 'vitest';
+import { SuperConverter, hasBodyNumberingReferences } from './converter.js';
+
+/**
+ * Smoke test for the legacy public facade converter entry (SD-3180).
+ * Declaration-side validation (symbol set, leak grep) lives in
+ * `packages/superdoc/scripts/verify-public-facade-emit.cjs`.
+ */
+describe('public facade (legacy/converter)', () => {
+  it('re-exports SuperConverter as a constructor', () => {
+    expect(typeof SuperConverter).toBe('function');
+  });
+
+  it('re-exports hasBodyNumberingReferences as a function', () => {
+    expect(typeof hasBodyNumberingReferences).toBe('function');
+  });
+});

packages/superdoc/src/public/legacy/converter.ts

@@ -0,0 +1,24 @@
+/**
+ * SuperDoc public facade: legacy converter entry.
+ *
+ * SD-3180 under SD-3178 (Phase 3 of SD-3175). Mirrors the existing
+ * `superdoc/converter` subpath under the path-as-contract structure.
+ *
+ * Classification: **legacy public compatibility surface** per
+ * `docs/architecture/package-boundaries.md` Decision 4. New code should
+ * import `SuperConverter` from `superdoc` directly.
+ *
+ * AIDEV-NOTE: The runtime contract for `superdoc/converter` today exports
+ * both `SuperConverter` and `hasBodyNumberingReferences` (see
+ * `packages/superdoc/dist/super-editor/converter.es.js`). The existing
+ * types entry only declares `SuperConverter`, so the SD-3176 typed
+ * snapshot shows 1 name while the runtime contract has 2. This facade
+ * types both so Phase 4 can flip `package.json#exports` without
+ * regressing JS consumers doing
+ * `import { hasBodyNumberingReferences } from 'superdoc/converter'`.
+ * Adding or removing an export here updates the `expectedNames` for
+ * the `legacy/converter` entry in `FACADE_ENTRIES` inside
+ * `packages/superdoc/scripts/verify-public-facade-emit.cjs` in the
+ * same PR.
+ */
+export { SuperConverter, hasBodyNumberingReferences } from '@superdoc/super-editor/converter';

packages/superdoc/src/public/legacy/docx-zipper.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import DocxZipper from './docx-zipper.js';
+
+/**
+ * Smoke test for the legacy public facade docx-zipper entry (SD-3180).
+ * This one specifically validates the default-import contract:
+ * `import DocxZipper from 'superdoc/docx-zipper'` is the existing
+ * public contract and must keep working through the facade.
+ */
+describe('public facade (legacy/docx-zipper)', () => {
+  it('re-exports DocxZipper as the default export (constructor)', () => {
+    expect(typeof DocxZipper).toBe('function');
+    expect(DocxZipper.name).toBe('DocxZipper');
+  });
+});

packages/superdoc/src/public/legacy/docx-zipper.ts

@@ -0,0 +1,26 @@
+/**
+ * SuperDoc public facade: legacy docx-zipper entry.
+ *
+ * SD-3180 under SD-3178 (Phase 3 of SD-3175). Mirrors the existing
+ * `superdoc/docx-zipper` subpath under the path-as-contract structure.
+ *
+ * AIDEV-NOTE: This entry is a **default export**, not a named export.
+ * The current public contract is `import DocxZipper from 'superdoc/docx-zipper'`,
+ * which means the resolved declaration's exported name must be `default`.
+ * Importing the default from the narrow `@superdoc/super-editor/docx-zipper`
+ * subpath and re-exporting it as the default preserves that contract and
+ * keeps the emitted bundle narrow (no broad super-editor root graph).
+ *
+ * Classification: **legacy public compatibility surface** per
+ * `docs/architecture/package-boundaries.md` Decision 4. New code should
+ * import `DocxZipper` from `superdoc` directly:
+ *
+ *   import { DocxZipper } from 'superdoc';
+ *
+ * AIDEV-NOTE: Single-export facade. Update `expectedNames` for the
+ * `legacy/docx-zipper` entry in `FACADE_ENTRIES` inside
+ * `packages/superdoc/scripts/verify-public-facade-emit.cjs` in the
+ * same PR if the surface changes.
+ */
+import DocxZipper from '@superdoc/super-editor/docx-zipper';
+export default DocxZipper;

packages/superdoc/src/public/legacy/file-zipper.test.ts

@@ -0,0 +1,8 @@
+import { describe, it, expect } from 'vitest';
+import { createZip } from './file-zipper.js';
+
+describe('public facade (legacy/file-zipper)', () => {
+  it('re-exports createZip as a function', () => {
+    expect(typeof createZip).toBe('function');
+  });
+});

packages/superdoc/src/public/legacy/file-zipper.ts

@@ -0,0 +1,17 @@
+/**
+ * SuperDoc public facade: legacy file-zipper entry.
+ *
+ * SD-3180 under SD-3178 (Phase 3 of SD-3175). Mirrors the existing
+ * `superdoc/file-zipper` subpath under the path-as-contract structure.
+ *
+ * Classification: **legacy public compatibility surface** per
+ * `docs/architecture/package-boundaries.md` Decision 4. New code should
+ * import `createZip` from `superdoc` directly.
+ *
+ * AIDEV-NOTE: Single-export facade. Growing this list ships a new public
+ * symbol through a legacy compat path. Update `expectedNames` for the
+ * `legacy/file-zipper` entry in `FACADE_ENTRIES` inside
+ * `packages/superdoc/scripts/verify-public-facade-emit.cjs` in the
+ * same PR.
+ */
+export { createZip } from '@superdoc/super-editor/file-zipper';

packages/superdoc/vite.config.js

@@ -252,6 +252,12 @@ export default defineConfig(({ mode, command }) => {
           // custom UI integrations should use the `superdoc/ui` /
           // `superdoc/ui/react` entries instead.
           'public/legacy/headless-toolbar': 'src/public/legacy/headless-toolbar.ts',
+          // SD-3180: legacy leaf facade entries mirroring the existing
+          // single-export legacy subpaths. Same classification as
+          // headless-toolbar above.
+          'public/legacy/converter': 'src/public/legacy/converter.ts',
+          'public/legacy/docx-zipper': 'src/public/legacy/docx-zipper.ts',
+          'public/legacy/file-zipper': 'src/public/legacy/file-zipper.ts',
         },
         external: [
           'yjs',

tests/consumer-typecheck/snapshot-superdoc-legacy-exports.mjs

@@ -99,19 +99,36 @@ function snapshotName(subpath) {
   return 'superdoc-' + subpath.replace(/^\.\//, '').replace(/\//g, '-') + '.txt';
 }
 
-function listExportedNames(entryFile) {
+function formatDiagnostic(diagnostic) {
+  const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n');
+  if (!diagnostic.file || diagnostic.start == null) return message;
+  const { line, character } = diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start);
+  return `${diagnostic.file.fileName}:${line + 1}:${character + 1} ${message}`;
+}
+
+function listExportedNames(subpath, entryFile) {
   const program = ts.createProgram({
     rootNames: [entryFile],
     options: {
       moduleResolution: ts.ModuleResolutionKind.Bundler,
       module: ts.ModuleKind.ESNext,
       target: ts.ScriptTarget.ESNext,
       noEmit: true,
-      skipLibCheck: true,
+      skipLibCheck: false,
       allowJs: false,
       declaration: false,
     },
   });
+  const diagnostics = [
+    ...program.getSyntacticDiagnostics(),
+    ...program.getSemanticDiagnostics(),
+    ...program.getDeclarationDiagnostics(),
+  ];
+  if (diagnostics.length > 0) {
+    const details = diagnostics.slice(0, 10).map((diagnostic) => `  - ${formatDiagnostic(diagnostic)}`).join('\n');
+    const suffix = diagnostics.length > 10 ? `\n  ... ${diagnostics.length - 10} more diagnostics` : '';
+    throw new Error(`${subpath} declaration has TypeScript diagnostics:\n${details}${suffix}`);
+  }
   const checker = program.getTypeChecker();
   const source = program.getSourceFile(entryFile);
   if (!source) throw new Error('Cannot load source: ' + entryFile);
@@ -139,7 +156,7 @@ for (const subpath of SUBPATHS) {
 
   let names;
   try {
-    names = listExportedNames(importFile);
+    names = listExportedNames(subpath, importFile);
   } catch (err) {
     console.error(`[SD-3176] Failed to enumerate ${subpath}: ${err.message}`);
     failed = true;
@@ -160,7 +177,7 @@ for (const subpath of SUBPATHS) {
     }
     let cjsNames;
     try {
-      cjsNames = listExportedNames(requireFile);
+      cjsNames = listExportedNames(subpath, requireFile);
     } catch (err) {
       console.error(`[SD-3176] Failed to enumerate CJS for ${subpath}: ${err.message}`);
       failed = true;