fix(schemas): support splitByTags with indexFiles:false

When schemas are split by tag and there is no root barrel, operation
files (pets/pets.ts) and the consolidated <schemas>/index.faker.ts file
both previously emitted schema imports that didn't resolve. Operation
files imported '../model/pet' when the file lived at
'../model/pets/pet.ts'; the faker factory file imported types from '.'
when no root index.ts existed.

The root cause was that generateImportsForBuilder (used by every mode
writer) and writeFakerSchemaMocks both assumed a flat schemas directory
or a root barrel. Neither consulted the schema-to-tag map computed by
writeSchemasTagsSplit.

Compute the schema-to-tag map once in writeSpecs and thread it through:

- WriteModeProps: new optional schemaTagMap field
- generateImportsForBuilder: optional schemaTagMap param; the
  indexFiles:false branch routes each import into its tag subdir
  (or keeps shared schemas at the schemas root)
- single-mode / split-mode / tags-mode / split-tags-mode: forward
  schemaTagMap at all 13 generateImportsForBuilder call sites
- writeFakerSchemaMocks: same per-schema routing for the consolidated
  index.faker.ts file under indexFiles:false

Removes the validation guard that previously rejected the combination,
since the underlying import resolution now handles it correctly.

- packages/core/src/types.ts: add schemaTagMap? to WriteModeProps
- packages/core/src/writers/generate-imports-for-builder.ts: optional
  schemaTagMap param + tag-aware routing in indexFiles:false branch
- packages/core/src/writers/{single,split,tags,split-tags}-mode.ts:
  destructure schemaTagMap from WriteModeProps, forward to call sites
- packages/orval/src/write-specs.ts: hoist schemaTagMap computation to
  writeSpecs scope; thread to writeFakerSchemaMocks and writeMode;
  per-schema routing in writeFakerSchemaMocks under indexFiles:false
- packages/orval/src/utils/options.ts: remove the guard
- packages/orval/src/utils/options.test.ts: remove guard tests
- packages/core/src/writers/generate-imports-for-builder.test.ts: add
  splitByTags: false to two orval-labs#3618 schemasImportPath test cases that
  now require it (those test cases predate splitByTags becoming
  required in NormalizedSchemaOptions)
- docs/content/docs/reference/configuration/output.mdx: drop the
  indexFiles:true requirement note under splitByTags
- tests/configs/axios.config.ts: new splitByTagsFakerSchemasNoIndex
  config exercising the previously-broken combination
- tests/__snapshots__/axios/split-by-tags-faker-schemas-no-index/:
  snapshots for the new config
- tests/api-generation.spec.ts: 3 regression tests pinning per-tag
  import paths for operation files, faker factory file, and tag
  isolation

Author: aqeelat

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

@@ -224,10 +224,6 @@ import type { Error } from '../error';
   within their tag directories automatically.
 - Schema-to-tag mapping is transitive: if `Pet` imports `Dog` which imports
   `Dachshund`, all three land in the same directory.
-- Requires `indexFiles: true` (the default). The operation writers and the
-  consolidated `<schemas>/index.faker.ts` file currently route schema imports
-  through the schemas root barrel, which is not generated when `indexFiles`
-  is false.
 
 ### Validation of `importPath`
 

packages/core/src/types.ts

