Skip to content

add the planetscale plugin - #134

Merged
brandonphelps1212 merged 4 commits into
mainfrom
planetscale-plugin
Nov 20, 2026
Merged

brandonphelps1212 merged 4 commits into
mainfrom
planetscale-plugin

Conversation

@brandonphelps1212

Copy link
Copy Markdown
Contributor

What this changes

Adds planetscale, an openapi plugin for PlanetScale's platform API. Part of #75 (I11.7 · Watch PlanetScale), under #14.

  • Source: schemas/openapi.yaml in planetscale/terraform-provider-planetscale (Apache-2.0, PlanetScale's own org), read at the newest commit that changed it.

    • It's a copy of the live spec, https://planetscale.com/docs/openapi.yaml. That has no versions, and Wayback holds 1 snapshot. A weekly bot PR syncs the copy and a maintainer merges it.
    • The trade-off: events can arrive late, after the merge. Some commits are hand edits, but those can't create a deprecation: only PlanetScale's "Deprecated." text does.
  • version is the commit date. info.version is a fixed v1.

  • Deprecations are only said in words: the spec has never set deprecated: true. A description starting Deprecated. or Deprecated: (case-insensitive) marks the operation (DeprecatedDescription). It's matched only at the start and only on the operation, so "Deprecated, storage shrinking…" on a property doesn't count.

  • Rule: Vercel's deprecationsOnly.

  • Operation names include /v1 (GET /v1/organizations/…), the path a caller sends, via the shared adapter.ServerBasePath. This protects against a future move of /v1 turning deprecated operations into false removals.

  • Refuses a file that isn't a spec: missing, unparseable, or without paths. One commit in the history deleted the file and it came back the same day. Rather than diffing against that, Run errors and emits nothing.

  • History: over all 31 consecutive pairs it keeps exactly 5 events, the deprecations on 2026-11-09:

    • GET and DELETE …/bouncers/{bouncer}/resizes;
    • GET …/neki-changes;
    • GET and DELETE …/neki-changes/{id}.

    The 41 unmarked removals (renames, a method change, routes the Go SDK still calls) are dropped.

For the maintainers: the test data's license

The spec file states no license ("© 2026 PlanetScale, Inc."), although the repo it's in is Apache-2.0. The test data is trimmed: openapi, info, the path items involved and the 2-line servers block, every line unchanged. Please confirm that's acceptable.

Needs a client change

planetscale must be added to the patch-it client's list of date-versioned APIs, like neon and convex. That's a separate PR in the client repo.

Checklist

  • Added to docs/plugins.md: new row, status live. docs/plugins.json regenerated, README badge 27. I compared the row's words with the plugin.
  • Every commit is signed off (DCO)
  • Golden test: replay e631095a → fc13e09d, 5 deprecation events. Each quote is checked against the YAML as published.
  • Pinned drop test: b49c3540 → f6d6ad4d, the read-only to dedicated read-replica rename, 0 events. With the filter off it gives 7 removals, so the test isn't vacuous.
  • Tests for path-parameter renames and for flag quoting. Each fails if its option is removed.
  • testdata/README.md rows: URL at the commit, date, license, quote.
  • providers/planetscale.md from the template, with Why this source and Known gaps:
    • deprecations announced only in the changelog or docs, like /workflows;
    • sync lag and hand edits;
    • the database-js 2.0 breaking change.
  • Fetches only through the fetch layer.
  • make check passes.
  • Nothing private.

Notes for the reviewer

An independent review replayed all 31 history pairs and searched every version and the live spec.

  • Nothing emitted is wrong: no operation is described as deprecated apart from the 5.
  • Every regex and keep-rule mutation it tried makes a test fail.
  • The trimmed and full files give the same golden.

Its two suggestions are in the third commit: tests for the two untested options, and the base-path protection.

🤖 Generated with Claude Code

brandonphelps1212 and others added 3 commits November 19, 2026 19:15
Watches the PlanetScale API spec (schemas/openapi.yaml in
planetscale/terraform-provider-planetscale, a copy of
planetscale.com/docs/openapi.yaml), pinned to the commit that last
changed it, version = commit date. Deprecations are read from the
start of the operation's description ("Deprecated. Use ... instead.");
keep rule is deprecationsOnly. A fetched file with no paths is refused.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
…tions by the path a caller sends

Move the server's /v1 into the paths with the shared adapter.ServerBasePath,
so a spec that moves it can't read as every deprecated operation removed
(the trimmed test copies keep the spec's two-line servers block). Test
PathTemplates and QuoteDeprecatedOperation. Keep both plugins' rows; badge 26.

Signed-off-by: brandonphelps1212 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
@claude

claude Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Claude finished @brandonphelps1212's task in 1m 41s —— View job


✅ Ready to merge: the plugin follows every repo rule, its tests and checks pass, and I found no path that would emit a wrong event. The one problem I found is a garbled package doc comment, which isn't blocking.

Rules

Rule Status Evidence
Plugin list (Rule 1) ✅ Added adapter.PlanetScale{} to the registry and to registered_test.go. The new docs/plugins.md row sits between the markers, uses absolute links and has status live. I compared it with the code: the id, the provider, the source (schemas/openapi.yaml in planetscale/terraform-provider-planetscale), what it watches and the format (openapi) all match. docs/plugins.json count and README badge are both 27.
Provider page ✅ providers/planetscale.md follows the template. Why this source has the link, the check date (2026-11-19), why it's the best source, 6 alternatives and a quote. Known gaps is thorough. It's listed in providers/README.md.
Golden test and quote ✅ TestPlanetScaleGolden replays e631095a → fc13e09d and gets 5 deprecations. Each event's excerpt is checked against the saved YAML at its SourcePointer, and each must start with "Deprecated. Use ". Both pairs have testdata/README.md rows with the URL at the commit, the date, the license and a quote.
Drop test ✅ TestPlanetScaleDropsRemovalsThatWerentDeprecated replays b49c3540 → f6d6ad4d and gets 0 events. With Keep off the same pair gives the 7 removals, so the test isn't vacuous.
Fetch only via env ✅ adapter/planetscale.go uses only fetch.Get. net/http appears only in _test.go files (httptest). No filesystem or database access outside the tests.
Nothing private (Rule 2) ✅ Code, docs, test data, commit messages and the PR body contain no credentials, internal names or session links. The leak guard passes.
DCO ✅ Every commit on the branch has a Signed-off-by.

Bugs

None blocking.

Precision. deprecationsOnly(planetscaleDiff) keeps a removal only when the old operation was marked deprecated: either the flag, or a description starting with Deprecated./Deprecated:, matched by (?i)^\s*deprecated[.:].

  • The regex is anchored at the start and applied only to operations. So "Deprecated, storage shrinking…" on a property, and "deprecated" further into a description, aren't matched. Both cases have tests.
  • Fetch refuses a 404, YAML that doesn't parse, and a file without paths, so a deleted or stub file can't turn into "every operation removed".
  • ServerBasePath plus PathTemplates covers a /v1 move and a renamed path parameter.

Verified

Command Result
go build ./... ok
go vet ./... clean
gofmt -l . printed nothing
go test -race ./... every package ok, including adapter and plugins/openapi. This includes the docs/plugins.json freshness check.
python3 scripts/leak_guard.py --all "no banned terms (8 hashed terms checked)"

I could not run make imports nethttp todos: the command needs approval in this job. I searched by hand instead: there's no net/http outside the tests and no TODO(new-plugin) in the changed files.

Non-blocking

  • Package doc garbled by the merge (plugins/openapi/openapi.go:7-10, inline comment). The four new lines were added under the old paragraph instead of replacing it, so the doc reads "…Sentry, Neon): … releases. Algolia, Elasticsearch, Sentry, PlanetScale): …". Convex is also missing from the list. This shows on pkg.go.dev, so it's worth fixing before merge. Fix this →
  • For the maintainers: please answer the PR body's question about the test data's license. The spec file states no license (only "© 2026 PlanetScale, Inc."), but the repo it's in is Apache-2.0, and the excerpts are trimmed. The client-side follow-up (adding planetscale to the client's list of date-versioned APIs) is noted in the PR body and in the provider page's Known gaps.

Comment thread plugins/openapi/openapi.go Outdated
Comment on lines +7 to +10
// Algolia, Elasticsearch, Sentry, PlanetScale): fetch the newest spec, diff it against the
// last one seen, normalize the changes into events, and attach migration
// hints from the API's changelog when it has one. It can also replay two
// given releases.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The merge left the package doc garbled. These 4 lines were added under the old paragraph instead of replacing it, so the doc now reads "…Sentry, Neon): … two given releases. Algolia, Elasticsearch, Sentry, PlanetScale): …". It builds, but this is what pkg.go.dev shows. Convex is missing from the list too. Suggested fix: delete these 4 lines and make lines 1–6 one paragraph:

// Package openapi is the source plugin for an API that publishes an OpenAPI
// spec per release (Stripe, Datadog, GitLab, GitHub, Vercel, Supabase,
// Algolia, Elasticsearch, Sentry, Neon, Convex, PlanetScale): fetch the newest
// spec, diff it against the last one seen, normalize the changes into events,
// and attach migration hints from the API's changelog when it has one. It can
// also replay two given releases.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Signed-off-by: brandonphelps1212 <[email protected]>
@brandonphelps1212
brandonphelps1212 merged commit b5f8eff into main Nov 20, 2026
4 checks passed
@brandonphelps1212
brandonphelps1212 deleted the planetscale-plugin branch November 20, 2026 00:39
@brandonphelps1212 brandonphelps1212 mentioned this pull request Nov 20, 2026
15 tasks
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