docs/feat: clarify clean behavior and support generated-only cleanup

[aqeelat]

Problem

Orval's current output.clean behavior can be surprising when users generate into prepared package folders.

Observed behavior:

• Default behavior: Orval merges into target/schema folders and preserves unrelated files.
• Stale generated files may remain if tag filters shrink or generated paths change.
• With output.clean: true, Orval removes files in configured target/schema folders, including sentinel/package files.

This is risky when target or schemas points at a package entrypoint root containing files such as:

ng-package.json
package.json
public-api.ts

Documentation suggestion

Document clearly that users should not point target or schemas directly at a package entrypoint root if that root contains prepared files that should not be deleted.

The docs should explain that output.clean: true cleans the configured output folders, not only files generated by Orval.

Potential API improvement

Support generated-only cleanup:

output: {
  clean: {
    generatedOnly: true,
  },
}

Alternative approach:

• Generate a manifest file containing files emitted by the previous run.
• On the next run, clean only files listed in the previous manifest.
• Write a new manifest after generation.

Expected behavior

With generated-only cleanup enabled:

• Stale generated files from previous Orval runs are removed.
• Non-generated files such as package.json, ng-package.json, and public-api.ts are preserved.
• Users can safely generate into package-oriented folders without risking sentinel files.

Why this helps

• Avoids accidental deletion of package metadata.
• Reduces stale generated files when filters or tags change.
• Makes Orval safer for monorepos and package secondary entrypoints.

[aqeelat]

We've been looking at this and want to share our analysis before any implementation.

Current behavior

clean: true in generate-spec.ts globs **/* (excluding .d.ts) in the target and schemas directories, deletes everything, then removes empty directories. It runs per-project, sequentially, before generation.

Multi-project shared targets

Several samples (e.g., swr-with-zod, swr-with-effect) have multiple projects writing to the same target directory, differentiated by fileExtension:

// swr-with-zod/orval.config.ts
petstore:            { target: 'src/gen/endpoints', client: 'swr', clean: true }              // pets.ts, pets.msw.ts, pets.faker.ts
petstoreZod:         { target: 'src/gen/endpoints', client: 'zod', fileExtension: '.zod.ts' }  // pets.zod.ts
petstoreZodReusable: { target: 'src/gen/endpoints', client: 'zod', fileExtension: '-reusable.zod.ts' } // pets-reusable.zod.ts

Only the first project has clean: true — the others can't use it without deleting files from prior projects. Any generatedOnly cleanup would need to account for this.

Is generatedOnly needed?

Orval is primarily a CLI tool. SDK generation is typically orchestrated by build scripts where cleaning can be handled externally. The existing clean: true covers the wipe-and-regenerate pattern.

For the Angular secondary entrypoint case raised in the issue, the target can be nested inside the entrypoint:

my-entrypoint/
  ng-package.json
  package.json
  public-api.ts          # re-exports from ./generated
  generated/             # orval target, clean: true is safe here
    pets/
      pets.ts

clean: true only wipes generated/ — sentinel files are untouched. This is a trivial config change, not a structural limitation.

Question for maintainers: Is there a concrete use case where nesting the target isn't viable? If not, documenting the recommended output structure (generated files in a dedicated subdirectory) might be sufficient, and the generatedOnly feature may not be needed.

Design (if we proceed)

If there is a valid use case, we'd recommend a manifest-based approach:

output: {
  clean: {
    generatedOnly: true,
  },
}

Why manifest over header scanning: Every orval-generated file already starts with Generated by orval in the JSDoc header. Scanning for this is simple and stateless, but fragile — formatters or users could strip it, and it wouldn't catch files from older orval versions. A manifest file is more reliable.

Single shared manifest per directory: Given the multi-project pattern above, we'd use one .orval-manifest.json per output directory rather than per-project manifests. Each project that writes to a directory appends to the same manifest. This mirrors how clean already works (directory-scoped) and avoids orphaned files when a project is removed from the config.

1. Extend clean type to accept { generatedOnly: boolean } alongside existing boolean | string[].
2. When generatedOnly: true, read the previous manifest, delete only the listed files, then generate.
3. After generation, write an updated manifest with all files written by all projects sharing that directory.

[melloware]

@aqeelat Generated by orval is not required and users can override the generated header to whateve they want.

[melloware]

personally i think clean should definitely clean everything it needs to clean with as little config as possible.