@@ -1792,6 +1792,14 @@ export interface WriteModeProps {
   header: string;
   needSchema: boolean;
   generateSchemasInline?: () => string;
+  // Schema-to-tag map computed by `writeSpecs` when `schemas.splitByTags` is
+  // enabled. Mode writers forward it to `generateImportsForBuilder` so the
+  // `indexFiles: false` branch can route each schema import into its tag
+  // subdirectory instead of assuming a flat layout. `undefined` when
+  // `splitByTags` is disabled, in which case routing falls back to the flat
+  // layout. The `'.'` sentinel marks schemas referenced by 0 or 2+ tags
+  // (shared, kept at the schemas root).
+  schemaTagMap?: Map<string, string>;
 }
 
 export interface GeneratorApiOperations {

packages/core/src/writers/generate-imports-for-builder.test.ts

@@ -335,6 +335,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
         mock: {
           indexMockFiles: false,
@@ -373,6 +374,7 @@ describe('generateImportsForBuilder', () => {
           path: '/libs/models',
           type: 'typescript',
           importPath: '@acme/models',
+          splitByTags: false,
         },
         mock: {
           indexMockFiles: false,

packages/core/src/writers/generate-imports-for-builder.ts

@@ -20,6 +20,11 @@ export function generateImportsForBuilder(
   output: NormalizedOutputOptions,
   imports: readonly GeneratorImport[],
   relativeSchemasPath: string,
+  // Schema→tag map computed by `writeSpecs` when `schemas.splitByTags` is
+  // enabled. Used only in the `indexFiles: false` branch to insert each
+  // schema's tag subdirectory into the import path. `'.'` is the sentinel
+  // for shared schemas (referenced by 0 or 2+ tags).
+  schemaTagMap?: Map<string, string>,
 ): GeneratorDependency[] {
   const isPackageImport =
     isObject(output.schemas) && !!output.schemas.importPath;
@@ -93,9 +98,17 @@ export function generateImportsForBuilder(
       const importExtension = isPackageImport
         ? ''
         : getImportExtension(output.fileExtension, output.tsconfig);
+      // When schemas are split by tag, route each import into its tag
+      // subdirectory. Schemas referenced by 0 or 2+ tags land at the schemas
+      // root (sentinel `'.'`); their path is unchanged from the flat layout.
+      // The lookup uses the original schema name (`schemaName` preferred),
+      // not the TS identifier, because `buildSchemaTagMap` keys on the
+      // original name.
+      const tagDir = schemaTagMap?.get(baseName);
+      const tagSegment = tagDir && tagDir !== '.' ? `${tagDir}/` : '';
       const dependency = upath.joinSafe(
         relativeSchemasPath,
-        `${normalizedName}${suffix}${importExtension}`,
+        `${tagSegment}${normalizedName}${suffix}${importExtension}`,
       );
 
       if (!importsByDependency.has(dependency)) {

packages/core/src/writers/single-mode.ts

@@ -36,6 +36,7 @@ export async function writeSingleMode({
   header,
   needSchema,
   generateSchemasInline,
+  schemaTagMap,
 }: WriteModeProps): Promise<string[]> {
   try {
     const {
@@ -143,6 +144,7 @@ export async function writeSingleMode({
           output,
           normalizedImports,
           relativeSchemasPath,
+          schemaTagMap,
         )
       : generateImportsForBuilder(
           output,
@@ -191,6 +193,7 @@ export async function writeSingleMode({
               output,
               filteredMockImports,
               relativeSchemasPath,
+              schemaTagMap,
             )
           : generateImportsForBuilder(
               output,
@@ -309,6 +312,7 @@ export async function writeSingleMode({
                 output,
                 mockOutput.imports,
                 mockRelativeSchemasPath,
+                schemaTagMap,
               )
             : generateImportsForBuilder(
                 output,

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

@@ -34,6 +34,7 @@ export async function writeSplitMode({
   header,
   needSchema,
   generateSchemasInline,
+  schemaTagMap,
 }: WriteModeProps): Promise<string[]> {
   try {
     const {
@@ -108,6 +109,7 @@ export async function writeSplitMode({
       output,
       imports,
       relativeSchemasPath,
+      schemaTagMap,
     );
 
     implementationData += builder.imports({
@@ -261,6 +263,7 @@ export async function writeSplitMode({
           finalizeMockOptions.strictSchemaTypeNames,
         ),
         mockRelativeSchemasPath,
+        schemaTagMap,
       );
       let mockData = header;
       mockData += builder.importsMock({

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

@@ -40,6 +40,7 @@ export async function writeSplitTagsMode({
   header,
   needSchema,
   generateSchemasInline,
+  schemaTagMap,
 }: WriteModeProps): Promise<string[]> {
   const { filename, dirname, extension } = getFileInfo(output.target, {
     backupFilename: conventionName(
@@ -188,6 +189,7 @@ export async function writeSplitTagsMode({
           output,
           adjustedImports,
           relativeSchemasPath,
+          schemaTagMap,
         );
 
         implementationData += builder.imports({
@@ -348,6 +350,7 @@ export async function writeSplitTagsMode({
               finalizeMockOptions.strictSchemaTypeNames,
             ),
             mockRelativeSchemasPath,
+            schemaTagMap,
           );
 
           let mockData = header;

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

@@ -42,6 +42,7 @@ export async function writeTagsMode({
   header,
   needSchema,
   generateSchemasInline,
+  schemaTagMap,
 }: WriteModeProps): Promise<string[]> {
   const {
     path: targetPath,
@@ -168,6 +169,7 @@ export async function writeTagsMode({
           output,
           normalizedImports,
           schemasPathRelative,
+          schemaTagMap,
         );
 
         data += builder.imports({
@@ -202,6 +204,7 @@ export async function writeTagsMode({
                   ),
               ),
               schemasPathRelative,
+              schemaTagMap,
             );
 
             data += builder.importsMock({
@@ -359,6 +362,7 @@ export async function writeTagsMode({
                 finalizeMockOptions.strictSchemaTypeNames,
               ),
               mockRelativeSchemasPath,
+              schemaTagMap,
             );
 
             let mockData = header;

packages/orval/src/utils/options.test.ts

@@ -1364,104 +1364,4 @@ describe('normalizeOptions', () => {
       }
     });
   });
-
-  describe('schemas.splitByTags with indexFiles', () => {
-    it('rejects splitByTags + indexFiles:false', async () => {
-      const workspace = await createTempWorkspace();
-
-      try {
-        await expect(
-          normalizeOptions(
-            {
-              input: {
-                target: {
-                  openapi: '3.1.0',
-                  info: { title: 'Test', version: '1.0.0' },
-                  paths: {},
-                },
-              },
-              output: {
-                target: './generated.ts',
-                schemas: {
-                  path: './models',
-                  type: 'typescript',
-                  splitByTags: true,
-                },
-                indexFiles: false,
-              },
-            },
-            workspace,
-          ),
-        ).rejects.toThrow(/splitByTags.*requires.*indexFiles.*true/s);
-      } finally {
-        await rm(workspace, { recursive: true, force: true });
-      }
-    });
-
-    it('accepts splitByTags + indexFiles:true (default)', async () => {
-      const workspace = await createTempWorkspace();
-
-      try {
-        const normalized = await normalizeOptions(
-          {
-            input: {
-              target: {
-                openapi: '3.1.0',
-                info: { title: 'Test', version: '1.0.0' },
-                paths: {},
-              },
-            },
-            output: {
-              target: './generated.ts',
-              schemas: {
-                path: './models',
-                type: 'typescript',
-                splitByTags: true,
-              },
-            },
-          },
-          workspace,
-        );
-
-        expect(normalized.output.schemas).toMatchObject({
-          splitByTags: true,
-        });
-        // `indexFiles` defaults to true; splitByTags should be accepted.
-        expect(normalized.output.indexFiles).toBe(true);
-      } finally {
-        await rm(workspace, { recursive: true, force: true });
-      }
-    });
-
-    it('does not reject indexFiles:false when splitByTags is not set', async () => {
-      const workspace = await createTempWorkspace();
-
-      try {
-        const normalized = await normalizeOptions(
-          {
-            input: {
-              target: {
-                openapi: '3.1.0',
-                info: { title: 'Test', version: '1.0.0' },
-                paths: {},
-              },
-            },
-            output: {
-              target: './generated.ts',
-              schemas: {
-                path: './models',
-                type: 'typescript',
-              },
-              indexFiles: false,
-            },
-          },
-          workspace,
-        );
-
-        expect(normalized.output.indexFiles).toBe(false);
-      } finally {
-        await rm(workspace, { recursive: true, force: true });
-      }
-    });
-  });
 });

packages/orval/src/utils/options.ts

@@ -755,26 +755,6 @@ export async function normalizeOptions(
     );
   }
 
-  // `schemas.splitByTags` routes schema files into per-tag subdirectories and
-  // (when `indexFiles: false`) skips the root barrel. Operation files and the
-  // consolidated `<schemas>/index.faker.ts` file both currently assume either
-  // a flat schemas directory or a root barrel, so without `indexFiles: true`
-  // they emit imports that don't resolve (e.g. `../model/pet` when the file
-  // lives at `../model/pets/pet.ts`). Reject the combination until the import
-  // resolvers are taught to honor `splitByTags` directly.
-  if (
-    isObject(normalizedOptions.output.schemas) &&
-    normalizedOptions.output.schemas.splitByTags &&
-    !normalizedOptions.output.indexFiles
-  ) {
-    throw new Error(
-      styleText(
-        'red',
-        `\`schemas.splitByTags\` currently requires \`output.indexFiles: true\`. With \`indexFiles: false\`, operation files and the consolidated faker factory file emit schema imports that don't resolve against the per-tag layout. Set \`indexFiles: true\` (the default) or remove \`splitByTags\`.`,
-      ),
-    );
-  }
-
   return normalizedOptions;
 }