Skip to content

Add pkg/plan: one versioned dry-run report for both front doors - #8

Draft
Kiran01bm wants to merge 1 commit into
kiran01bm/oss-standupfrom
kiran01bm/p2-5-plan-contract
Draft

Add pkg/plan: one versioned dry-run report for both front doors#8
Kiran01bm wants to merge 1 commit into
kiran01bm/oss-standupfrom
kiran01bm/p2-5-plan-contract

Conversation

@Kiran01bm

Copy link
Copy Markdown
Collaborator

Summary

Consolidates the engine's two ad-hoc dry-run JSON shapes into one versioned, machine-readable plan contract: pkg/plan.Report. Both front doors — migrate --dry-run --json and diff --json — now emit the same shape, so an orchestrator adapter parses one contract regardless of how the plan was derived. First slice of the P2.5 dry-run/advisory surface; a real linter and an advisory suggest command stack on top of this.

What

  • New pkg/plan: Report with format_version: 1, a typed source (alter | diff), and a shared Statement carrying SQL, route, backend, disposition, per-operation decisions, and the safer exec_sql sequence.
  • migrate --dry-run --json emits plan.Report instead of raw router.Plan; diff --json emits it instead of the private diffReport.
  • table_exists is optional (pointer): set only by the diff path, which introspects for existence; omitted for the alter path.
  • Empty plans serialize statements as [], never null; consumers reject unknown format_version.
  • Text (non-JSON) output, routing behavior, and debug logging are unchanged.
  • Contract pinned by an exact-JSON-shape unit test; pkg/plan at 100% statement coverage.

Why

The dry-run report is the seam a future orchestration adapter consumes to decide whether and how a change would execute. Two divergent, unversioned shapes made that seam fragile: consumers had to know which command produced the JSON and could not detect contract drift. One versioned report removes both problems before the linter and suggest surfaces widen the contract.

Before / after

Before:
  migrate --dry-run --json ──> router.Plan        (unversioned)
  diff --json ───────────────> diffReport (private, unversioned)

After:
  migrate --dry-run --json ──┐
                             ├──> plan.Report  format_version: 1
  diff --json ───────────────┘    source: alter | diff

References

migrate --dry-run --json and diff --json previously emitted two ad-hoc
JSON shapes (router.Plan and a private diffReport). Consolidate them
into a single versioned plan.Report (format_version 1) so an
orchestrator adapter parses one contract regardless of how the plan
was derived. Groundwork for PLAT-38440 (dry-run plan + suggest surface).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant