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

docs/content/docs/reference/configuration/output.mdx

@@ -618,6 +618,70 @@ import { getPetMock } from '@acme/data-layer/sdk/fakers';
 
 Generate `index.ts` files for schemas.
 
+## tagsSplitDeduplication
+
+**Type:** `Boolean`
+**Default:** `false`
+
+In `tags-split` mode, extract shared infrastructure types (e.g. `HTTPStatusCode*` emitted by the fetch client) into a single `common-types.ts` file and generate a barrel `index.ts` at the target root.
+
+When enabled alongside [`indexFiles: true`](#indexfiles):
+
+- Shared types that would otherwise be duplicated across per-tag files are collected and written once to `[commonTypesFileName].ts`
+- Each per-tag file imports shared types from the common file instead of declaring them inline
+- A barrel `index.ts` is generated with named re-exports for public shared types plus `export *` re-exports for each per-tag implementation file
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      mode: 'tags-split',
+      target: './src/api/endpoints.ts',
+      schemas: './src/api/model',
+      client: 'fetch',
+      indexFiles: true,
+      tagsSplitDeduplication: true,
+    },
+  },
+});
+```
+
+Resulting structure:
+
+```
+src/api/
+├── common-types.ts           ← shared types extracted once
+├── index.ts                  ← barrel with named + wildcard re-exports
+├── pets/
+│   └── pets.ts               ← import type { ... } from '../common-types'
+└── health/
+    └── health.ts             ← import type { ... } from '../common-types'
+```
+
+When disabled (default), shared types are inlined per-tag and no barrel is generated — identical to previous behavior.
+
+Suppressed when [`workspace`](#workspace) is set (the workspace barrel handles aggregation).
+
+## commonTypesFileName
+
+**Type:** `String`
+**Default:** `'common-types'`
+
+The file name (without extension) used for the shared types file when [`tagsSplitDeduplication`](#tagssplitdeduplication) is enabled.
+
+```ts title="orval.config.ts"
+export default defineConfig({
+  petstore: {
+    output: {
+      mode: 'tags-split',
+      indexFiles: true,
+      tagsSplitDeduplication: true,
+      commonTypesFileName: 'shared',  // generates shared.ts
+    },
+  },
+});
+```
+
 ## docs
 
 **Type:** `Boolean | Object`

docs/content/docs/zh/reference/configuration/output.mdx

@@ -139,6 +139,20 @@ export default defineConfig({
 
 控制是否生成 index 文件。拆分模式下通常保持开启，便于统一导入。
 
+## tagsSplitDeduplication
+
+**类型：** `Boolean`
+**默认值：** `false`
+
+在 `tags-split` 模式下，将共享的基础设施类型（如 fetch 客户端的 `HTTPStatusCode*`）提取到单独的 `common-types.ts` 文件中，并在目标根目录生成 barrel `index.ts`。需要同时开启 `indexFiles: true`。
+
+## commonTypesFileName
+
+**类型：** `String`
+**默认值：** `'common-types'`
+
+当 `tagsSplitDeduplication` 开启时，共享类型文件的文件名（不含扩展名）。
+
 ## docs
 
 生成接口文档相关输出。只有需要把生成产物和文档系统集成时再开启。

packages/angular/src/http-client.test.ts

@@ -147,6 +147,8 @@ const createOutput = (
     optionsParamRequired: false,
     unionAddMissingProperties: false,
     propertySortOrder: 'Specification',
+    tagsSplitDeduplication: false,
+    commonTypesFileName: 'common-types',
     factoryMethods: {
       functionNamePrefix: 'create',
       mode: 'single',

packages/angular/src/http-resource.test.ts

@@ -157,6 +157,8 @@ const createOutput = (
     optionsParamRequired: false,
     unionAddMissingProperties: false,
     propertySortOrder: 'Specification',
+    tagsSplitDeduplication: false,
+    commonTypesFileName: 'common-types',
     factoryMethods: {
       functionNamePrefix: 'create',
       mode: 'single',
@@ -940,7 +942,7 @@ describe('angular httpResource generator', () => {
       routeRegistry.set('getPetById', '/api/pets/${petId}');
       routeRegistry.set('createPet', '/api/pets');
 
-      const header = generateHttpResourceHeader({
+      const rawHeader = generateHttpResourceHeader({
         title: 'PetService',
         isRequestOptions: true,
         isMutator: false,
@@ -952,6 +954,9 @@ describe('angular httpResource generator', () => {
         clientImplementation: '',
       } as never);
 
+      const header =
+        typeof rawHeader === 'string' ? rawHeader : rawHeader.implementation;
+
       expect(header.match(/type AngularHttpParamValue =/g)).toHaveLength(1);
       expect(header.match(/preserveRequiredNullables = false,/g)).toHaveLength(
         1,
@@ -2633,7 +2638,7 @@ describe('angular httpResource generator', () => {
       const verbOption = createVerbOption();
       routeRegistry.set('getPetById', '/api/pets/${petId}');
 
-      return generateHttpResourceHeader({
+      const result = generateHttpResourceHeader({
         title: 'PetService',
         isRequestOptions: true,
         isMutator: false,
@@ -2644,6 +2649,8 @@ describe('angular httpResource generator', () => {
         verbOptions: { getPetById: verbOption },
         clientImplementation: '',
       } as never);
+
+      return typeof result === 'string' ? result : result.implementation;
     };
 
     it('encodes the signal path parameter when urlEncodeParameters is true', () => {

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);
+  });
 });