Skip to main content

Editable generated code

The files at outputDir are application code. You can edit any generated file. Each run compares your edits with new generated code, one top-level TypeScript declaration at a time.

The generator stores the last generation's fingerprints in outputDir/.pg-sourcerer/manifest.json. A fingerprint is a SHA-256 hash of text. Commit this manifest with your code. It holds declaration hashes and import names, rather than a second copy of the generated code. Keys have a stable sorted order for review.

What the manifest records​

For each TypeScript file, the manifest records two hashes per declaration key: its leading comments and its complete text. It also records specifier names for each named-import group. A group identifies a module and whether the import is type-only. Other files have one hash of their whole text.

A declaration key contains its kind and name. Repeated keys, such as function overloads, get occurrence numbers. Separators between statements are layout, not part of the declaration hash. TypeScript hashes use normalized LF line endings.

Each comparison uses three inputs:

  • base is the fingerprint from the last generation.
  • ours is your current file.
  • theirs is the newly generated file, after the configured formatter and validation.

A missing file supplies empty text. The generator considers only paths in the manifest or the new output. It never reads or writes other files in the output directory.

Declaration decisions​

Changes since the baseResult
Only the generator changed itTake the new generated declaration
Only you changed itKeep your declaration
Both made the same changeKeep that change once
Both changed it differently, even on separate linesWrite a both changed conflict
Both added the same key differentlyWrite a both added conflict
You deleted it and the generator left it unchangedKeep it deleted
You deleted it and the generator changed itWrite a conflict
The generator dropped it and you left it unchangedRemove it
The generator dropped it and you edited itWrite a conflict

Your declarations keep their order. A new declaration goes near its neighbours in the new output. Named imports merge as sets. An import you removed returns if the new generated code still needs it. Same-line comments belong to their statements. Removing the first statement removes its separator unless an input explicitly starts with a blank line.

When your file uses CRLF line endings, the merge operates on LF and restores CRLF in the result. The generator does not format the merged text.

Files ending in .ts, .tsx, .mts, or .cts use declaration comparisons. Other files compare whole-file hashes. Equal versions resolve directly. Different edits on both sides conflict for the whole file, reported under the declaration name (file).

The storage trade​

A small hash manifest avoids duplicate generated code. A hash can show that text changed, but cannot recover the old text. The generator therefore cannot merge separate line edits inside a declaration that both sides changed.

Conflicts use two-way markers:

<<<<<<< yours
user's declaration
=======
new generated declaration
>>>>>>> generated

A deletion leaves the corresponding side empty. The old base text is unavailable and never appears inside the markers.

Validation, writes and recovery​

The generator validates relative paths and typechecks the pristine TypeScript output before publication. The .pg-sourcerer directory is reserved for its state. It decodes the manifest with an Effect Schema, parses the current and generated modules, and plans every change before writing files. A parse failure names its path and side and leaves the tree and manifest unchanged.

The publisher writes application files first, then the new manifest. A crash can leave an old manifest with some new files. Run the generator again to recover. Declarations already written match the new generation and resolve cleanly against the old hashes.

Conflicts still write both the marked files and the new manifest. Resolve the markers before the next run. The next run uses the generation you resolved against as its base.

If the merged text is empty and either side is absent, the tree file stays absent or is deleted. The same rule applies when the merged text and new generated text are both empty. If the new generated text is empty, the generator removes the path from the manifest. Otherwise, the manifest records the new pristine hashes and import names.

The publish report contains written, created, deleted and conflicts. Paths in created also appear in written. Unchanged tree files appear in none of these path lists. Each conflict holds path, declaration and reason. The CLI prints each conflict as path:declaration: reason and exits with code 1.

Publication can expose partial writes during a run. Retry recovery replaces an atomic directory switch so that application files remain directly editable.