feat(core): add tagsSplitDeduplication option for barrel + shared type extraction

Add a new `tagsSplitDeduplication` output option (default: false) that
extracts shared infrastructure types (e.g. HTTPStatusCode*) emitted by
client header builders into a `common-types.ts` file, then generates a
barrel `index.ts` with named re-exports for public types.

When enabled (with `indexFiles: true`):
- Shared types are collected across all per-tag files and deduplicated
- Extracted to `<commonTypesFileName>.ts` (default: 'common-types')
- Per-tag files import shared types from the common file
- Barrel uses named re-exports for exported types + `export *` for tags

When disabled (default): behavior is identical to before — shared types
are inlined per-tag, no barrel, no extraction.

The header builder API is backward compatible: `ClientHeaderBuilder`
return type widens from `string` to `string | HeaderResult`. Existing
builders returning `string` continue to work unchanged.

Currently only `generateFetchHeader` emits `sharedTypes` (HTTPStatusCode*
family). The extraction mechanism is generic — other header builders can
adopt it incrementally.

Remove stale barrel snapshots from the previous naive implementation
(gated on `indexFiles` alone). The barrel now requires both
`indexFiles` and `tagsSplitDeduplication` to be `true`.

Related design discussion: #3553
Closes #3553

Author: aqeelat

packages/core/src/test-utils/context.ts

