File tracking and cleanup

When you rename a backend artifact, its old TypeScript file must disappear or consumers can keep importing a client that no longer has an endpoint. Arc identifies those stale files with inline metadata, rather than a separate JSON index.

How it works

An illustrative generated metadata line:

// @generated by Cratis. Source: MyApp.Commands.CreateOrder. Time: 2024-12-08T12:00:00.0000000Z. Hash: 1E9523083D8C6457F194B1CB045877E19BE204FB42F9F6E5574B77FC79B3ABDA

After generating the current artifacts, the executable:

1. Scans .ts files recursively below the output path, excluding index.ts.
2. Identifies files with valid generated metadata that were not produced in this run.
3. Deletes those orphaned files and attempts to clean their directories.
4. Updates barrel files unless index generation is skipped.

The scan is output-tree-wide, not partitioned by input assembly. Do not give independent generation runs the same output tree: one can regard another’s proxies as orphans.

For example, renaming UpdateOrder to ModifyOrder creates ModifyOrder.ts, removes the marked UpdateOrder.ts, and updates its exports. An unchanged CreateOrder.ts retains its timestamp when its existing metadata/hash matches in incremental mode.

Configuration limits

Setting	Current behavior
CratisProxiesSkipOutputDeletion=true	Prevents initial recursive output deletion; orphan cleanup still runs
CratisProxiesSkipIndexGeneration=true	Skips barrel creation/update; does not prevent orphan cleanup from deleting an index
CratisProxiesSkipFileIndexTracking=true	Forwarded by MSBuild, but ignored by the executable; does not disable cleanup

A manual export can also point at an entire sibling folder that has its own index.ts/index.tsx barrel, or re-export an npm package outright — both are preserved the same way:

// A hand-written folder with its own barrel (./List/index.ts)
export * from './List';

// A hand-written re-export of an entire package
export * from '@cratis/components';

export * from './CreateOrder';
export * from './UpdateOrder';

The generator only ever removes a relative export once its target genuinely stops resolving — a sibling file that no longer exists, or a sibling folder whose own barrel is gone. It never considers a bare/package specifier for removal, because it has no way to verify one on disk.

Note

Unlike every other generated file, index.ts never carries the // @generated by Cratis marker comment. Because it is a merge target you edit directly rather than a file the generator fully owns, marking it “generated” would make it eligible for the orphan-deletion pass described above, and would cause @cratis/eslint-plugin-arc’s skip-generated-proxies processor to stop linting the hand-written lines it contains. If you’d rather manage index.ts entirely yourself, see output behavior, controlled by CratisProxiesSkipIndexGeneration.

The executable no longer maintains .cratis/GeneratedFileIndex.json, and it does not consume --project-directory. Do not create, repair, or configure that retired index as part of a current setup.

See output behavior for the different MSBuild and direct-executable deletion defaults.

Barrel preservation is limited

During an index update, the generator recognizes export * from '…' lines, adds exports for generated files, and removes recognized exports whose targets are stale. It can retain existing exports to live .ts/.tsx files; it does not automatically add exports for arbitrary handwritten files.

Nonempty non-matching lines, such as imports and comments, are retained when rewriting, but moved before the managed exports. Blank lines and precise formatting are not preserved. This is not a general TypeScript-aware barrel editor.

A separate orphan-directory cleanup phase can delete index.ts without checking whether it is handwritten. Its emptiness test counts other .ts/.tsx files and subdirectories, not all file types. A directory containing only an index and non-TypeScript assets can lose its index before directory deletion fails because those assets remain. Skipping index generation does not bypass that phase.

For dependable isolation, keep handwritten source, assets, and public barrels outside the generated output directory. Do not rely on the skipped-tracking flag as a safety switch.

Troubleshooting

• A stale proxy remains: confirm it has valid first-line generated metadata and lies under the configured output path. Unmarked files are not recognized as orphans.
• Unexpected deletions: inspect the build log, output path, full-deletion setting, and whether another assembly shares that tree. Restore handwritten files from version control before rebuilding with isolated output.
• Unexpected Git diffs: full deletion recreates inline timestamps; configuration, grouping, or template changes can also change output.
• A barrel is missing or stale: inspect index-generation settings and cleanup messages. Review the actual exports rather than assuming all index edits survive.

Commit generated proxies when your frontend workflow consumes them directly, and review generated deletions in code review. Never edit a generated proxy to repair its backend contract; fix the source or generator configuration and rebuild.