Rescanning Incrementally Without Losing Edits

Quick answer: Incremental rescans use a discovery.json sidecar to track what was already detected, so a new scan updates only the parts that changed instead of rebuilding the whole document. Your edits to the generated OpenAPI are preserved rather than overwritten. This keeps repeated scans fast as the code evolves and avoids redoing the refinements you already made.

Why a full rebuild is the wrong default

A generated document rarely stays untouched. After the first scan you adjust descriptions, fix a gap, and tighten contracts by hand. If every later scan rebuilt the document from scratch, those edits would be wiped each time, and you would be forced to choose between a fresh scan and your own refinements.

The sidecar removes that trade-off by recording the discovery state between runs.

What the discovery sidecar carries

The discovery.json sidecar keeps the evidence the scan already produced, so the next run knows the baseline.

On a rescan, the tool reads the sidecar, examines what changed, and updates the affected parts rather than re-emitting everything.

How edits stay safe

The scan treats your manual refinements as values to keep, not as temporary output to replace.

1. The first scan writes the document and the discovery sidecar.
2. You edit the generated OpenAPI and fill gaps.
3. A later scan reads the sidecar and detects the changed code.
4. It updates the affected routes while preserving your edits.
5. New unknowns are marked as gaps rather than overwriting your work.

This matters when a codebase changes a little at a time. A handful of new or modified routes should not force a full re-reading or a full re-edit of an otherwise stable document.

Conflict handling is worth a moment. A changed handler can touch a route you also edited, and the tool has to reconcile two inputs rather than pick one blindly. It keeps your manual value where the code change does not affect it, and it flags the overlap where the new code and your edit disagree, so you can read the diff instead of discovering the overwrite later. The sidecar is the reference that makes that comparison possible, because it remembers which values were yours and which came from the scan.

Limits and honest reading

The sidecar reflects the state at the last scan, so a large structural change can still require a careful review rather than a silent merge. When the framework wiring changes in a way the old baseline did not anticipate, confirm the updated routes rather than assuming the incremental diff is complete.

A successful scan still does not prove the implementation conforms, and the scan does not run the app. Preserving edits keeps the document stable, but it does not certify the runtime behavior. Source code is not sent anywhere by default.

Powerduck keeps the discovery sidecar and the preservation logic in the desktop workflow, so repeated scans build on the earlier evidence instead of resetting it.

Frequently asked questions

Will a rescan overwrite my manual edits? No. The discovery.json sidecar lets the scan update only what changed while preserving your edits to the generated document.

What does the sidecar track? It records the detected routes, their provenance, the changed files, and the edits to keep, so the next scan has a baseline.

When should I review a rescan closely? When the code change is large or alters the framework wiring, rather than just adding a small route. Confirm the updated routes before adopting them.

The bottom line

Incremental rescans build on a discovery.json sidecar rather than rebuilding from scratch, updating only the changed routes and keeping your manual edits intact. That keeps the workflow fast as the code evolves and stops you from choosing between a fresh scan and your own refinements. Treat large structural changes as a review point, and remember a scan still does not prove conformance. The sidecar is what makes repeated generation safe. Read more in the code-to-OpenAPI guide.