@@ -47,6 +47,8 @@ export function createTestContextSpec({
     optionsParamRequired: false,
     propertySortOrder: PropertySortOrder.SPECIFICATION,
     factoryMethods: undefined,
+    tagsSplitDeduplication: false,
+    commonTypesFileName: 'common-types',
     override: {
       title: undefined,
       transformer: undefined,

packages/core/src/test-utils/split-modes.ts

@@ -75,6 +75,8 @@ export const createSplitModeOutput = (
     unionAddMissingProperties: false,
     optionsParamRequired: false,
     propertySortOrder: 'Alphabetical',
+    tagsSplitDeduplication: false,
+    commonTypesFileName: 'common-types',
     override: {
       tags: {},
       operations: {},

packages/core/src/types.ts

@@ -68,6 +68,8 @@ export interface NormalizedOutputOptions {
   optionsParamRequired: boolean;
   propertySortOrder: PropertySortOrder;
   factoryMethods?: NormalizedFactoryMethodsOptions;
+  tagsSplitDeduplication: boolean;
+  commonTypesFileName: string;
 }
 
 export interface NormalizedParamsSerializerOptions {
@@ -360,6 +362,8 @@ export interface OutputOptions {
   optionsParamRequired?: boolean;
   propertySortOrder?: PropertySortOrder;
   factoryMethods?: FactoryMethodsOptions;
+  tagsSplitDeduplication?: boolean;
+  commonTypesFileName?: string;
 }
 
 export interface InputFiltersOptions {
@@ -1396,6 +1400,7 @@ export interface GeneratorTarget {
   paramsSerializer?: GeneratorMutator[];
   paramsFilter?: GeneratorMutator[];
   fetchReviver?: GeneratorMutator[];
+  sharedTypes?: SharedTypeDeclaration[];
 }
 
 export interface GeneratorTargetFull {
@@ -1409,6 +1414,7 @@ export interface GeneratorTargetFull {
   paramsSerializer?: GeneratorMutator[];
   paramsFilter?: GeneratorMutator[];
   fetchReviver?: GeneratorMutator[];
+  sharedTypes?: SharedTypeDeclaration[];
 }
 
 export interface GeneratorOperation {
@@ -1507,6 +1513,17 @@ export type ClientExtraFilesBuilder = (
   context: ContextSpec,
 ) => Promise<ClientFileBuilder[]>;
 
+export interface SharedTypeDeclaration {
+  name: string;
+  exported: boolean;
+  code: string;
+}
+
+export type HeaderResult = {
+  implementation: string;
+  sharedTypes?: SharedTypeDeclaration[];
+};
+
 export type ClientHeaderBuilder = (params: {
   title: string;
   isRequestOptions: boolean;
@@ -1520,7 +1537,7 @@ export type ClientHeaderBuilder = (params: {
   tag?: string;
   isDefaultTagBucket?: boolean;
   clientImplementation: string;
-}) => string;
+}) => string | HeaderResult;
 
 export type ClientFooterBuilder = (params: {
   noFunction?: boolean | undefined;
@@ -1759,6 +1776,7 @@ export interface GeneratorApiOperations {
 export interface GeneratorClientExtra {
   implementation: string;
   implementationMock: string;
+  sharedTypes?: SharedTypeDeclaration[];
 }
 
 export type GeneratorClientTitle = (data: {

packages/core/src/writers/split-tags-mode.test.ts

@@ -320,13 +320,14 @@ describe('writeSplitTagsMode — barrel index.ts at target root (#3553)', () =>
     fs.removeSync(tmpDir);
   });
 
-  it('writes index.ts when indexFiles is true', async () => {
+  it('writes index.ts when indexFiles and tagsSplitDeduplication are true', async () => {
     const target = path.join(tmpDir, 'petstore.ts');
     const props = {
       ...createSplitModeProps(target),
       output: createSplitModeOutput(target, {
         mode: OutputMode.TAGS_SPLIT,
         indexFiles: true,
+        tagsSplitDeduplication: true,
       }),
     };
 
@@ -340,13 +341,32 @@ describe('writeSplitTagsMode — barrel index.ts at target root (#3553)', () =>
     expect(content).toContain("export * from './pets/pets'");
   });
 
+  it('does not write index.ts when tagsSplitDeduplication is false', async () => {
+    const target = path.join(tmpDir, 'petstore.ts');
+    const props = {
+      ...createSplitModeProps(target),
+      output: createSplitModeOutput(target, {
+        mode: OutputMode.TAGS_SPLIT,
+        indexFiles: true,
+        tagsSplitDeduplication: false,
+      }),
+    };
+
+    const paths = await writeSplitTagsMode({ ...props, needSchema: false });
+
+    const indexPath = path.join(tmpDir, 'index.ts');
+    expect(paths).not.toContain(indexPath);
+    expect(fs.existsSync(indexPath)).toBe(false);
+  });
+
   it('does not write index.ts when indexFiles is false', async () => {
     const target = path.join(tmpDir, 'petstore.ts');
     const props = {
       ...createSplitModeProps(target),
       output: createSplitModeOutput(target, {
         mode: OutputMode.TAGS_SPLIT,
         indexFiles: false,
+        tagsSplitDeduplication: true,
       }),
     };
 
@@ -364,6 +384,7 @@ describe('writeSplitTagsMode — barrel index.ts at target root (#3553)', () =>
       output: createSplitModeOutput(target, {
         mode: OutputMode.TAGS_SPLIT,
         indexFiles: true,
+        tagsSplitDeduplication: true,
       }),
     };
 
@@ -380,6 +401,7 @@ describe('writeSplitTagsMode — barrel index.ts at target root (#3553)', () =>
       output: createSplitModeOutput(target, {
         mode: OutputMode.TAGS_SPLIT,
         indexFiles: true,
+        tagsSplitDeduplication: true,
         workspace: path.join(tmpDir, 'workspace'),
       }),
     };
@@ -390,4 +412,22 @@ describe('writeSplitTagsMode — barrel index.ts at target root (#3553)', () =>
     expect(paths).not.toContain(indexPath);
     expect(fs.existsSync(indexPath)).toBe(false);
   });
+
+  it('does not write common-types.ts when no shared types are present', async () => {
+    const target = path.join(tmpDir, 'petstore.ts');
+    const props = {
+      ...createSplitModeProps(target),
+      output: createSplitModeOutput(target, {
+        mode: OutputMode.TAGS_SPLIT,
+        indexFiles: true,
+        tagsSplitDeduplication: true,
+      }),
+    };
+
+    const paths = await writeSplitTagsMode({ ...props, needSchema: false });
+
+    const commonTypesPath = path.join(tmpDir, 'common-types.ts');
+    expect(paths).not.toContain(commonTypesPath);
+    expect(fs.existsSync(commonTypesPath)).toBe(false);
+  });
 });

packages/core/src/writers/split-tags-mode.ts

@@ -1,7 +1,12 @@
 import path from 'node:path';
 
 import { generateModelsInline, generateMutatorImports } from '../generators';
-import { OutputClient, OutputMockType, type WriteModeProps } from '../types';
+import {
+  OutputClient,
+  OutputMockType,
+  type SharedTypeDeclaration,
+  type WriteModeProps,
+} from '../types';
 import {
   conventionName,
   getFileInfo,
@@ -72,6 +77,33 @@ export async function writeSplitTagsMode({
     a.localeCompare(b),
   );
 
+  const deduplicationEnabled =
+    output.tagsSplitDeduplication && !output.workspace;
+
+  const collectedSharedTypes: SharedTypeDeclaration[] = [];
+  const seenSharedTypeNames = new Set<string>();
+  for (const [, target] of tagEntries) {
+    if (!target.sharedTypes) continue;
+    for (const t of target.sharedTypes) {
+      if (!seenSharedTypeNames.has(t.name)) {
+        seenSharedTypeNames.add(t.name);
+        collectedSharedTypes.push(t);
+      }
+    }
+  }
+
+  const commonTypesImportExtension = getImportExtension(
+    extension,
+    output.tsconfig,
+  );
+  const commonTypesBasename = output.commonTypesFileName;
+  const commonTypesPath = path.join(dirname, commonTypesBasename + extension);
+  const commonTypesRelativeImport =
+    '..' +
+    '/' +
+    commonTypesBasename +
+    (deduplicationEnabled ? commonTypesImportExtension : '');
+
   const generatedFilePathsArray = await Promise.all(
     tagEntries.map(async ([tag, target]) => {
       try {
@@ -90,6 +122,15 @@ export async function writeSplitTagsMode({
 
         let implementationData = header;
 
+        if (
+          deduplicationEnabled &&
+          target.sharedTypes &&
+          target.sharedTypes.length > 0
+        ) {
+          const typeNames = target.sharedTypes.map((t) => t.name).join(', ');
+          implementationData += `import type { ${typeNames} } from '${commonTypesRelativeImport}';\n`;
+        }
+
         const importerPath = path.join(dirname, tag, tag + extension);
         const schemaCustomImportPath = getSchemasImportPath(output.schemas);
         const relativeSchemasPath = output.schemas
@@ -363,24 +404,46 @@ export async function writeSplitTagsMode({
     }
   }
 
+  let commonTypesFilePath: string | undefined;
+  if (deduplicationEnabled && collectedSharedTypes.length > 0) {
+    const commonTypesContent =
+      collectedSharedTypes
+        .map((t) => `${t.exported ? 'export ' : ''}${t.code}`)
+        .join('\n') + '\n';
+    commonTypesFilePath = commonTypesPath;
+    await writeGeneratedFile(commonTypesPath, commonTypesContent);
+  }
+
   let indexFilePath: string | undefined;
-  if (output.indexFiles && !output.workspace && tagEntries.length > 0) {
+  if (output.indexFiles && deduplicationEnabled && tagEntries.length > 0) {
     const importExtension = getImportExtension(
       output.fileExtension,
       output.tsconfig,
     );
     const serviceSuffix =
       OutputClient.ANGULAR === output.client ? '.service' : '';
-    const indexContent = tagEntries
+
+    const publicSharedTypeNames = collectedSharedTypes
+      .filter((t) => t.exported)
+      .map((t) => t.name);
+
+    const namedReExports =
+      publicSharedTypeNames.length > 0
+        ? `export type { ${publicSharedTypeNames.join(', ')} } from './${commonTypesBasename}${importExtension}';\n`
+        : '';
+
+    const tagReExports = tagEntries
       .map(([tag]) => {
         const tagFile = upath.joinSafe(
           './',
           tag,
           tag + serviceSuffix + importExtension,
         );
-        return `export * from '${tagFile}'\n`;
+        return `export * from '${tagFile}';\n`;
       })
       .join('');
+
+    const indexContent = namedReExports + tagReExports;
     indexFilePath = path.join(dirname, `index${extension}`);
     await writeGeneratedFile(indexFilePath, indexContent);
   }
@@ -392,6 +455,7 @@ export async function writeSplitTagsMode({
             path.join(mockDir, `index.${ext}${extension}`),
           )
         : []),
+      ...(commonTypesFilePath ? [commonTypesFilePath] : []),
       ...(indexFilePath ? [indexFilePath] : []),
       ...generatedFilePathsArray.flat(),
     ]),

packages/core/src/writers/target-tags.ts

@@ -251,6 +251,16 @@ export function generateTargetForTags(
           clientImplementation: target.implementation,
         });
 
+        const sharedTypes = header.sharedTypes;
+        const deduplicationActive =
+          options.tagsSplitDeduplication && !options.workspace;
+        const inlinedSharedTypes =
+          !deduplicationActive && sharedTypes && sharedTypes.length > 0
+            ? sharedTypes
+                .map((t) => `${t.exported ? 'export ' : ''}${t.code}`)
+                .join('\n') + '\n\n'
+            : '';
+
         // Apply the per-tag header/footer wrap to each mock output that has
         // accumulated handler entries. Mock outputs without a handler (faker
         // only) skip the wrap.
@@ -274,6 +284,7 @@ export function generateTargetForTags(
 
         transformed[tag] = {
           implementation:
+            inlinedSharedTypes +
             header.implementation +
             target.implementation +
             footer.implementation,
@@ -286,6 +297,7 @@ export function generateTargetForTags(
           paramsSerializer: target.paramsSerializer,
           paramsFilter: target.paramsFilter,
           fetchReviver: target.fetchReviver,
+          sharedTypes: deduplicationActive ? sharedTypes : undefined,
         };
       }
       allTargetTags = transformed;

packages/core/src/writers/target.ts

@@ -58,6 +58,7 @@ export function generateTarget(
     paramsSerializer: [],
     paramsFilter: [],
     fetchReviver: [],
+    sharedTypes: [],
   };
   const operations = Object.values(builder.operations);
   for (const [index, operation] of operations.entries()) {
@@ -146,7 +147,15 @@ export function generateTarget(
         clientImplementation: target.implementation,
       });
 
-      target.implementation = header.implementation + target.implementation;
+      const inlinedSharedTypes =
+        header.sharedTypes && header.sharedTypes.length > 0
+          ? header.sharedTypes
+              .map((t) => `${t.exported ? 'export ' : ''}${t.code}`)
+              .join('\n') + '\n\n'
+          : '';
+
+      target.implementation =
+        inlinedSharedTypes + header.implementation + target.implementation;
 
       const footer = builder.footer({
         outputClient: options.client,