From edb69689b3f377cbb66d4ff049b11aa8c4b0bc2a Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:43:16 -0500 Subject: [PATCH 1/2] move shared code to core/ and readers under their kind core/ holds what isn't one kind: the plugin contract and registry, fetch, kit and kittest, the event types, migrate, and the OpenAPI diff engine with normalize and hint. The spec adapters move to plugins/openapi/adapter, the deprecations-page reader to plugins/retirements/retire and the migration guide reader to plugins/migrationguide/sdkguide. The old import paths that patch-it's hosted ingestion service uses (plugin, event, fetch, migrate, kit, kit/kittest, retire, sdkguide) stay as deprecated packages that only forward to the new ones. The newest-release, newest-commit-on-a-path and commit-date lookups that nine adapters, apichangelog and catalog each decoded themselves are now one helper, core/github. Also regenerates docs/plugins.json and the README badge (out of date on main since the salesforce plugin) and gofmts vercel_test.go. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- .github/pull_request_template.md | 2 +- .github/workflows/CI_contract.yml | 2 +- .github/workflows/CI_go.yml | 2 +- .github/workflows/claude-code-review.yml | 2 +- .github/workflows/claude.yml | 2 +- AGENTS.md | 22 +- CONTRIBUTING.md | 2 +- Makefile | 4 +- README.md | 13 +- cmd/new-plugin/formats.go | 32 +-- cmd/new-plugin/main.go | 7 +- cmd/new-plugin/main_test.go | 2 +- {diff => core/diff}/diff.go | 2 +- {diff => core/diff}/diff_test.go | 0 {diff => core/diff}/options_test.go | 0 core/event/event.go | 215 +++++++++++++++ {event => core/event}/event_test.go | 6 +- {event => core/event}/v2.go | 0 {event => core/event}/v2_test.go | 2 +- {fetch => core/fetch}/cache.go | 0 {fetch => core/fetch}/cache_test.go | 0 core/fetch/fetch.go | 135 ++++++++++ {fetch => core/fetch}/fetch_test.go | 0 core/github/github.go | 126 +++++++++ core/github/github_test.go | 58 ++++ {hint => core/hint}/hint.go | 2 +- {hint => core/hint}/hint_test.go | 2 +- {hint => core/hint}/stripe.go | 2 +- {hint => core/hint}/testdata/README.md | 0 {hint => core/hint}/testdata/endive.md | 0 .../polymorphic-billing-cycle-anchor.md | 0 ...-payment-method-types-checkout-sessions.md | 0 .../hint}/testdata/removed-payto-fields.md | 0 ...-from-payment-intents-and-setup-intents.md | 0 .../hint}/testdata/trial-offer-ga.md | 0 core/kit/kit.go | 48 ++++ {kit => core/kit}/kit_test.go | 4 +- {kit => core/kit}/kittest/checksink.go | 4 +- core/kit/kittest/kittest.go | 214 +++++++++++++++ {kit => core/kit}/kittest/mem.go | 4 +- {kit => core/kit}/kittest/mem_test.go | 4 +- {kit => core/kit}/wayback.go | 2 +- {kit => core/kit}/wayback_test.go | 0 core/migrate/migrate.go | 120 +++++++++ {migrate => core/migrate}/migrate_test.go | 4 +- {normalize => core/normalize}/golden_test.go | 2 +- {normalize => core/normalize}/normalize.go | 4 +- .../normalize}/normalize_test.go | 4 +- .../normalize}/testdata/README.md | 0 .../breaking-property-removed/events.json | 0 .../golden/breaking-property-removed/new.json | 0 .../golden/breaking-property-removed/old.json | 0 .../testdata/golden/deprecation/events.json | 0 .../testdata/golden/deprecation/new.json | 0 .../testdata/golden/deprecation/old.json | 0 .../golden/identical-specs/events.json | 0 .../testdata/golden/identical-specs/new.json | 0 .../testdata/golden/identical-specs/old.json | 0 .../testdata/golden/new-endpoint/events.json | 0 .../testdata/golden/new-endpoint/new.json | 0 .../testdata/golden/new-endpoint/old.json | 0 core/plugin/plugin.go | 141 ++++++++++ {plugin => core/plugin}/plugin_test.go | 2 +- docs/plugins.json | 2 +- docs/writing-a-plugin.md | 18 +- event/event.go | 245 +++-------------- fetch/fetch.go | 144 +--------- internal/pluginlist/pluginlist.go | 2 +- kit/kit.go | 56 ++-- kit/kittest/kittest.go | 235 ++-------------- migrate/migrate.go | 124 +-------- plugin/plugin.go | 154 ++--------- plugins/all/all_test.go | 2 +- plugins/apichangelog/apichangelog.go | 21 +- plugins/apichangelog/apichangelog_test.go | 4 +- plugins/catalog/catalog.go | 18 +- plugins/catalog/catalog_test.go | 6 +- plugins/catalog/registered_test.go | 2 +- plugins/changelog/changelog.go | 4 +- plugins/changelog/changelog_test.go | 2 +- plugins/changelog/classify.go | 2 +- plugins/changelog/registered_test.go | 2 +- plugins/eol/eol.go | 8 +- plugins/eol/eol_test.go | 6 +- plugins/feed/cloudflare_test.go | 4 +- plugins/feed/feed.go | 6 +- plugins/feed/feed_test.go | 2 +- plugins/feed/readers.go | 2 +- plugins/feed/registered_test.go | 2 +- plugins/migrationguide/golden_test.go | 6 +- plugins/migrationguide/migrationguide.go | 6 +- plugins/migrationguide/migrationguide_test.go | 6 +- plugins/migrationguide/registered_test.go | 4 +- plugins/migrationguide/sdkguide/sdkguide.go | 174 ++++++++++++ .../migrationguide/sdkguide}/sdkguide_test.go | 2 +- .../sdkguide}/testdata/README.md | 0 .../testdata/anthropic-MIGRATION-v1.0.0.md | 0 .../openapi/adapter}/adapter.go | 0 .../openapi/adapter}/algolia.go | 21 +- .../openapi/adapter}/algolia_test.go | 0 .../openapi/adapter}/appwrite.go | 35 +-- .../openapi/adapter}/appwrite_test.go | 0 .../openapi/adapter}/convex.go | 36 +-- .../openapi/adapter}/convex_test.go | 0 .../openapi/adapter}/datadog.go | 16 +- .../openapi/adapter}/datadog_test.go | 0 .../openapi/adapter}/elasticsearch.go | 17 +- .../openapi/adapter}/elasticsearch_test.go | 0 .../openapi/adapter}/flagsmith.go | 16 +- .../openapi/adapter}/github.go | 5 +- .../openapi/adapter}/github_test.go | 0 .../openapi/adapter}/gitlab.go | 2 +- .../openapi/adapter}/gitlab_test.go | 0 {adapter => plugins/openapi/adapter}/neon.go | 36 +-- .../openapi/adapter}/neon_test.go | 0 .../openapi/adapter}/planetscale.go | 36 +-- .../openapi/adapter}/planetscale_test.go | 0 .../openapi/adapter}/sentry.go | 9 +- .../openapi/adapter}/sentry_test.go | 0 .../openapi/adapter}/stripe.go | 28 +- .../openapi/adapter}/stripe_test.go | 0 .../openapi/adapter}/supabase.go | 36 +-- .../openapi/adapter}/supabase_test.go | 0 .../openapi/adapter}/vercel.go | 16 +- .../openapi/adapter}/vercel_test.go | 0 plugins/openapi/algolia.go | 2 +- plugins/openapi/algolia_test.go | 8 +- plugins/openapi/appwrite.go | 2 +- plugins/openapi/appwrite_test.go | 8 +- plugins/openapi/convex.go | 2 +- plugins/openapi/convex_test.go | 6 +- plugins/openapi/datadog_test.go | 2 +- plugins/openapi/elasticsearch.go | 2 +- plugins/openapi/elasticsearch_test.go | 6 +- plugins/openapi/flagsmith_test.go | 4 +- plugins/openapi/github_test.go | 2 +- plugins/openapi/gitlab_test.go | 2 +- plugins/openapi/neon.go | 2 +- plugins/openapi/neon_test.go | 6 +- plugins/openapi/openapi.go | 14 +- plugins/openapi/openapi_test.go | 10 +- plugins/openapi/planetscale.go | 2 +- plugins/openapi/planetscale_test.go | 8 +- plugins/openapi/registered_test.go | 4 +- plugins/openapi/sentry.go | 2 +- plugins/openapi/sentry_test.go | 8 +- plugins/openapi/supabase.go | 2 +- plugins/openapi/supabase_test.go | 6 +- plugins/openapi/vercel.go | 2 +- plugins/openapi/vercel_test.go | 14 +- plugins/removedmembers/golden_test.go | 2 +- plugins/removedmembers/newrelic_test.go | 4 +- plugins/removedmembers/posthog_test.go | 4 +- plugins/removedmembers/registered_test.go | 2 +- plugins/removedmembers/removedmembers.go | 4 +- plugins/removedmembers/removedmembers_test.go | 4 +- plugins/retirements/golden_test.go | 6 +- plugins/retirements/registered_test.go | 4 +- .../retirements/retire}/providers.go | 0 plugins/retirements/retire/retire.go | 245 +++++++++++++++++ .../retirements/retire}/retire_test.go | 2 +- .../retirements/retire}/testdata/README.md | 0 .../testdata/anthropic-deprecations.md | 0 .../retire}/testdata/openai-deprecations.md | 0 plugins/retirements/retirements.go | 8 +- plugins/retirements/retirements_test.go | 6 +- providers/anthropic-models.md | 2 +- providers/anthropic.md | 2 +- providers/flagsmith.md | 2 +- providers/openai-models.md | 2 +- providers/stripe.md | 2 +- retire/retire.go | 252 ++---------------- scripts/check_contract.py | 4 +- sdkguide/sdkguide.go | 183 ++----------- 174 files changed, 1940 insertions(+), 1705 deletions(-) rename {diff => core/diff}/diff.go (99%) rename {diff => core/diff}/diff_test.go (100%) rename {diff => core/diff}/options_test.go (100%) create mode 100644 core/event/event.go rename {event => core/event}/event_test.go (97%) rename {event => core/event}/v2.go (100%) rename {event => core/event}/v2_test.go (99%) rename {fetch => core/fetch}/cache.go (100%) rename {fetch => core/fetch}/cache_test.go (100%) create mode 100644 core/fetch/fetch.go rename {fetch => core/fetch}/fetch_test.go (100%) create mode 100644 core/github/github.go create mode 100644 core/github/github_test.go rename {hint => core/hint}/hint.go (99%) rename {hint => core/hint}/hint_test.go (99%) rename {hint => core/hint}/stripe.go (99%) rename {hint => core/hint}/testdata/README.md (100%) rename {hint => core/hint}/testdata/endive.md (100%) rename {hint => core/hint}/testdata/polymorphic-billing-cycle-anchor.md (100%) rename {hint => core/hint}/testdata/remove-payment-method-types-checkout-sessions.md (100%) rename {hint => core/hint}/testdata/removed-payto-fields.md (100%) rename {hint => core/hint}/testdata/removes-the-payment-method-types-parameter-from-payment-intents-and-setup-intents.md (100%) rename {hint => core/hint}/testdata/trial-offer-ga.md (100%) create mode 100644 core/kit/kit.go rename {kit => core/kit}/kit_test.go (94%) rename {kit => core/kit}/kittest/checksink.go (97%) create mode 100644 core/kit/kittest/kittest.go rename {kit => core/kit}/kittest/mem.go (97%) rename {kit => core/kit}/kittest/mem_test.go (91%) rename {kit => core/kit}/wayback.go (98%) rename {kit => core/kit}/wayback_test.go (100%) create mode 100644 core/migrate/migrate.go rename {migrate => core/migrate}/migrate_test.go (97%) rename {normalize => core/normalize}/golden_test.go (98%) rename {normalize => core/normalize}/normalize.go (98%) rename {normalize => core/normalize}/normalize_test.go (97%) rename {normalize => core/normalize}/testdata/README.md (100%) rename {normalize => core/normalize}/testdata/golden/breaking-property-removed/events.json (100%) rename {normalize => core/normalize}/testdata/golden/breaking-property-removed/new.json (100%) rename {normalize => core/normalize}/testdata/golden/breaking-property-removed/old.json (100%) rename {normalize => core/normalize}/testdata/golden/deprecation/events.json (100%) rename {normalize => core/normalize}/testdata/golden/deprecation/new.json (100%) rename {normalize => core/normalize}/testdata/golden/deprecation/old.json (100%) rename {normalize => core/normalize}/testdata/golden/identical-specs/events.json (100%) rename {normalize => core/normalize}/testdata/golden/identical-specs/new.json (100%) rename {normalize => core/normalize}/testdata/golden/identical-specs/old.json (100%) rename {normalize => core/normalize}/testdata/golden/new-endpoint/events.json (100%) rename {normalize => core/normalize}/testdata/golden/new-endpoint/new.json (100%) rename {normalize => core/normalize}/testdata/golden/new-endpoint/old.json (100%) create mode 100644 core/plugin/plugin.go rename {plugin => core/plugin}/plugin_test.go (97%) create mode 100644 plugins/migrationguide/sdkguide/sdkguide.go rename {sdkguide => plugins/migrationguide/sdkguide}/sdkguide_test.go (97%) rename {sdkguide => plugins/migrationguide/sdkguide}/testdata/README.md (100%) rename {sdkguide => plugins/migrationguide/sdkguide}/testdata/anthropic-MIGRATION-v1.0.0.md (100%) rename {adapter => plugins/openapi/adapter}/adapter.go (100%) rename {adapter => plugins/openapi/adapter}/algolia.go (88%) rename {adapter => plugins/openapi/adapter}/algolia_test.go (100%) rename {adapter => plugins/openapi/adapter}/appwrite.go (88%) rename {adapter => plugins/openapi/adapter}/appwrite_test.go (100%) rename {adapter => plugins/openapi/adapter}/convex.go (76%) rename {adapter => plugins/openapi/adapter}/convex_test.go (100%) rename {adapter => plugins/openapi/adapter}/datadog.go (86%) rename {adapter => plugins/openapi/adapter}/datadog_test.go (100%) rename {adapter => plugins/openapi/adapter}/elasticsearch.go (89%) rename {adapter => plugins/openapi/adapter}/elasticsearch_test.go (100%) rename {adapter => plugins/openapi/adapter}/flagsmith.go (87%) rename {adapter => plugins/openapi/adapter}/github.go (94%) rename {adapter => plugins/openapi/adapter}/github_test.go (100%) rename {adapter => plugins/openapi/adapter}/gitlab.go (99%) rename {adapter => plugins/openapi/adapter}/gitlab_test.go (100%) rename {adapter => plugins/openapi/adapter}/neon.go (74%) rename {adapter => plugins/openapi/adapter}/neon_test.go (100%) rename {adapter => plugins/openapi/adapter}/planetscale.go (77%) rename {adapter => plugins/openapi/adapter}/planetscale_test.go (100%) rename {adapter => plugins/openapi/adapter}/sentry.go (97%) rename {adapter => plugins/openapi/adapter}/sentry_test.go (100%) rename {adapter => plugins/openapi/adapter}/stripe.go (76%) rename {adapter => plugins/openapi/adapter}/stripe_test.go (100%) rename {adapter => plugins/openapi/adapter}/supabase.go (69%) rename {adapter => plugins/openapi/adapter}/supabase_test.go (100%) rename {adapter => plugins/openapi/adapter}/vercel.go (83%) rename {adapter => plugins/openapi/adapter}/vercel_test.go (100%) rename {retire => plugins/retirements/retire}/providers.go (100%) create mode 100644 plugins/retirements/retire/retire.go rename {retire => plugins/retirements/retire}/retire_test.go (99%) rename {retire => plugins/retirements/retire}/testdata/README.md (100%) rename {retire => plugins/retirements/retire}/testdata/anthropic-deprecations.md (100%) rename {retire => plugins/retirements/retire}/testdata/openai-deprecations.md (100%) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 30b6631..020aa01 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,7 +10,7 @@ - [ ] `testdata/README.md` lists each file: URL, date fetched, license, quote of the part the plugin reads - [ ] One pinned drop test: a realistic input that produces no event - [ ] `providers/.md` written or updated from `providers/_template.md`, including **Why this source** -- [ ] Fetches only through `env.Get` / `kit/` +- [ ] Fetches only through `env.Get` / `core/kit/` - [ ] `make check` passes locally (and `make plugins-json` was run if a plugin or its row changed) - [ ] Nothing private: no credentials, internal hosts, private links, customer names diff --git a/.github/workflows/CI_contract.yml b/.github/workflows/CI_contract.yml index 7818684..0ddd5cb 100644 --- a/.github/workflows/CI_contract.yml +++ b/.github/workflows/CI_contract.yml @@ -1,5 +1,5 @@ # contract/fixtures/ is a copy of patch-it's fixtures/ (the change-event contract -# patch-it owns). This fails when the two drift apart, so event/ and migrate/ test +# patch-it owns). This fails when the two drift apart, so core/event/ and core/migrate/ test # the same events the patch-it client does. Only top-level "_comment" fields may # differ (scripts/check_contract.py). # diff --git a/.github/workflows/CI_go.yml b/.github/workflows/CI_go.yml index 8f21644..315ed6f 100644 --- a/.github/workflows/CI_go.yml +++ b/.github/workflows/CI_go.yml @@ -1,7 +1,7 @@ # The plugins build, are formatted and vetted, and their tests pass with the race # detector. Two guards keep plugins self-contained: # - imports: only this module, the standard library and the approved dependencies; -# - network: net/http only in the fetch layer (fetch/, kit/, adapter/). +# - network: net/http only in the fetch layer (core/fetch/, core/kit/, plugins/openapi/adapter/). # The steps are Makefile targets, so `make check` runs exactly this locally. # Until the Go code lands there is no go.mod, and every step after the first is skipped # with a notice, so the check passes. diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 2a41f67..6f33f2f 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -110,7 +110,7 @@ jobs: the source URL and a quote. A golden file edited without the PR explaining why the new output is right is blocking. 5. PLUGIN CODE. Fetch only through env.Get or kit/: no net/http outside the - fetch layer (fetch/, kit/, adapter/), no filesystem outside testdata/, no + fetch layer (core/fetch/, core/kit/, plugins/openapi/adapter/), no filesystem outside testdata/, no database. Precision over recall: flag any path that could emit an event for something that isn't a real change; a wrong event becomes a wrong pull request in someone's repo. Don't change contract/fixtures/ here first (the diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 4fc0a79..aabd647 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -68,4 +68,4 @@ jobs: --permission-mode default --allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*)" --disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*),Bash(git add:*),Bash(git rm:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files" - --append-system-prompt "This is patch-it-plugins, a public repo of source plugins. Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check it against AGENTS.md: (1) every new, changed or removed plugin has its row added, updated or removed in docs/plugins.md between the plugins:start and plugins:end markers, absolute links only; (2) every new provider has providers/.md from providers/_template.md with a real 'Why this source' (link, date checked, why it's best, alternatives, quote); (3) a golden test over a real saved source, a testdata/README.md row (URL, date fetched, license, quote), one pinned drop test, every event carries its source URL and a quote, and golden edits are explained; (4) fetch only through env.Get or kit/, no net/http outside fetch/, kit/ and adapter/, no filesystem outside testdata/; (5) precision over recall: flag anything that could emit an event for a non-change; (6) nothing private: no credentials, internal hostnames or service names, links to private repos or tickets, customer names, or links to AI sessions. You can't run the tests; say that CI_go covers them. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then a table of rule | status | evidence, blocking bugs, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link." + --append-system-prompt "This is patch-it-plugins, a public repo of source plugins. Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check it against AGENTS.md: (1) every new, changed or removed plugin has its row added, updated or removed in docs/plugins.md between the plugins:start and plugins:end markers, absolute links only; (2) every new provider has providers/.md from providers/_template.md with a real 'Why this source' (link, date checked, why it's best, alternatives, quote); (3) a golden test over a real saved source, a testdata/README.md row (URL, date fetched, license, quote), one pinned drop test, every event carries its source URL and a quote, and golden edits are explained; (4) fetch only through env.Get or core/kit/, no net/http outside core/fetch/, core/kit/ and plugins/openapi/adapter/, no filesystem outside testdata/; (5) precision over recall: flag anything that could emit an event for a non-change; (6) nothing private: no credentials, internal hostnames or service names, links to private repos or tickets, customer names, or links to AI sessions. You can't run the tests; say that CI_go covers them. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then a table of rule | status | evidence, blocking bugs, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link." diff --git a/AGENTS.md b/AGENTS.md index 9c6764a..4dedcad 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -26,7 +26,7 @@ Refer to the service that runs these plugins as "patch-it's hosted ingestion ser ## Rules for plugin code - **Start a new provider with `go run ./cmd/new-plugin --api --provider --format `**, then fill in every `TODO(new-plugin)`; `make todos` (part of `make check` and CI_go) fails while one is left. -- **Fetch only through the environment** (`env.Get` or `kit/`). No `net/http` outside the fetch layer, no filesystem outside `testdata/`, no database. +- **Fetch only through the environment** (`env.Get` or `core/kit/`). No `net/http` outside the fetch layer, no filesystem outside `testdata/`, no database. - **Golden test + dated source quote**: a saved copy of the real source in `testdata/`, a row in `testdata/README.md` (URL, date fetched, license, quote), and `testdata/golden/.json` with the exact events. - **Precision over recall.** When unsure whether something is a change, don't emit an event. - **One pinned drop test** per plugin: a realistic input that must produce no event. @@ -51,16 +51,20 @@ One target at a time: `make tidy`, `make build`, `make fmt`, `make vet`, `make i Go module `github.com/patch-it-dev/patch-it-plugins`; the only dependency is `gopkg.in/yaml.v3`. ``` -plugin/ the Plugin interface, the registry, Env, Result, Spec (baselines) +core/plugin/ the Plugin interface, the registry, Env, Result, Spec (baselines) +core/fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache +core/github/ the newest release / commit on GitHub, and a commit's SHA and date (one place) +core/kit/ core/kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden) +core/event/ core/migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 +core/diff/ core/normalize/ core/hint/ the OpenAPI diff engine and its helpers +plugins// one package per kind, with its providers: openapi (+ adapter/, one spec adapter + per provider), retirements (+ retire/), migrationguide (+ sdkguide/), + removedmembers, changelog, feed, apichangelog, catalog, eol; + plugins/all imports every one +plugin/ event/ fetch/ migrate/ kit/ retire/ sdkguide/ deprecated old import paths: they only + forward to the packages above; don't add to them cmd/list-plugins/ writes docs/plugins.json (make plugins-json); internal/pluginlist/ is its logic cmd/new-plugin/ scaffolds a provider on a format plugin (go run ./cmd/new-plugin --help) -plugins// one package per format plugin: openapi, retirements, migrationguide, - removedmembers, changelog, feed, apichangelog, catalog; plugins/all imports every one -kit/ kit/kittest/ Unchanged, Cite, Wayback; the test kit (Mem, Pages, Ingest, Golden) -event/ migrate/ the change-event types from patch-it's contract (v1 + v2), v1 -> v2 -fetch/ the HTTP fetch with retries and the ETag / Last-Modified cache -diff/ normalize/ hint/ adapter/ the OpenAPI diff engine and the spec adapters -retire/ sdkguide/ deprecations-page and migration-guide readers contract/fixtures/ a copy of patch-it's change-event fixtures (CI_contract checks it) docs/plugins.md the list of supported plugins (Rule 1); docs/plugins.json is generated from it Makefile make check (what CI_go runs, plus the leak guard), make plugins-json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 69d5d46..7a2fde0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Thanks for helping patch-it watch more APIs. This file is the rulebook; [docs/wr ## The rules 1. **Add your plugin to [docs/plugins.md](docs/plugins.md).** Every new plugin gets a row; every change to a plugin's id, provider, source, what it watches or status updates its row. The list on docs.patch-it.dev is built from that file, so a plugin that isn't listed is invisible to users. Then run `make plugins-json` to regenerate [`docs/plugins.json`](docs/plugins.json); it fails if the registry and the table disagree, and the tests fail while the JSON is out of date. -2. **Fetch only through the environment.** Plugins get their sources from `env.Get` or the helpers in `kit/`, never from `net/http` directly, the filesystem or a database. That keeps tests offline and lets the hosted service cache, retry and rate-limit politely. +2. **Fetch only through the environment.** Plugins get their sources from `env.Get` or the helpers in `core/kit/`, never from `net/http` directly, the filesystem or a database. That keeps tests offline and lets the hosted service cache, retry and rate-limit politely. 3. **Every plugin has a golden test** over a real saved copy of its source: `testdata/` in, `testdata/golden/.json` out. `testdata/README.md` lists each file with its URL, the date you fetched it, its license, and a short quote of the part your plugin reads. Keep openly licensed files whole; trim vendor documentation pages to what the test needs. 4. **Precision over recall.** A missed change is a bug we can fix later. A wrong change becomes a wrong pull request in someone's repo. When in doubt, don't emit. 5. **One pinned drop test per plugin**: a realistic input your plugin must *not* turn into an event (an unrelated section, a renamed heading, a non-breaking addition). diff --git a/Makefile b/Makefile index 23ddf94..75bd27f 100644 --- a/Makefile +++ b/Makefile @@ -52,7 +52,7 @@ imports: nethttp: @bad=$$($(GO) list -f '{{.ImportPath}} {{join .Imports " "}}' ./... \ | grep -E '(^| )net/http( |$$)' | cut -d' ' -f1 \ - | grep -vE '^$(MODULE)/(fetch|kit|adapter)(/|$$)' || true); \ + | grep -vE '^$(MODULE)/(core/fetch|core/kit|plugins/openapi/adapter)(/|$$)' || true); \ if [ -n "$$bad" ]; then \ echo "::error::these packages import net/http; fetch through env.Get or kit instead:"; echo "$$bad"; exit 1; \ fi @@ -64,7 +64,7 @@ test: # A provider started with new-plugin is done when nothing it wrote still says # TODO(new-plugin). -TODO_DIRS := plugins adapter retire sdkguide migrate providers docs/plugins.md +TODO_DIRS := plugins core/migrate providers docs/plugins.md todos: @left=$$(grep -rl 'TODO(new-plugin)' $(TODO_DIRS) || true); \ if [ -n "$$left" ]; then \ diff --git a/README.md b/README.md index 99b99a4..870f92c 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![Go Reference](https://pkg.go.dev/badge/github.com/patch-it-dev/patch-it-plugins.svg)](https://pkg.go.dev/github.com/patch-it-dev/patch-it-plugins) [![Go version](https://img.shields.io/github/go-mod/go-version/patch-it-dev/patch-it-plugins)](go.mod) [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-3f5bf0)](LICENSE) -[![Plugins](https://img.shields.io/badge/plugins-29-3f5bf0)](docs/plugins.md) +[![Plugins](https://img.shields.io/badge/plugins-30-3f5bf0)](docs/plugins.md) [![Docs](https://img.shields.io/badge/docs-docs.patch--it.dev-3f5bf0)](https://docs.patch-it.dev) [![Discussions](https://img.shields.io/github/discussions/patch-it-dev/patch-it-plugins)](https://github.com/patch-it-dev/patch-it-plugins/discussions) @@ -96,14 +96,15 @@ Most providers are an entry for a shared format plugin (`openapi`, `retirements` | Path | What's there | |---|---| -| [`plugin/`](plugin/) | The `Plugin` interface, the registry (`Register`, `Lookup`, `Names`), `Env`, `Result` | +| [`core/plugin/`](core/plugin/) | The `Plugin` interface, the registry (`Register`, `Lookup`, `Names`), `Env`, `Result` | | [`plugins/`](plugins/) | The format plugins; `plugins/all` imports every one | | [`cmd/new-plugin/`](cmd/new-plugin/), [`cmd/list-plugins/`](cmd/list-plugins/) | The starter for a new provider; the generator of `docs/plugins.json` | -| [`kit/`](kit/), [`kit/kittest/`](kit/kittest/) | What plugins share (the unchanged-page check, Wayback citing) and the test kit (in-memory store, saved pages, golden files) | -| [`event/`](event/), [`migrate/`](migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | -| [`diff/`](diff/), [`normalize/`](normalize/), [`hint/`](hint/), [`adapter/`](adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider | -| [`retire/`](retire/), [`sdkguide/`](sdkguide/), [`fetch/`](fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache | +| [`core/kit/`](core/kit/), [`core/kit/kittest/`](core/kit/kittest/), [`core/github/`](core/github/) | What plugins share (the unchanged-page check, Wayback citing, the newest release or commit on GitHub) and the test kit (in-memory store, saved pages, golden files) | +| [`core/event/`](core/event/), [`core/migrate/`](core/migrate/) | The change-event types of [patch-it's contract](https://github.com/patch-it-dev/patch-it/tree/main/docs/contract), and the v1 → v2 conversion | +| [`core/diff/`](core/diff/), [`core/normalize/`](core/normalize/), [`core/hint/`](core/hint/), [`plugins/openapi/adapter/`](plugins/openapi/adapter/) | The OpenAPI diff engine: compare two specs, turn the changes into events, attach changelog hints; one adapter per spec provider | +| [`plugins/retirements/retire/`](plugins/retirements/retire/), [`plugins/migrationguide/sdkguide/`](plugins/migrationguide/sdkguide/), [`core/fetch/`](core/fetch/) | The deprecations-page and migration-guide readers; the HTTP fetch and cache | | [`contract/fixtures/`](contract/) | A copy of patch-it's change-event fixtures | +| `plugin/`, `event/`, `fetch/`, `migrate/`, `kit/`, `kit/kittest/`, `retire/`, `sdkguide/` | Deprecated: the old import paths, forwarding to the packages above until code that imports them moves | | [`providers/`](providers/) | One page per provider: why that source, what the plugin reads | | [`docs/`](docs/) | [The plugin list](docs/plugins.md), [how to write a plugin](docs/writing-a-plugin.md), the [README template](docs/README-template.md) patch-it's public repos share | diff --git a/cmd/new-plugin/formats.go b/cmd/new-plugin/formats.go index e6a0b75..038f03f 100644 --- a/cmd/new-plugin/formats.go +++ b/cmd/new-plugin/formats.go @@ -76,12 +76,12 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Feed: {{.Ident}}, Archiver: archive}) } `, - imports: []string{"github.com/patch-it-dev/patch-it-plugins/event"}, + imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, }, "retirements": { layer: "AI models", - defDir: "retire", + defDir: "plugins/retirements/retire", def: `package retire import "strings" @@ -104,7 +104,7 @@ var {{.Ident}} = Page{ } `, register: `plugin.Register(Plugin{Page: retire.{{.Ident}}, Archiver: kit.Wayback{}})`, - mapEntry: &mapEntry{"migrate/migrate.go", "providers", `retire.{{.Ident}}.API: "{{.Slug}}"`}, + mapEntry: &mapEntry{"core/migrate/migrate.go", "providers", `retire.{{.Ident}}.API: "{{.Slug}}"`}, pluginOf: `Plugin{Page: retire.{{.Ident}}}`, fixtures: map[string]string{"{{.File}}-deprecations.md": `# Placeholder deprecations page @@ -149,12 +149,12 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: retire.{{.Ident}}, Archiver: archive}) } `, - imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/event", "github.com/patch-it-dev/patch-it-plugins/retire"}, + imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire"}, }, "migrationguide": { layer: "SDK", - defDir: "sdkguide", + defDir: "plugins/migrationguide/sdkguide", def: `package sdkguide // {{.Ident}} is {{.Provider}}'s SDK guide to a major release (MIGRATION.md at @@ -173,7 +173,7 @@ var {{.Ident}} = Guide{ } `, register: `plugin.Register(Plugin{Guide: sdkguide.{{.Ident}}})`, - mapEntry: &mapEntry{"migrate/migrate.go", "guides", `sdkguide.{{.Ident}}.API: sdkguide.{{.Ident}}`}, + mapEntry: &mapEntry{"core/migrate/migrate.go", "guides", `sdkguide.{{.Ident}}.API: sdkguide.{{.Ident}}`}, pluginOf: `Plugin{Guide: sdkguide.{{.Ident}}}`, fixtures: map[string]string{"{{.File}}-MIGRATION.md": `# Migrating to v1 @@ -215,7 +215,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.Ingest(t, Plugin{Guide: sdkguide.{{.Ident}}}, kittest.Pages{sdkguide.{{.Ident}}.URL(): file}) } `, - imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/event", "github.com/patch-it-dev/patch-it-plugins/sdkguide"}, + imports: []string{"encoding/json", "strings", "github.com/patch-it-dev/patch-it-plugins/core/event", "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide"}, }, "removedmembers": { @@ -290,7 +290,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.Ingest(t, Plugin{Guide: {{.Ident}}}, kittest.Pages{ {{.Ident}}.URL(): file}) } `, - imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/event"}, + imports: []string{"slices", "github.com/patch-it-dev/patch-it-plugins/core/event"}, }, "changelog": { @@ -327,7 +327,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.Ingest(t, Plugin{File: {{.Ident}}}, kittest.Pages{ {{.Ident}}.URL(): file}) } `, - imports: []string{"github.com/patch-it-dev/patch-it-plugins/event"}, + imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, }, "apichangelog": { @@ -364,7 +364,7 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { }) } `, - imports: []string{"github.com/patch-it-dev/patch-it-plugins/event"}, + imports: []string{"github.com/patch-it-dev/patch-it-plugins/core/event"}, }, "catalog": { @@ -413,12 +413,12 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.Stored(t, sink) } `, - imports: []string{"context", "github.com/patch-it-dev/patch-it-plugins/event"}, + imports: []string{"context", "github.com/patch-it-dev/patch-it-plugins/core/event"}, }, "openapi": { layer: "API", - defDir: "adapter", + defDir: "plugins/openapi/adapter", def: `package adapter import ( @@ -440,12 +440,12 @@ func ({{.Ident}}) API() string { return "{{.ID}}" } // LatestTag is the newest release of the spec. func ({{.Ident}}) LatestTag(ctx context.Context) (string, error) { - return "", fmt.Errorf("{{.ID}}: LatestTag isn't written yet (adapter/{{.File}}.go)") + return "", fmt.Errorf("{{.ID}}: LatestTag isn't written yet (plugins/openapi/adapter/{{.File}}.go)") } // Fetch downloads the spec at tag. func ({{.Ident}}) Fetch(ctx context.Context, tag string) (Spec, error) { - return Spec{}, fmt.Errorf("{{.ID}}: Fetch isn't written yet (adapter/{{.File}}.go)") + return Spec{}, fmt.Errorf("{{.ID}}: Fetch isn't written yet (plugins/openapi/adapter/{{.File}}.go)") } `, register: `plugin.Register(Plugin{Adapter: adapter.{{.Ident}}{}})`, @@ -487,8 +487,8 @@ func {{.Lower}}Ingest(t *testing.T, file string) []event.EventV2 { return kittest.Stored(t, sink) } `, - imports: []string{"context", "fmt", "os", "github.com/patch-it-dev/patch-it-plugins/adapter", "github.com/patch-it-dev/patch-it-plugins/event"}, - next: "Write LatestTag and Fetch in adapter/{{.File}}.go (fetch.Get only); add Diff/Keep to the Register line if the spec needs them (see vercel.go).", + imports: []string{"context", "fmt", "os", "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter", "github.com/patch-it-dev/patch-it-plugins/core/event"}, + next: "Write LatestTag and Fetch in plugins/openapi/adapter/{{.File}}.go (fetch.Get only); add Diff/Keep to the Register line if the spec needs them (see vercel.go).", }, } diff --git a/cmd/new-plugin/main.go b/cmd/new-plugin/main.go index 7e4dd1d..a33de7e 100644 --- a/cmd/new-plugin/main.go +++ b/cmd/new-plugin/main.go @@ -5,7 +5,8 @@ // go run ./cmd/new-plugin --api acme --provider Acme --format openapi // // It writes the provider's definition in the format's package (or the reader -// package the format uses: adapter/, retire/, sdkguide/), adds its +// package the format uses: plugins/openapi/adapter/, plugins/retirements/retire/, +// plugins/migrationguide/sdkguide/), adds its // plugin.Register line to plugins/'s init, a test (registered, golden, // drop) over placeholder sources with an empty golden file, a row in that // testdata/README.md, providers/.md from providers/_template.md and a @@ -35,8 +36,8 @@ import ( "time" "unicode" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" "github.com/patch-it-dev/patch-it-plugins/internal/pluginlist" - "github.com/patch-it-dev/patch-it-plugins/plugin" _ "github.com/patch-it-dev/patch-it-plugins/plugins/all" ) @@ -167,7 +168,7 @@ func Run(o Options, out io.Writer) error { d.PluginOf = fill(f.pluginOf, d) d.Ingest = fill(f.ingest, d) d.Drop = fill(f.drop, d) - d.Imports = append(slices.Clone(f.imports), "testing", "github.com/patch-it-dev/patch-it-plugins/kit/kittest") + d.Imports = append(slices.Clone(f.imports), "testing", "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest") slices.Sort(d.Imports) pkgDir := "plugins/" + o.Format diff --git a/cmd/new-plugin/main_test.go b/cmd/new-plugin/main_test.go index 4fbbecd..209a5d4 100644 --- a/cmd/new-plugin/main_test.go +++ b/cmd/new-plugin/main_test.go @@ -38,7 +38,7 @@ func TestScaffoldEveryFormat(t *testing.T) { t.Errorf("%s: no next steps in\n%s", f, out.String()) } } - for _, args := range [][]string{{"build", "./..."}, {"vet", "./..."}, {"test", "-count=1", "./plugins/...", "./internal/...", "./migrate/..."}} { + for _, args := range [][]string{{"build", "./..."}, {"vet", "./..."}, {"test", "-count=1", "./plugins/...", "./internal/...", "./core/migrate/..."}} { cmd := exec.Command(goCmd, args...) cmd.Dir = root if b, err := cmd.CombinedOutput(); err != nil { diff --git a/diff/diff.go b/core/diff/diff.go similarity index 99% rename from diff/diff.go rename to core/diff/diff.go index c012569..e675458 100644 --- a/diff/diff.go +++ b/core/diff/diff.go @@ -19,7 +19,7 @@ import ( "sort" "strings" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // Kind is the shape of one structural difference. It is deliberately finer diff --git a/diff/diff_test.go b/core/diff/diff_test.go similarity index 100% rename from diff/diff_test.go rename to core/diff/diff_test.go diff --git a/diff/options_test.go b/core/diff/options_test.go similarity index 100% rename from diff/options_test.go rename to core/diff/options_test.go diff --git a/core/event/event.go b/core/event/event.go new file mode 100644 index 0000000..d17f1c9 --- /dev/null +++ b/core/event/event.go @@ -0,0 +1,215 @@ +package event + +import ( + "crypto/sha256" + "encoding/hex" + "fmt" + "regexp" + "strings" + "time" + "unicode/utf8" +) + +type ( + ChangeType string + AffectedKind string + Side string +) + +const ( + ChangeTypeBreaking ChangeType = "breaking" + ChangeTypeDeprecation ChangeType = "deprecation" + ChangeTypeNewFeature ChangeType = "new_feature" + ChangeTypeFix ChangeType = "fix" +) + +const ( + AffectedKindOperation AffectedKind = "operation" + AffectedKindRequestParameter AffectedKind = "request_parameter" + AffectedKindSchema AffectedKind = "schema" + AffectedKindSchemaProperty AffectedKind = "schema_property" +) + +const ( + SideRequest Side = "request" + SideResponse Side = "response" +) + +type Affected struct { + Kind AffectedKind `json:"kind"` // kind of change + Side Side `json:"side"` // which side is breaking + Operation string `json:"operation,omitempty"` // if operation change, what changed + Schema string `json:"schema,omitempty"` // if schema change, what changed + Property string `json:"property,omitempty"` // if poperty change, what changed + // Value is the one value of Property the change is about, when it's about one: + // the retired model name for a model retirement ("gpt-4"). Optional. + Value string `json:"value,omitempty"` +} + +type ChangeEvent struct { + ID int64 `json:"id"` + Fingerprint string `json:"fingerprint"` + API string `json:"api"` + Version string `json:"version"` + PreviousVersion string `json:"previous_version,omitempty"` + ChangeType ChangeType `json:"change_type"` + Breaking bool `json:"breaking"` + Affected Affected `json:"affected"` + Description string `json:"description"` + MigrationHint string `json:"migration_hint,omitempty"` + SourceURL string `json:"source_url"` + SourcePointer string `json:"source_pointer,omitempty"` + SourceExcerpt string `json:"source_excerpt"` + Confidence float64 `json:"confidence"` + DetectedAt time.Time `json:"detected_at"` +} + +// Fingerprint identifies one change at one location, so re-running ingest over +// the same specs updates nothing instead of duplicating events. detail is what +// separates two changes at the same place: the enum value added, the old and +// new type, "added as required". Absent fields are empty strings, and the parts +// are joined with a separator that cannot appear in a path or a schema name. +func Fingerprint(api, version string, changeType ChangeType, affected Affected, detail string) string { + sum := sha256.Sum256([]byte(strings.Join([]string{ + api, + version, + string(changeType), + string(affected.Kind), + string(affected.Side), + affected.Operation, + affected.Schema, + affected.Property, + detail, + }, "|"))) + return "sha256:" + hex.EncodeToString(sum[:]) +} + +// fingerprintPattern is the contract's shape for a fingerprint (the schema's +// pattern in the change event contract). patch-it checks the same pattern. +var fingerprintPattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`) + +func (e ChangeEvent) Validate() error { + if err := checkCommon(e.SourceURL, e.SourceExcerpt, e.Fingerprint, e.API, e.Version, + e.Description, e.DetectedAt, e.ChangeType, e.Breaking, e.Confidence); err != nil { + return err + } + + if err := e.Affected.validate(); err != nil { + return err + } + + // Rule 5 (continued): a value is a value of a property. + if e.Affected.Value != "" && e.Affected.Property == "" { + return fmt.Errorf("affected.value needs affected.property: it is a value of that property") + } + + return nil +} + +// checkCommon is the contract's rules for every field outside affected (v1) or +// subject (v2): the two versions differ only in what changed, not in the rest. +func checkCommon(sourceURL, excerpt, fingerprint, api, version, description string, + detectedAt time.Time, changeType ChangeType, breaking bool, confidence float64) error { + // Rule 1: provenance is mandatory — the anti-hallucination mechanism. + if sourceURL == "" { + return fmt.Errorf("source_url is required") + } + if excerpt == "" { + return fmt.Errorf("source_excerpt is required") + } + + // Rule 2: other required fields must be non-empty. + if fingerprint == "" { + return fmt.Errorf("fingerprint is required") + } + if !fingerprintPattern.MatchString(fingerprint) { + return fmt.Errorf("fingerprint must look like sha256:<64 lowercase hex>, got %q", fingerprint) + } + if api == "" { + return fmt.Errorf("api is required") + } + if version == "" { + return fmt.Errorf("version is required") + } + if description == "" { + return fmt.Errorf("description is required") + } + if detectedAt.IsZero() { + return fmt.Errorf("detected_at is required") + } + + // Rule 3: change_type must be one of the known enum values. + if changeType != ChangeTypeBreaking && + changeType != ChangeTypeDeprecation && + changeType != ChangeTypeNewFeature && + changeType != ChangeTypeFix { + return fmt.Errorf("change_type must be a valid enum value, got %q", changeType) + } + + // Rule 4: breaking must agree with change_type. + if breaking != (changeType == ChangeTypeBreaking) { + return fmt.Errorf("breaking (%v) must equal change_type == breaking", breaking) + } + + // Rule 6: confidence must be in [0, 1]. + if confidence < 0 || confidence > 1 { + return fmt.Errorf("confidence must be between 0 and 1, got %v", confidence) + } + + // Rule 7: source_excerpt is capped at 2000 characters. Count runes, not + // bytes: spec text is full of non-ASCII (Stripe writes "invoice\u2019s"), and + // len() would reject excerpts well under the documented limit. + if n := utf8.RuneCountInString(excerpt); n > 2000 { + return fmt.Errorf("source_excerpt must be at most 2000 characters, got %d", n) + } + return nil +} + +// validate is the contract's rules for an API location: v1's affected, and v2's +// api_operation subject. Kind decides the side and the required fields. +func (a Affected) validate() error { + // Rule 3 (continued): affected.kind and affected.side must be valid too. + if a.Kind != AffectedKindOperation && + a.Kind != AffectedKindRequestParameter && + a.Kind != AffectedKindSchema && + a.Kind != AffectedKindSchemaProperty { + return fmt.Errorf("affected.kind must be a valid enum value, got %q", a.Kind) + } + if a.Side != SideRequest && a.Side != SideResponse { + return fmt.Errorf("affected.side must be a valid enum value, got %q", a.Side) + } + + // Rule 5: affected's required sub-fields, and its side, depend on its kind. + // Kind decides side: requests live under paths, responses under schemas. + switch a.Kind { + case AffectedKindOperation: + if a.Operation == "" { + return fmt.Errorf("affected.operation is required when kind is operation") + } + if a.Side != SideRequest { + return fmt.Errorf("affected.side must be %q when kind is operation, got %q", SideRequest, a.Side) + } + case AffectedKindRequestParameter: + if a.Operation == "" || a.Property == "" { + return fmt.Errorf("affected.operation and affected.property are required when kind is request_parameter") + } + if a.Side != SideRequest { + return fmt.Errorf("affected.side must be %q when kind is request_parameter, got %q", SideRequest, a.Side) + } + case AffectedKindSchema: + if a.Schema == "" { + return fmt.Errorf("affected.schema is required when kind is schema") + } + if a.Side != SideResponse { + return fmt.Errorf("affected.side must be %q when kind is schema, got %q", SideResponse, a.Side) + } + case AffectedKindSchemaProperty: + if a.Schema == "" || a.Property == "" { + return fmt.Errorf("affected.schema and affected.property are required when kind is schema_property") + } + if a.Side != SideResponse { + return fmt.Errorf("affected.side must be %q when kind is schema_property, got %q", SideResponse, a.Side) + } + } + return nil +} diff --git a/event/event_test.go b/core/event/event_test.go similarity index 97% rename from event/event_test.go rename to core/event/event_test.go index e492dc5..6f0b3f6 100644 --- a/event/event_test.go +++ b/core/event/event_test.go @@ -176,7 +176,7 @@ func TestAValueNeedsTheProperty(t *testing.T) { // contract, one of the two tests fails. Reading a shared fixture is not an // import: the two still share only the contract. func TestSharedFixtureMatchesTheContract(t *testing.T) { - raw, err := os.ReadFile("../contract/fixtures/change-events.json") + raw, err := os.ReadFile("../../contract/fixtures/change-events.json") if err != nil { t.Fatalf("reading the shared fixture: %v", err) } @@ -199,7 +199,7 @@ func TestSharedFixtureMatchesTheContract(t *testing.T) { // The model retirements fixture is the hosted service's real output, the first to // carry affected.value. Ingest and the client both check it. func TestRetirementFixtureMatchesTheContract(t *testing.T) { - raw, err := os.ReadFile("../contract/fixtures/change-events-model-retirements-2026-10-13.json") + raw, err := os.ReadFile("../../contract/fixtures/change-events-model-retirements-2026-10-13.json") if err != nil { t.Fatalf("reading the fixture: %v", err) } @@ -222,7 +222,7 @@ func TestRetirementFixtureMatchesTheContract(t *testing.T) { // The negative half of the contract test: every event in the shared invalid // fixture breaks one rule, and both loops must reject all of them. func TestSharedInvalidFixtureIsRejected(t *testing.T) { - raw, err := os.ReadFile("../contract/fixtures/change-events-invalid.json") + raw, err := os.ReadFile("../../contract/fixtures/change-events-invalid.json") if err != nil { t.Fatalf("reading the shared invalid fixture: %v", err) } diff --git a/event/v2.go b/core/event/v2.go similarity index 100% rename from event/v2.go rename to core/event/v2.go diff --git a/event/v2_test.go b/core/event/v2_test.go similarity index 99% rename from event/v2_test.go rename to core/event/v2_test.go index 5b1c58c..0d2dab3 100644 --- a/event/v2_test.go +++ b/core/event/v2_test.go @@ -12,7 +12,7 @@ import ( // go test ./event -update var update = flag.Bool("update", false, "rewrite fingerprints in change-events-v2-types.json") -const v2Fixtures = "../contract/fixtures/" +const v2Fixtures = "../../contract/fixtures/" func rawEvents(t *testing.T, name string) []json.RawMessage { t.Helper() diff --git a/fetch/cache.go b/core/fetch/cache.go similarity index 100% rename from fetch/cache.go rename to core/fetch/cache.go diff --git a/fetch/cache_test.go b/core/fetch/cache_test.go similarity index 100% rename from fetch/cache_test.go rename to core/fetch/cache_test.go diff --git a/core/fetch/fetch.go b/core/fetch/fetch.go new file mode 100644 index 0000000..8cb228c --- /dev/null +++ b/core/fetch/fetch.go @@ -0,0 +1,135 @@ +// Package fetch does plain HTTP GETs with retries and a timeout. It knows +// nothing about specs, Stripe, or any other caller — just how to reliably +// download bytes from a URL. +package fetch + +import ( + "context" + "errors" + "fmt" + "io" + "net/http" + "time" +) + +const ( + maxAttempts = 3 + attemptTimeout = 30 * time.Second +) + +// baseBackoff is a variable only so tests can shorten it. +var baseBackoff = 1 * time.Second + +// StatusError is returned when a request completes but with a non-200 status, +// so callers can check the exact code (e.g. a 404 meaning "try elsewhere") +// instead of matching on an error string. +type StatusError struct { + URL string + StatusCode int +} + +func (e *StatusError) Error() string { + return fmt.Sprintf("unexpected status %d from %s", e.StatusCode, e.URL) +} + +// requestError marks a failure to even build the HTTP request (e.g. a +// malformed URL). It's never transient, so Get fails fast on it instead of +// retrying like it does for network errors and 5xx responses. +type requestError struct{ err error } + +func (e *requestError) Error() string { return e.err.Error() } +func (e *requestError) Unwrap() error { return e.err } + +// Get downloads url, retrying on network errors and 5xx responses up to +// maxAttempts times with exponential backoff (1s, 2s, 4s...). A 4xx response +// means the request itself is wrong, so it fails immediately instead of +// retrying. headers are set on every attempt; nil is fine for none. +func Get(ctx context.Context, url string, headers map[string]string) ([]byte, error) { + r, err := get(ctx, url, headers) + if err == nil && r.status == http.StatusNotModified { + // Get sends no validators of its own, so a 304 is the server's error, + // never an empty page. + return nil, &StatusError{URL: url, StatusCode: r.status} + } + return r.body, err +} + +// response is one successful attempt: 200 with its body, or 304 Not Modified +// to a conditional request (no body). +type response struct { + status int + body []byte + header http.Header +} + +// get is Get's retry loop, returning the whole response. +func get(ctx context.Context, url string, headers map[string]string) (response, error) { + var lastErr error + + for attempt := 1; attempt <= maxAttempts; attempt++ { + r, err := attemptGet(ctx, url, headers) + status := r.status + if err == nil { + return r, nil + } + lastErr = err + + var reqErr *requestError + if errors.As(err, &reqErr) { + return response{}, err // a malformed request won't build any differently on retry + } + + if status >= 400 && status < 500 { + return response{}, err // retrying a bad request never helps + } + + if attempt < maxAttempts { + backoff := baseBackoff * time.Duration(1<<(attempt-1)) + select { + case <-time.After(backoff): + case <-ctx.Done(): + return response{}, ctx.Err() + } + } + } + + return response{}, fmt.Errorf("fetching %s failed after %d attempts: %w", url, maxAttempts, lastErr) +} + +// attemptGet makes one attempt, bounded by its own timeout so a single hung +// request can't block forever. status is 0 when the failure happened before +// a response arrived (a bad request, a network error). A 304 is a success: it +// only comes back to a request that asked for it (If-None-Match, +// If-Modified-Since). +func attemptGet(ctx context.Context, url string, headers map[string]string) (response, error) { + ctx, cancel := context.WithTimeout(ctx, attemptTimeout) + defer cancel() + + req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) + if err != nil { + return response{}, &requestError{err: fmt.Errorf("could not build the request: %w", err)} + } + for key, value := range headers { + req.Header.Set(key, value) + } + + resp, err := http.DefaultClient.Do(req) + if err != nil { + return response{}, fmt.Errorf("could not retrieve the content from given url: %w", err) + } + defer resp.Body.Close() + + r := response{status: resp.StatusCode, header: resp.Header} + if resp.StatusCode == http.StatusNotModified { + return r, nil + } + if resp.StatusCode != http.StatusOK { + return r, &StatusError{URL: url, StatusCode: resp.StatusCode} + } + + r.body, err = io.ReadAll(resp.Body) + if err != nil { + return r, fmt.Errorf("could not read the response body: %w", err) + } + return r, nil +} diff --git a/fetch/fetch_test.go b/core/fetch/fetch_test.go similarity index 100% rename from fetch/fetch_test.go rename to core/fetch/fetch_test.go diff --git a/core/github/github.go b/core/github/github.go new file mode 100644 index 0000000..b056470 --- /dev/null +++ b/core/github/github.go @@ -0,0 +1,126 @@ +// Package github is the one place a plugin asks GitHub's REST API where a +// source's newest version is: the newest release, the newest commit that +// changed a path, and one commit's full SHA and date. Every plugin that +// follows a GitHub repo calls these instead of decoding GitHub's responses +// itself. +// +// Each function takes how to fetch (Get, or a plugin's env.Get) and the full +// API URL, so a test serves it from saved pages or a local server. +package github + +import ( + "context" + "encoding/json" + "fmt" + "os" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/fetch" +) + +// API is GitHub's REST API. +const API = "https://api.github.com" + +// Raw serves a repo's files at a ref, with no auth. +const Raw = "https://raw.githubusercontent.com" + +// Headers adds GITHUB_TOKEN as a bearer token when set, which raises the +// GitHub API's rate limit. Never required. +func Headers() map[string]string { + token := os.Getenv("GITHUB_TOKEN") + if token == "" { + return nil + } + return map[string]string{"Authorization": "Bearer " + token} +} + +// Getter fetches one URL: Get, or plugin.Env.Get. +type Getter func(ctx context.Context, url string) ([]byte, error) + +// Get is fetch.Get with Headers: GITHUB_TOKEN, when set, raises the rate limit +// (never required). +func Get(ctx context.Context, url string) ([]byte, error) { + return fetch.Get(ctx, url, Headers()) +} + +// LatestRelease reads a repo's releases/latest (url) and returns its tag. +// GitHub's "latest" skips drafts and prereleases. +func LatestRelease(ctx context.Context, get Getter, url string) (string, error) { + body, err := get(ctx, url) + if err != nil { + return "", err + } + var release struct { + TagName string `json:"tag_name"` + } + if err := json.Unmarshal(body, &release); err != nil { + return "", fmt.Errorf("parsing github release response: %w", err) + } + if release.TagName == "" { + return "", fmt.Errorf("github release response had no tag_name") + } + return release.TagName, nil +} + +// LatestCommit reads a commit list (url: commits?path=&per_page=1, newest +// first) and returns the newest commit's SHA, or an error when it lists none. +func LatestCommit(ctx context.Context, get Getter, url string) (string, error) { + body, err := get(ctx, url) + if err != nil { + return "", err + } + var commits []struct { + SHA string `json:"sha"` + } + if err := json.Unmarshal(body, &commits); err != nil { + return "", fmt.Errorf("parsing github commits response: %w", err) + } + if len(commits) == 0 || commits[0].SHA == "" { + return "", fmt.Errorf("github lists no commit") + } + return commits[0].SHA, nil +} + +// Commit reads one commit (url: commits/) and returns its full SHA and +// its committer date. A response with no date is an error; one with no SHA +// returns "" (a caller that pins by SHA checks it). +func Commit(ctx context.Context, get Getter, url string) (sha string, date time.Time, err error) { + body, err := get(ctx, url) + if err != nil { + return "", time.Time{}, err + } + var c struct { + SHA string `json:"sha"` + Commit struct { + Committer struct { + Date time.Time `json:"date"` + } `json:"committer"` + } `json:"commit"` + } + if err := json.Unmarshal(body, &c); err != nil { + return "", time.Time{}, fmt.Errorf("parsing github commit: %w", err) + } + if c.Commit.Committer.Date.IsZero() { + return "", time.Time{}, fmt.Errorf("github commit has no date") + } + return c.SHA, c.Commit.Committer.Date, nil +} + +// Head reads one commit (url: commits/) and returns its full +// SHA: the newest commit on a branch, when the source has no releases. +func Head(ctx context.Context, get Getter, url string) (string, error) { + body, err := get(ctx, url) + if err != nil { + return "", err + } + var c struct { + SHA string `json:"sha"` + } + if err := json.Unmarshal(body, &c); err != nil { + return "", fmt.Errorf("parsing github commit: %w", err) + } + if c.SHA == "" { + return "", fmt.Errorf("the commit lookup named no sha") + } + return c.SHA, nil +} diff --git a/core/github/github_test.go b/core/github/github_test.go new file mode 100644 index 0000000..5c4d44a --- /dev/null +++ b/core/github/github_test.go @@ -0,0 +1,58 @@ +package github + +import ( + "context" + "fmt" + "testing" + "time" +) + +// pages serves canned API responses by URL. +func pages(m map[string]string) Getter { + return func(_ context.Context, url string) ([]byte, error) { + b, ok := m[url] + if !ok { + return nil, fmt.Errorf("no page %s", url) + } + return []byte(b), nil + } +} + +func TestLatestRelease(t *testing.T) { + get := pages(map[string]string{"r": `{"tag_name":"v2468"}`, "empty": `{}`, "bad": ``}) + if tag, err := LatestRelease(context.Background(), get, "r"); err != nil || tag != "v2468" { + t.Errorf("got %q, %v", tag, err) + } + for _, url := range []string{"empty", "bad", "missing"} { + if _, err := LatestRelease(context.Background(), get, url); err == nil { + t.Errorf("%s: no error", url) + } + } +} + +func TestLatestCommit(t *testing.T) { + get := pages(map[string]string{"c": `[{"sha":"abc"},{"sha":"def"}]`, "none": `[]`}) + if sha, err := LatestCommit(context.Background(), get, "c"); err != nil || sha != "abc" { + t.Errorf("got %q, %v", sha, err) + } + if _, err := LatestCommit(context.Background(), get, "none"); err == nil { + t.Error("an empty list gave no error") + } +} + +func TestCommitAndHead(t *testing.T) { + get := pages(map[string]string{ + "c": `{"sha":"abc","commit":{"committer":{"date":"2026-11-19T10:00:00Z"}}}`, + "nodate": `{"sha":"abc"}`, + }) + sha, date, err := Commit(context.Background(), get, "c") + if err != nil || sha != "abc" || !date.Equal(time.Date(2026, 11, 19, 10, 0, 0, 0, time.UTC)) { + t.Errorf("got %q %v %v", sha, date, err) + } + if _, _, err := Commit(context.Background(), get, "nodate"); err == nil { + t.Error("a commit with no date gave no error") + } + if sha, err := Head(context.Background(), get, "nodate"); err != nil || sha != "abc" { + t.Errorf("Head: %q %v", sha, err) + } +} diff --git a/hint/hint.go b/core/hint/hint.go similarity index 99% rename from hint/hint.go rename to core/hint/hint.go index 60fe8aa..7039941 100644 --- a/hint/hint.go +++ b/core/hint/hint.go @@ -22,7 +22,7 @@ import ( "strings" "unicode/utf8" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // hintLimit caps a hint at the contract's excerpt cap, counted in characters. diff --git a/hint/hint_test.go b/core/hint/hint_test.go similarity index 99% rename from hint/hint_test.go rename to core/hint/hint_test.go index 52020fd..00ba8f0 100644 --- a/hint/hint_test.go +++ b/core/hint/hint_test.go @@ -9,7 +9,7 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // fakeDocs serves the saved changelog pages under testdata the way diff --git a/hint/stripe.go b/core/hint/stripe.go similarity index 99% rename from hint/stripe.go rename to core/hint/stripe.go index a94d676..88eaa10 100644 --- a/hint/stripe.go +++ b/core/hint/stripe.go @@ -9,7 +9,7 @@ import ( "strings" "unicode" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" ) // Stripe reads docs.stripe.com's changelog, which every page serves as diff --git a/hint/testdata/README.md b/core/hint/testdata/README.md similarity index 100% rename from hint/testdata/README.md rename to core/hint/testdata/README.md diff --git a/hint/testdata/endive.md b/core/hint/testdata/endive.md similarity index 100% rename from hint/testdata/endive.md rename to core/hint/testdata/endive.md diff --git a/hint/testdata/polymorphic-billing-cycle-anchor.md b/core/hint/testdata/polymorphic-billing-cycle-anchor.md similarity index 100% rename from hint/testdata/polymorphic-billing-cycle-anchor.md rename to core/hint/testdata/polymorphic-billing-cycle-anchor.md diff --git a/hint/testdata/remove-payment-method-types-checkout-sessions.md b/core/hint/testdata/remove-payment-method-types-checkout-sessions.md similarity index 100% rename from hint/testdata/remove-payment-method-types-checkout-sessions.md rename to core/hint/testdata/remove-payment-method-types-checkout-sessions.md diff --git a/hint/testdata/removed-payto-fields.md b/core/hint/testdata/removed-payto-fields.md similarity index 100% rename from hint/testdata/removed-payto-fields.md rename to core/hint/testdata/removed-payto-fields.md diff --git a/hint/testdata/removes-the-payment-method-types-parameter-from-payment-intents-and-setup-intents.md b/core/hint/testdata/removes-the-payment-method-types-parameter-from-payment-intents-and-setup-intents.md similarity index 100% rename from hint/testdata/removes-the-payment-method-types-parameter-from-payment-intents-and-setup-intents.md rename to core/hint/testdata/removes-the-payment-method-types-parameter-from-payment-intents-and-setup-intents.md diff --git a/hint/testdata/trial-offer-ga.md b/core/hint/testdata/trial-offer-ga.md similarity index 100% rename from hint/testdata/trial-offer-ga.md rename to core/hint/testdata/trial-offer-ga.md diff --git a/core/kit/kit.go b/core/kit/kit.go new file mode 100644 index 0000000..4f16c7b --- /dev/null +++ b/core/kit/kit.go @@ -0,0 +1,48 @@ +// Package kit is what source plugins share beyond the core: the Wayback +// Machine client a plugin cites a live page through (Wayback, Cite) and the +// "same page as last run" check (Unchanged). Fetching with ETag and +// Last-Modified caching is fetch's Cache, handed to every plugin as +// plugin.Env.Get; the test kit is kittest. +// +// kit is not a plugin: plugins import it, it imports no plugin. +package kit + +import ( + "context" + "fmt" + "reflect" + + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +// Unchanged reports whether body is what api's last stored baseline hashed +// to, and returns that baseline (nil on a first run). A plugin reading a live +// page returns early on true: an unchanged page costs one GET and no snapshot. +func Unchanged(env plugin.Env, api string, body []byte) (last *plugin.Spec, same bool, err error) { + last, err = env.Baselines.LastSpec(api) + if err != nil { + return nil, false, fmt.Errorf("loading the last baseline of %s: %w", api, err) + } + return last, last != nil && last.SHA256 == plugin.SHA256(body), nil +} + +// Cite snapshots a live page and checks the snapshot holds what the plugin +// read from the live page: read turns bytes into whatever the plugin makes +// events from, and the snapshot's must deep-equal want. The events are then +// made from the snapshot and cite snapURL, so every excerpt is on the page it +// cites. No snapshot, or one that says something else (the page changed in +// between), is an error: no provenance, no event. +func Cite[T any](ctx context.Context, a Archiver, pageURL string, read func([]byte) (T, error), want T) (snapURL string, snap []byte, got T, err error) { + snapURL, snap, err = a.Snapshot(ctx, pageURL) + if err != nil { + return "", nil, got, fmt.Errorf("no events without a snapshot to cite: %w", err) + } + got, err = read(snap) + if err != nil { + return "", nil, got, fmt.Errorf("reading the snapshot %s: %w", snapURL, err) + } + if !reflect.DeepEqual(got, want) { + return "", nil, got, fmt.Errorf("the snapshot %s doesn't hold what %s says now; run again", snapURL, pageURL) + } + return snapURL, snap, got, nil +} diff --git a/kit/kit_test.go b/core/kit/kit_test.go similarity index 94% rename from kit/kit_test.go rename to core/kit/kit_test.go index 17f8fa1..a27881e 100644 --- a/kit/kit_test.go +++ b/core/kit/kit_test.go @@ -7,8 +7,8 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) type archive struct { diff --git a/kit/kittest/checksink.go b/core/kit/kittest/checksink.go similarity index 97% rename from kit/kittest/checksink.go rename to core/kit/kittest/checksink.go index b991b6a..548881d 100644 --- a/kit/kittest/checksink.go +++ b/core/kit/kittest/checksink.go @@ -5,8 +5,8 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // CheckSink checks that the Sinks open returns store as patch-it's hosted diff --git a/core/kit/kittest/kittest.go b/core/kit/kittest/kittest.go new file mode 100644 index 0000000..d134f14 --- /dev/null +++ b/core/kit/kittest/kittest.go @@ -0,0 +1,214 @@ +// Package kittest is the plugin test kit: a saved copy of a source in, the +// events a plugin stores out, compared with a golden file. Nothing reaches the +// network or a database: a URL the test didn't save fails the test, events and +// baselines are kept in memory (Mem), and the clock is fixed, so the same +// pages always give byte-identical events. +// +// got := kittest.Ingest(t, plugin, kittest.Pages{url: "testdata/page.md"}) +// kittest.Golden(t, "testdata/golden/numpy.json", got) +// +// `go test ./plugins/ -update` rewrites a plugin's golden files; +// review the diff like code. +package kittest + +import ( + "bytes" + "context" + "encoding/json" + "flag" + "fmt" + "os" + "path/filepath" + "reflect" + "strconv" + "testing" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" +) + +var update = flag.Bool("update", false, "rewrite the golden files from what the plugins store now") + +// Clock is the time every kit run detects its changes at. +var Clock = time.Date(2026, 11, 14, 12, 0, 0, 0, time.UTC) + +// Pages are the saved copies a run may fetch: URL to file, relative to the +// test's package. +type Pages map[string]string + +// Get serves Pages, and fails the test on any other URL. +func (p Pages) Get(t testing.TB) func(context.Context, string) ([]byte, error) { + return func(_ context.Context, url string) ([]byte, error) { + file, ok := p[url] + if !ok { + t.Errorf("fetched %s, which the test didn't save", url) + return nil, fmt.Errorf("no saved copy of %s", url) + } + return Read(t, file), nil + } +} + +// Read is a saved file, or the test fails. +func Read(t testing.TB, file string) []byte { + t.Helper() + b, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + return b +} + +// Env is an empty Mem for the baselines and the events, Pages for the network +// and Clock for the time. Nothing outside the test is touched: no database, no +// network. +func Env(t testing.TB, pages Pages) plugin.Env { + t.Helper() + return plugin.Env{Baselines: NewMem(), Get: pages.Get(t), Now: func() time.Time { return Clock }} +} + +// Ingest runs p twice and returns what the first run stored. Any rejected +// event or error fails the test, and so does a second run over the same pages +// that stores anything new: the fingerprints must dedupe. +func Ingest(t testing.TB, p plugin.Plugin, pages Pages) []event.EventV2 { + t.Helper() + env := Env(t, pages) + return IngestWith(t, env, p) +} + +// IngestWith is Ingest over an Env the test built (its own archive, a baseline +// already saved). env.Baselines is where the events are stored too, so it must +// be a Sink, as Env's Mem is. +func IngestWith(t testing.TB, env plugin.Env, p plugin.Plugin) []event.EventV2 { + t.Helper() + sink, ok := env.Baselines.(Sink) + if !ok { + t.Fatalf("env.Baselines is a %T, not a kittest.Sink to store the events in", env.Baselines) + } + if rejected, err := Run(context.Background(), env, sink, p); err != nil || rejected { + t.Fatalf("%s: rejected=%v err=%v", p.Name(), rejected, err) + } + first := Stored(t, sink) + if rejected, err := Run(context.Background(), env, sink, p); err != nil || rejected { + t.Fatalf("%s, second run: rejected=%v err=%v", p.Name(), rejected, err) + } + if again := Stored(t, sink); len(again) != len(first) { + t.Errorf("%s: a second run over the same pages stored %d more events", p.Name(), len(again)-len(first)) + } + return first +} + +// Stored is every event in s, in feed order, or the test fails. +func Stored(t testing.TB, s Sink) []event.EventV2 { + t.Helper() + all, err := s.All() + if err != nil { + t.Fatal(err) + } + return all +} + +// Golden compares events with the JSON file at path, or rewrites it with +// -update. Every event must also be valid v2, or the golden would pin a bug. +func Golden(t testing.TB, path string, events []event.EventV2) { + t.Helper() + golden(t, path, events, *update) +} + +// CompareGolden is Golden that never rewrites the file, even with -update: +// for a test that checks someone else's golden file. +func CompareGolden(t testing.TB, path string, events []event.EventV2) { + t.Helper() + golden(t, path, events, false) +} + +func golden(t testing.TB, path string, events []event.EventV2, rewrite bool) { + t.Helper() + for _, e := range events { + if err := e.Validate(); err != nil { + t.Errorf("event %d (%s) is invalid: %v", e.ID, e.Description, err) + } + } + if events == nil { + events = []event.EventV2{} + } + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetIndent("", " ") + enc.SetEscapeHTML(false) + if err := enc.Encode(events); err != nil { + t.Fatal(err) + } + if rewrite { + if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(path, buf.Bytes(), 0o644); err != nil { + t.Fatal(err) + } + return + } + want, err := os.ReadFile(path) + if err != nil { + t.Fatalf("%v (run the test with -update to create it)", err) + } + if !bytes.Equal(want, buf.Bytes()) { + t.Errorf("%s: the stored events differ from the golden file (%d events now); if the change is intended, rerun with -update and review the diff\n%s", + path, len(events), firstDiff(want, buf.Bytes())) + } +} + +// firstDiff is the first line that differs, for the failure message. +func firstDiff(want, got []byte) string { + w, g := bytes.Split(want, []byte("\n")), bytes.Split(got, []byte("\n")) + for i := 0; i < len(w) || i < len(g); i++ { + var wl, gl []byte + if i < len(w) { + wl = w[i] + } + if i < len(g) { + gl = g[i] + } + if !bytes.Equal(wl, gl) { + return "line " + strconv.Itoa(i+1) + ":\n want " + string(wl) + "\n got " + string(gl) + } + } + return "" +} + +// Archive is the Wayback Machine without the network: it serves a saved copy +// as the snapshot of a page, under a fixed timestamp, and counts the +// snapshots it was asked for. +type Archive struct { + T testing.TB + Pages Pages // the page's URL to the file the snapshot holds + Timestamp string // 14 digits; default 20261114120000 + Calls int +} + +func (a *Archive) Snapshot(_ context.Context, page string) (string, []byte, error) { + a.Calls++ + file, ok := a.Pages[page] + if !ok { + return "", nil, fmt.Errorf("no snapshot of %s in the test archive", page) + } + ts := a.Timestamp + if ts == "" { + ts = "20261114120000" + } + return "https://web.archive.org/web/" + ts + "/" + page, Read(a.T, file), nil +} + +// Registered fails the test unless p's package registered a plugin of p's +// type under p's name: each plugin package checks its own registration. +func Registered(t testing.TB, p plugin.Plugin) { + t.Helper() + got, ok := plugin.Lookup(p.Name()) + if !ok { + t.Errorf("no plugin registered as %q", p.Name()) + return + } + if reflect.TypeOf(got) != reflect.TypeOf(p) { + t.Errorf("%q is a %T, want a %T", p.Name(), got, p) + } +} diff --git a/kit/kittest/mem.go b/core/kit/kittest/mem.go similarity index 97% rename from kit/kittest/mem.go rename to core/kit/kittest/mem.go index dba9b6b..8a04593 100644 --- a/kit/kittest/mem.go +++ b/core/kit/kittest/mem.go @@ -9,8 +9,8 @@ import ( "sync" "time" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // Sink is where a kit run stores what a plugin found, and where the plugin diff --git a/kit/kittest/mem_test.go b/core/kit/kittest/mem_test.go similarity index 91% rename from kit/kittest/mem_test.go rename to core/kit/kittest/mem_test.go index 148767b..c673613 100644 --- a/kit/kittest/mem_test.go +++ b/core/kit/kittest/mem_test.go @@ -3,8 +3,8 @@ package kittest import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func TestMemStoresAsIngestDoes(t *testing.T) { diff --git a/kit/wayback.go b/core/kit/wayback.go similarity index 98% rename from kit/wayback.go rename to core/kit/wayback.go index 74cca51..6745126 100644 --- a/kit/wayback.go +++ b/core/kit/wayback.go @@ -11,7 +11,7 @@ import ( "strings" "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" ) // Archiver takes a snapshot of a page that never changes afterwards, and hands diff --git a/kit/wayback_test.go b/core/kit/wayback_test.go similarity index 100% rename from kit/wayback_test.go rename to core/kit/wayback_test.go diff --git a/core/migrate/migrate.go b/core/migrate/migrate.go new file mode 100644 index 0000000..3ffa523 --- /dev/null +++ b/core/migrate/migrate.go @@ -0,0 +1,120 @@ +// Package migrate converts stored v1 change events to the proposed v2 contract +// (the change event contract): `affected` becomes a typed +// `subject`. It runs once, at the cut-over, over every event in the store. +// +// A Stripe event keeps its fingerprint: v2's api_operation formula is v1's. +// A model retirement or an SDK release gets a new one, and `supersedes` names +// the old one, so the patch-it client, which finds its open issues and pull +// requests by the fingerprint in their marker, knows they're the same change +// and opens nothing twice. +package migrate + +import ( + "fmt" + "regexp" + "strings" + + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" + "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" +) + +// providers are the model retirement slugs and who retires the models. +var providers = map[string]string{ + retire.OpenAI.API: "openai", + retire.Anthropic.API: "anthropic", +} + +// guides are the SDKs whose v1 events came from a migration guide. +var guides = map[string]sdkguide.Guide{sdkguide.AnthropicV1.API: sdkguide.AnthropicV1} + +// ToV2 converts one v1 event. It refuses an event it can't place rather than +// guess: an unknown slug with a value, or an SDK event that isn't a removed +// request parameter. +func ToV2(e event.ChangeEvent) (event.EventV2, error) { + v2 := event.EventV2{ + ID: e.ID, API: e.API, Version: e.Version, PreviousVersion: e.PreviousVersion, + ChangeType: e.ChangeType, Breaking: e.Breaking, Description: e.Description, + MigrationHint: e.MigrationHint, SourceURL: e.SourceURL, SourcePointer: e.SourcePointer, + SourceExcerpt: e.SourceExcerpt, Confidence: e.Confidence, DetectedAt: e.DetectedAt, + } + a := e.Affected + if provider, ok := providers[e.API]; ok { + if a.Value == "" { + return event.EventV2{}, fmt.Errorf("event %d: a %s event without the model in affected.value", e.ID, e.API) + } + v2.Subject = event.Subject{ + Type: event.SubjectModel, Provider: provider, Name: a.Value, + Replacement: replacement(e.MigrationHint), + } + return rekeyed(v2, e.Fingerprint), nil + } + if g, ok := guides[e.API]; ok { + if a.Kind != event.AffectedKindRequestParameter || a.Property == "" { + return event.EventV2{}, fmt.Errorf("event %d: an %s SDK event that isn't a removed parameter", e.ID, e.API) + } + v2.Subject = event.Subject{ + Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.API, + Change: event.PackageRemovedParameter, Parameter: a.Property, Symbols: g.Symbols, + } + return rekeyed(v2, e.Fingerprint), nil + } + if a.Value != "" { + return event.EventV2{}, fmt.Errorf("event %d: affected.value on %s, which isn't a model retirement", e.ID, e.API) + } + v2.Subject = event.Subject{ + Type: event.SubjectAPIOperation, Kind: a.Kind, Side: a.Side, + Operation: a.Operation, Schema: a.Schema, Property: a.Property, + } + v2.Fingerprint = e.Fingerprint // the same formula: unchanged by construction + return v2, nil +} + +// rekeyed gives the event its v2 fingerprint and says which v1 one it replaces. +func rekeyed(v2 event.EventV2, old string) event.EventV2 { + v2.Fingerprint = event.FingerprintV2(v2.API, v2.Version, v2.ChangeType, v2.Subject, "") + if v2.Fingerprint != old { + v2.Supersedes = old + } + return v2 +} + +// useInstead is the hint retire.Events writes: "Use instead: …". +var useInstead = regexp.MustCompile("^Use (.+?) instead: ") + +// replacement is the one model the provider names, when its replacement cell +// is exactly one model name: not none ("names no replacement model"), not +// several, not a model with a setting (`gpt-5.6-sol` (`reasoning.mode: pro`)). +// The patch-it client opens an issue for the rest, as it does today. +func replacement(hint string) string { + m := useInstead.FindStringSubmatch(hint) + if m == nil { + return "" + } + name := retire.First(m[1]) + if name == "" || strings.TrimSpace(m[1]) != "`"+name+"`" { + return "" + } + return name +} + +// Fresh converts events a source has just produced in the v1 shape. Unlike a +// stored row, a fresh event replaces nothing, so it carries no `supersedes`. An +// event that can't be placed is returned as an error, like a failed validation. +func Fresh(events []event.ChangeEvent) ([]event.EventV2, []error) { + var out []event.EventV2 + var errs []error + for _, e := range events { + v2, err := ToV2(e) + if err == nil { + v2.Supersedes = "" + err = v2.Validate() + } + if err != nil { + errs = append(errs, err) + continue + } + out = append(out, v2) + } + return out, errs +} diff --git a/migrate/migrate_test.go b/core/migrate/migrate_test.go similarity index 97% rename from migrate/migrate_test.go rename to core/migrate/migrate_test.go index 84646c5..c6fccb3 100644 --- a/migrate/migrate_test.go +++ b/core/migrate/migrate_test.go @@ -8,13 +8,13 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // -update rewrites the golden v2 fixture from the v1 ones: go test ./migrate -update var update = flag.Bool("update", false, "rewrite contract/fixtures/change-events-v2.json") -const fixtures = "../contract/fixtures/" +const fixtures = "../../contract/fixtures/" // The v1 fixtures the golden v2 file is converted from: the shared contract // fixture, the hosted service's model retirements and the anthropic SDK release. diff --git a/normalize/golden_test.go b/core/normalize/golden_test.go similarity index 98% rename from normalize/golden_test.go rename to core/normalize/golden_test.go index f3d25ab..6fb92a1 100644 --- a/normalize/golden_test.go +++ b/core/normalize/golden_test.go @@ -9,7 +9,7 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/diff" + "github.com/patch-it-dev/patch-it-plugins/core/diff" ) // Golden-file tests for the whole pipeline: each directory under diff --git a/normalize/normalize.go b/core/normalize/normalize.go similarity index 98% rename from normalize/normalize.go rename to core/normalize/normalize.go index 9fb8097..9279fc9 100644 --- a/normalize/normalize.go +++ b/core/normalize/normalize.go @@ -14,8 +14,8 @@ import ( "time" "unicode/utf8" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // excerptLimit matches the contract's cap, counted in characters. diff --git a/normalize/normalize_test.go b/core/normalize/normalize_test.go similarity index 97% rename from normalize/normalize_test.go rename to core/normalize/normalize_test.go index 28aae0d..89d8025 100644 --- a/normalize/normalize_test.go +++ b/core/normalize/normalize_test.go @@ -6,8 +6,8 @@ import ( "time" "unicode/utf8" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) const ( diff --git a/normalize/testdata/README.md b/core/normalize/testdata/README.md similarity index 100% rename from normalize/testdata/README.md rename to core/normalize/testdata/README.md diff --git a/normalize/testdata/golden/breaking-property-removed/events.json b/core/normalize/testdata/golden/breaking-property-removed/events.json similarity index 100% rename from normalize/testdata/golden/breaking-property-removed/events.json rename to core/normalize/testdata/golden/breaking-property-removed/events.json diff --git a/normalize/testdata/golden/breaking-property-removed/new.json b/core/normalize/testdata/golden/breaking-property-removed/new.json similarity index 100% rename from normalize/testdata/golden/breaking-property-removed/new.json rename to core/normalize/testdata/golden/breaking-property-removed/new.json diff --git a/normalize/testdata/golden/breaking-property-removed/old.json b/core/normalize/testdata/golden/breaking-property-removed/old.json similarity index 100% rename from normalize/testdata/golden/breaking-property-removed/old.json rename to core/normalize/testdata/golden/breaking-property-removed/old.json diff --git a/normalize/testdata/golden/deprecation/events.json b/core/normalize/testdata/golden/deprecation/events.json similarity index 100% rename from normalize/testdata/golden/deprecation/events.json rename to core/normalize/testdata/golden/deprecation/events.json diff --git a/normalize/testdata/golden/deprecation/new.json b/core/normalize/testdata/golden/deprecation/new.json similarity index 100% rename from normalize/testdata/golden/deprecation/new.json rename to core/normalize/testdata/golden/deprecation/new.json diff --git a/normalize/testdata/golden/deprecation/old.json b/core/normalize/testdata/golden/deprecation/old.json similarity index 100% rename from normalize/testdata/golden/deprecation/old.json rename to core/normalize/testdata/golden/deprecation/old.json diff --git a/normalize/testdata/golden/identical-specs/events.json b/core/normalize/testdata/golden/identical-specs/events.json similarity index 100% rename from normalize/testdata/golden/identical-specs/events.json rename to core/normalize/testdata/golden/identical-specs/events.json diff --git a/normalize/testdata/golden/identical-specs/new.json b/core/normalize/testdata/golden/identical-specs/new.json similarity index 100% rename from normalize/testdata/golden/identical-specs/new.json rename to core/normalize/testdata/golden/identical-specs/new.json diff --git a/normalize/testdata/golden/identical-specs/old.json b/core/normalize/testdata/golden/identical-specs/old.json similarity index 100% rename from normalize/testdata/golden/identical-specs/old.json rename to core/normalize/testdata/golden/identical-specs/old.json diff --git a/normalize/testdata/golden/new-endpoint/events.json b/core/normalize/testdata/golden/new-endpoint/events.json similarity index 100% rename from normalize/testdata/golden/new-endpoint/events.json rename to core/normalize/testdata/golden/new-endpoint/events.json diff --git a/normalize/testdata/golden/new-endpoint/new.json b/core/normalize/testdata/golden/new-endpoint/new.json similarity index 100% rename from normalize/testdata/golden/new-endpoint/new.json rename to core/normalize/testdata/golden/new-endpoint/new.json diff --git a/normalize/testdata/golden/new-endpoint/old.json b/core/normalize/testdata/golden/new-endpoint/old.json similarity index 100% rename from normalize/testdata/golden/new-endpoint/old.json rename to core/normalize/testdata/golden/new-endpoint/old.json diff --git a/core/plugin/plugin.go b/core/plugin/plugin.go new file mode 100644 index 0000000..4b0802c --- /dev/null +++ b/core/plugin/plugin.go @@ -0,0 +1,141 @@ +// Package plugin is what a change source is: every source is a plugin behind +// one interface, registered by name. A plugin reads its source and returns a +// Result; it stores nothing itself. Whoever runs it (patch-it's hosted +// ingestion service, or the test kit) stores the events, then the baselines. +// Adding a source is a new package under plugins/ that calls Register; nothing +// here changes. +package plugin + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "fmt" + "slices" + "sync" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" +) + +// Plugin is one place changes come from. +type Plugin interface { + // Name is the slug the command line selects it by and its events carry in + // `api`: "stripe", "openai-models". + Name() string + // Run reads the source as it is now and returns what changed since the + // baseline it saved last (env.Baselines.LastSpec). An error stores nothing. + Run(ctx context.Context, env Env) (Result, error) +} + +// Replayer is a plugin that can also diff two given releases (--from, --to): +// how a historical change is recreated without moving the normal baseline. +type Replayer interface { + Replay(ctx context.Context, env Env, from, to string) (Result, error) +} + +// Env is everything a plugin may reach outside itself, so a test can hand it +// baselines, the network and a clock of its own. A plugin that fetches through +// its own client (the OpenAPI plugin's adapter) ignores Get; its tests fake +// that client instead. +type Env struct { + Baselines BaselineReader + // Get fetches one URL. In both the hosted ingestion service and the test + // kit, this is fetch.Cache.Get (kit/kittest's Pages.Get wraps saved files + // the same way): a non-2xx, non-304 response fails with a *fetch.StatusError + // naming the status, returned as is, so errors.As finds it. A plugin that + // branches on the status (eol, when the provider's own site blocks a plain + // GET) can rely on that. + Get func(ctx context.Context, url string) ([]byte, error) + Now func() time.Time +} + +// BaselineReader is the one thing a plugin reads back: the baseline its last +// run saved. Ingest's store implements it; so does the test kit. +type BaselineReader interface { + // LastSpec is api's latest baseline, or nil (and no error) on a first run. + LastSpec(api string) (*Spec, error) +} + +// Spec is one baseline: a fetched copy of what a source said, kept only so a +// later run can diff against it, or tell in one hash comparison that nothing +// changed. +type Spec struct { + API string + Version string + Tag string + SHA256 string + SourceURL string + FetchedAt time.Time + Replay bool + Content []byte +} + +// Result is what one run found. +type Result struct { + Label string // what was read, for the summary: a tag, a snapshot, a URL + Events []event.EventV2 // valid v2 events, to store + Rejected []error // changes that failed to become valid events + Baselines []Spec // what the run read, saved after the events +} + +var ( + mu sync.Mutex + registry = map[string]Plugin{} +) + +// Register adds a plugin. A second plugin with the same name is a programming +// error: two sources would write the same `api`. So is the name "all", which +// `--api all` means. +func Register(p Plugin) { + mu.Lock() + defer mu.Unlock() + if p.Name() == "all" { + panic(`plugin: "all" means every plugin; a plugin can't be named it`) + } + if _, dup := registry[p.Name()]; dup { + panic(fmt.Sprintf("plugin: a plugin named %q is already registered", p.Name())) + } + registry[p.Name()] = p +} + +// Lookup finds a registered plugin by name. +func Lookup(name string) (Plugin, bool) { + mu.Lock() + defer mu.Unlock() + p, ok := registry[name] + return p, ok +} + +// Names are the registered plugins, sorted. +func Names() []string { + mu.Lock() + defer mu.Unlock() + names := make([]string, 0, len(registry)) + for n := range registry { + names = append(names, n) + } + slices.Sort(names) + return names +} + +// Baseline is what a plugin saves as the last thing it read, hashed so the +// next run can tell an unchanged source in one comparison. +func Baseline(api, version, tag, sourceURL string, content []byte, replay bool, at time.Time) Spec { + return Spec{ + API: api, + Version: version, + Tag: tag, + SHA256: SHA256(content), + SourceURL: sourceURL, + FetchedAt: at, + Replay: replay, + Content: content, + } +} + +// SHA256 is the hex hash a baseline is compared by. +func SHA256(data []byte) string { + sum := sha256.Sum256(data) + return hex.EncodeToString(sum[:]) +} diff --git a/plugin/plugin_test.go b/core/plugin/plugin_test.go similarity index 97% rename from plugin/plugin_test.go rename to core/plugin/plugin_test.go index 6595548..34f3b12 100644 --- a/plugin/plugin_test.go +++ b/core/plugin/plugin_test.go @@ -5,7 +5,7 @@ import ( "slices" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // testPlugin is a source defined only here: registering it and running it diff --git a/docs/plugins.json b/docs/plugins.json index dba6b2a..48aadc0 100644 --- a/docs/plugins.json +++ b/docs/plugins.json @@ -1,7 +1,7 @@ { "_comment": "Generated from the plugin registry and docs/plugins.md by `make plugins-json` (go run ./cmd/list-plugins). Don't edit by hand.", "$schema": "./plugins.schema.json", - "count": 29, + "count": 30, "plugins": [ { "id": "algolia-ingestion", diff --git a/docs/writing-a-plugin.md b/docs/writing-a-plugin.md index 9e08c71..cad93c2 100644 --- a/docs/writing-a-plugin.md +++ b/docs/writing-a-plugin.md @@ -17,7 +17,7 @@ go run ./cmd/new-plugin --api acme --provider Acme --format openapi It writes, and lists: -- the provider's definition, in the package the format reads it from (`adapter/`, `retire/`, `sdkguide/` or `plugins//`), and its `plugin.Register` line in that format's `init` (plus the `migrate/` map entry that `retirements` and `migrationguide` need); +- the provider's definition, in the package the format reads it from (`plugins/openapi/adapter/`, `plugins/retirements/retire/`, `plugins/migrationguide/sdkguide/` or `plugins//`), and its `plugin.Register` line in that format's `init` (plus the `core/migrate/` map entry that `retirements` and `migrationguide` need); - `plugins//_test.go`: the registration test, a golden test and a pinned drop test, over placeholder sources in `testdata/`, with the golden file written from them; - a row per saved file in that `testdata/README.md` (URL, date, license, quote to fill in); - `providers/.md` from the template (or nothing, with `--page`, when the provider already has one); @@ -75,9 +75,9 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp | Format plugin | Reads | Add a provider by | |---|---|---| -| `plugins/openapi` | An OpenAPI spec per release, diffed with `diff/` and turned into events by `normalize/` | An `adapter.Adapter` in `adapter/` (latest tag, fetch a tag's spec) and a `plugin.Register(Plugin{Adapter: …})` line | -| `plugins/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `retire/providers.go` | -| `plugins/migrationguide` | An SDK's migration guide at a release tag (removed request parameters) | A `sdkguide.Guide` in `sdkguide/` | +| `plugins/openapi` | An OpenAPI spec per release, diffed with `core/diff/` and turned into events by `core/normalize/` | An `adapter.Adapter` in `plugins/openapi/adapter/` (latest tag, fetch a tag's spec) and a `plugin.Register(Plugin{Adapter: …})` line | +| `plugins/retirements` | A model provider's deprecations page (a table of date, model, replacement) | A `retire.Page` in `plugins/retirements/retire/providers.go` | +| `plugins/migrationguide` | An SDK's migration guide at a release tag (removed request parameters) | A `sdkguide.Guide` in `plugins/migrationguide/sdkguide/` | | `plugins/removedmembers` | A package's table of removed members at a release tag (an RST simple table or a Markdown pipe table) | A `removedmembers.Guide` | | `plugins/changelog` | A `CHANGELOG.md` / `CHANGES.rst` / `HISTORY.rst` at a release tag | A `changelog.File` | | `plugins/feed` | An RSS or Atom feed | A `feed.Feed` with a reader for that vendor's entries | @@ -87,7 +87,7 @@ Write the numbers on the provider page, as `providers/vercel.md` does for its sp ## 4. The interface -A plugin implements `plugin.Plugin` (package [`plugin/`](../plugin/plugin.go)): +A plugin implements `plugin.Plugin` (package [`core/plugin/`](../core/plugin/plugin.go)): ```go type Plugin interface { @@ -126,9 +126,9 @@ func init() { `Register` panics on a duplicate name or the name `all`. -### Fetching: `env.Get` and `kit/` +### Fetching: `env.Get` and `core/kit/` -- Fetch **only** with `env.Get`. It caches by `ETag` / `Last-Modified`, retries, and in tests serves saved files. `CI_go` fails a package outside `fetch/`, `kit/` and `adapter/` that imports `net/http`. +- Fetch **only** with `env.Get`. It caches by `ETag` / `Last-Modified`, retries, and in tests serves saved files. `CI_go` fails a package outside `core/fetch/`, `core/kit/` and `plugins/openapi/adapter/` that imports `net/http`. - `kit.Unchanged(env, api, body)`: true when the page hashes to the last baseline. Return early: an unchanged source costs one GET and nothing else. - `kit.Cite(ctx, archiver, url, read, want)`: for a **live page**. Takes a Wayback Machine snapshot, reads it with your own reader and checks it says exactly what the live page said. Make the events from the snapshot and cite its URL. No snapshot, no events. - `plugin.Baseline(api, version, tag, sourceURL, content, replay, now)`: the baseline to return. @@ -140,7 +140,7 @@ The event format is [patch-it's change-event contract](https://github.com/patch- ## 5. Save the source -Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads. +Save a real copy of what the plugin reads under your package's `testdata/` (or the reader package's, like `plugins/retirements/retire/testdata/`). Add a row to that directory's `README.md`: file, URL, date fetched, license, and a short quote of the part the plugin reads. - **Openly licensed files** (MIT, BSD, Apache, CC BY): keep them whole. - **Vendor documentation pages**: trim to what the plugin reads (the tables, the sections), copy every kept line unchanged, mark it "excerpt for testing; © the vendor", and say what you left out. @@ -150,7 +150,7 @@ Save a real copy of what the plugin reads under your package's `testdata/` (or t ## 6. Write the golden test -The test kit, `kit/kittest`, runs the plugin with no network, no database and a fixed clock: +The test kit, `core/kit/kittest`, runs the plugin with no network, no database and a fixed clock: ```go func TestGolden(t *testing.T) { diff --git a/event/event.go b/event/event.go index d17f1c9..02bec52 100644 --- a/event/event.go +++ b/event/event.go @@ -1,215 +1,50 @@ +// Package event is the old import path of github.com/patch-it-dev/patch-it-plugins/core/event. +// +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/event +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package event -import ( - "crypto/sha256" - "encoding/hex" - "fmt" - "regexp" - "strings" - "time" - "unicode/utf8" -) +import moved "github.com/patch-it-dev/patch-it-plugins/core/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/event. type ( - ChangeType string - AffectedKind string - Side string -) - -const ( - ChangeTypeBreaking ChangeType = "breaking" - ChangeTypeDeprecation ChangeType = "deprecation" - ChangeTypeNewFeature ChangeType = "new_feature" - ChangeTypeFix ChangeType = "fix" + Affected = moved.Affected + AffectedKind = moved.AffectedKind + ChangeEvent = moved.ChangeEvent + ChangeType = moved.ChangeType + EventV2 = moved.EventV2 + PackageChange = moved.PackageChange + Side = moved.Side + Subject = moved.Subject + SubjectType = moved.SubjectType ) +// Deprecated: the constants live in github.com/patch-it-dev/patch-it-plugins/core/event. const ( - AffectedKindOperation AffectedKind = "operation" - AffectedKindRequestParameter AffectedKind = "request_parameter" - AffectedKindSchema AffectedKind = "schema" - AffectedKindSchemaProperty AffectedKind = "schema_property" + AffectedKindOperation = moved.AffectedKindOperation + AffectedKindRequestParameter = moved.AffectedKindRequestParameter + AffectedKindSchema = moved.AffectedKindSchema + AffectedKindSchemaProperty = moved.AffectedKindSchemaProperty + ChangeTypeBreaking = moved.ChangeTypeBreaking + ChangeTypeDeprecation = moved.ChangeTypeDeprecation + ChangeTypeFix = moved.ChangeTypeFix + ChangeTypeNewFeature = moved.ChangeTypeNewFeature + PackageChangedDefault = moved.PackageChangedDefault + PackageRemovedParameter = moved.PackageRemovedParameter + PackageRemovedSymbol = moved.PackageRemovedSymbol + PackageRenamedSymbol = moved.PackageRenamedSymbol + SideRequest = moved.SideRequest + SideResponse = moved.SideResponse + SubjectAPIOperation = moved.SubjectAPIOperation + SubjectCIRuntime = moved.SubjectCIRuntime + SubjectModel = moved.SubjectModel + SubjectPackageRelease = moved.SubjectPackageRelease ) -const ( - SideRequest Side = "request" - SideResponse Side = "response" +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/event. +var ( + DecodeV2 = moved.DecodeV2 + Fingerprint = moved.Fingerprint + FingerprintV2 = moved.FingerprintV2 ) - -type Affected struct { - Kind AffectedKind `json:"kind"` // kind of change - Side Side `json:"side"` // which side is breaking - Operation string `json:"operation,omitempty"` // if operation change, what changed - Schema string `json:"schema,omitempty"` // if schema change, what changed - Property string `json:"property,omitempty"` // if poperty change, what changed - // Value is the one value of Property the change is about, when it's about one: - // the retired model name for a model retirement ("gpt-4"). Optional. - Value string `json:"value,omitempty"` -} - -type ChangeEvent struct { - ID int64 `json:"id"` - Fingerprint string `json:"fingerprint"` - API string `json:"api"` - Version string `json:"version"` - PreviousVersion string `json:"previous_version,omitempty"` - ChangeType ChangeType `json:"change_type"` - Breaking bool `json:"breaking"` - Affected Affected `json:"affected"` - Description string `json:"description"` - MigrationHint string `json:"migration_hint,omitempty"` - SourceURL string `json:"source_url"` - SourcePointer string `json:"source_pointer,omitempty"` - SourceExcerpt string `json:"source_excerpt"` - Confidence float64 `json:"confidence"` - DetectedAt time.Time `json:"detected_at"` -} - -// Fingerprint identifies one change at one location, so re-running ingest over -// the same specs updates nothing instead of duplicating events. detail is what -// separates two changes at the same place: the enum value added, the old and -// new type, "added as required". Absent fields are empty strings, and the parts -// are joined with a separator that cannot appear in a path or a schema name. -func Fingerprint(api, version string, changeType ChangeType, affected Affected, detail string) string { - sum := sha256.Sum256([]byte(strings.Join([]string{ - api, - version, - string(changeType), - string(affected.Kind), - string(affected.Side), - affected.Operation, - affected.Schema, - affected.Property, - detail, - }, "|"))) - return "sha256:" + hex.EncodeToString(sum[:]) -} - -// fingerprintPattern is the contract's shape for a fingerprint (the schema's -// pattern in the change event contract). patch-it checks the same pattern. -var fingerprintPattern = regexp.MustCompile(`^sha256:[0-9a-f]{64}$`) - -func (e ChangeEvent) Validate() error { - if err := checkCommon(e.SourceURL, e.SourceExcerpt, e.Fingerprint, e.API, e.Version, - e.Description, e.DetectedAt, e.ChangeType, e.Breaking, e.Confidence); err != nil { - return err - } - - if err := e.Affected.validate(); err != nil { - return err - } - - // Rule 5 (continued): a value is a value of a property. - if e.Affected.Value != "" && e.Affected.Property == "" { - return fmt.Errorf("affected.value needs affected.property: it is a value of that property") - } - - return nil -} - -// checkCommon is the contract's rules for every field outside affected (v1) or -// subject (v2): the two versions differ only in what changed, not in the rest. -func checkCommon(sourceURL, excerpt, fingerprint, api, version, description string, - detectedAt time.Time, changeType ChangeType, breaking bool, confidence float64) error { - // Rule 1: provenance is mandatory — the anti-hallucination mechanism. - if sourceURL == "" { - return fmt.Errorf("source_url is required") - } - if excerpt == "" { - return fmt.Errorf("source_excerpt is required") - } - - // Rule 2: other required fields must be non-empty. - if fingerprint == "" { - return fmt.Errorf("fingerprint is required") - } - if !fingerprintPattern.MatchString(fingerprint) { - return fmt.Errorf("fingerprint must look like sha256:<64 lowercase hex>, got %q", fingerprint) - } - if api == "" { - return fmt.Errorf("api is required") - } - if version == "" { - return fmt.Errorf("version is required") - } - if description == "" { - return fmt.Errorf("description is required") - } - if detectedAt.IsZero() { - return fmt.Errorf("detected_at is required") - } - - // Rule 3: change_type must be one of the known enum values. - if changeType != ChangeTypeBreaking && - changeType != ChangeTypeDeprecation && - changeType != ChangeTypeNewFeature && - changeType != ChangeTypeFix { - return fmt.Errorf("change_type must be a valid enum value, got %q", changeType) - } - - // Rule 4: breaking must agree with change_type. - if breaking != (changeType == ChangeTypeBreaking) { - return fmt.Errorf("breaking (%v) must equal change_type == breaking", breaking) - } - - // Rule 6: confidence must be in [0, 1]. - if confidence < 0 || confidence > 1 { - return fmt.Errorf("confidence must be between 0 and 1, got %v", confidence) - } - - // Rule 7: source_excerpt is capped at 2000 characters. Count runes, not - // bytes: spec text is full of non-ASCII (Stripe writes "invoice\u2019s"), and - // len() would reject excerpts well under the documented limit. - if n := utf8.RuneCountInString(excerpt); n > 2000 { - return fmt.Errorf("source_excerpt must be at most 2000 characters, got %d", n) - } - return nil -} - -// validate is the contract's rules for an API location: v1's affected, and v2's -// api_operation subject. Kind decides the side and the required fields. -func (a Affected) validate() error { - // Rule 3 (continued): affected.kind and affected.side must be valid too. - if a.Kind != AffectedKindOperation && - a.Kind != AffectedKindRequestParameter && - a.Kind != AffectedKindSchema && - a.Kind != AffectedKindSchemaProperty { - return fmt.Errorf("affected.kind must be a valid enum value, got %q", a.Kind) - } - if a.Side != SideRequest && a.Side != SideResponse { - return fmt.Errorf("affected.side must be a valid enum value, got %q", a.Side) - } - - // Rule 5: affected's required sub-fields, and its side, depend on its kind. - // Kind decides side: requests live under paths, responses under schemas. - switch a.Kind { - case AffectedKindOperation: - if a.Operation == "" { - return fmt.Errorf("affected.operation is required when kind is operation") - } - if a.Side != SideRequest { - return fmt.Errorf("affected.side must be %q when kind is operation, got %q", SideRequest, a.Side) - } - case AffectedKindRequestParameter: - if a.Operation == "" || a.Property == "" { - return fmt.Errorf("affected.operation and affected.property are required when kind is request_parameter") - } - if a.Side != SideRequest { - return fmt.Errorf("affected.side must be %q when kind is request_parameter, got %q", SideRequest, a.Side) - } - case AffectedKindSchema: - if a.Schema == "" { - return fmt.Errorf("affected.schema is required when kind is schema") - } - if a.Side != SideResponse { - return fmt.Errorf("affected.side must be %q when kind is schema, got %q", SideResponse, a.Side) - } - case AffectedKindSchemaProperty: - if a.Schema == "" || a.Property == "" { - return fmt.Errorf("affected.schema and affected.property are required when kind is schema_property") - } - if a.Side != SideResponse { - return fmt.Errorf("affected.side must be %q when kind is schema_property, got %q", SideResponse, a.Side) - } - } - return nil -} diff --git a/fetch/fetch.go b/fetch/fetch.go index 8cb228c..8d79a32 100644 --- a/fetch/fetch.go +++ b/fetch/fetch.go @@ -1,135 +1,19 @@ -// Package fetch does plain HTTP GETs with retries and a timeout. It knows -// nothing about specs, Stripe, or any other caller — just how to reliably -// download bytes from a URL. +// Package fetch is the old import path of github.com/patch-it-dev/patch-it-plugins/core/fetch. +// +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/fetch +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package fetch -import ( - "context" - "errors" - "fmt" - "io" - "net/http" - "time" -) +import moved "github.com/patch-it-dev/patch-it-plugins/core/fetch" -const ( - maxAttempts = 3 - attemptTimeout = 30 * time.Second +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/fetch. +type ( + Cache = moved.Cache + StatusError = moved.StatusError ) -// baseBackoff is a variable only so tests can shorten it. -var baseBackoff = 1 * time.Second - -// StatusError is returned when a request completes but with a non-200 status, -// so callers can check the exact code (e.g. a 404 meaning "try elsewhere") -// instead of matching on an error string. -type StatusError struct { - URL string - StatusCode int -} - -func (e *StatusError) Error() string { - return fmt.Sprintf("unexpected status %d from %s", e.StatusCode, e.URL) -} - -// requestError marks a failure to even build the HTTP request (e.g. a -// malformed URL). It's never transient, so Get fails fast on it instead of -// retrying like it does for network errors and 5xx responses. -type requestError struct{ err error } - -func (e *requestError) Error() string { return e.err.Error() } -func (e *requestError) Unwrap() error { return e.err } - -// Get downloads url, retrying on network errors and 5xx responses up to -// maxAttempts times with exponential backoff (1s, 2s, 4s...). A 4xx response -// means the request itself is wrong, so it fails immediately instead of -// retrying. headers are set on every attempt; nil is fine for none. -func Get(ctx context.Context, url string, headers map[string]string) ([]byte, error) { - r, err := get(ctx, url, headers) - if err == nil && r.status == http.StatusNotModified { - // Get sends no validators of its own, so a 304 is the server's error, - // never an empty page. - return nil, &StatusError{URL: url, StatusCode: r.status} - } - return r.body, err -} - -// response is one successful attempt: 200 with its body, or 304 Not Modified -// to a conditional request (no body). -type response struct { - status int - body []byte - header http.Header -} - -// get is Get's retry loop, returning the whole response. -func get(ctx context.Context, url string, headers map[string]string) (response, error) { - var lastErr error - - for attempt := 1; attempt <= maxAttempts; attempt++ { - r, err := attemptGet(ctx, url, headers) - status := r.status - if err == nil { - return r, nil - } - lastErr = err - - var reqErr *requestError - if errors.As(err, &reqErr) { - return response{}, err // a malformed request won't build any differently on retry - } - - if status >= 400 && status < 500 { - return response{}, err // retrying a bad request never helps - } - - if attempt < maxAttempts { - backoff := baseBackoff * time.Duration(1<<(attempt-1)) - select { - case <-time.After(backoff): - case <-ctx.Done(): - return response{}, ctx.Err() - } - } - } - - return response{}, fmt.Errorf("fetching %s failed after %d attempts: %w", url, maxAttempts, lastErr) -} - -// attemptGet makes one attempt, bounded by its own timeout so a single hung -// request can't block forever. status is 0 when the failure happened before -// a response arrived (a bad request, a network error). A 304 is a success: it -// only comes back to a request that asked for it (If-None-Match, -// If-Modified-Since). -func attemptGet(ctx context.Context, url string, headers map[string]string) (response, error) { - ctx, cancel := context.WithTimeout(ctx, attemptTimeout) - defer cancel() - - req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) - if err != nil { - return response{}, &requestError{err: fmt.Errorf("could not build the request: %w", err)} - } - for key, value := range headers { - req.Header.Set(key, value) - } - - resp, err := http.DefaultClient.Do(req) - if err != nil { - return response{}, fmt.Errorf("could not retrieve the content from given url: %w", err) - } - defer resp.Body.Close() - - r := response{status: resp.StatusCode, header: resp.Header} - if resp.StatusCode == http.StatusNotModified { - return r, nil - } - if resp.StatusCode != http.StatusOK { - return r, &StatusError{URL: url, StatusCode: resp.StatusCode} - } - - r.body, err = io.ReadAll(resp.Body) - if err != nil { - return r, fmt.Errorf("could not read the response body: %w", err) - } - return r, nil -} +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/fetch. +var ( + Get = moved.Get +) diff --git a/internal/pluginlist/pluginlist.go b/internal/pluginlist/pluginlist.go index 7ad543f..5b75fac 100644 --- a/internal/pluginlist/pluginlist.go +++ b/internal/pluginlist/pluginlist.go @@ -19,7 +19,7 @@ import ( "strconv" "strings" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // Table is the plugin list, relative to the repo root. diff --git a/kit/kit.go b/kit/kit.go index 47920d0..5575062 100644 --- a/kit/kit.go +++ b/kit/kit.go @@ -1,48 +1,30 @@ -// Package kit is what source plugins share beyond the core: the Wayback -// Machine client a plugin cites a live page through (Wayback, Cite) and the -// "same page as last run" check (Unchanged). Fetching with ETag and -// Last-Modified caching is fetch's Cache, handed to every plugin as -// plugin.Env.Get; the test kit is kittest. +// Package kit is the old import path of github.com/patch-it-dev/patch-it-plugins/core/kit. // -// kit is not a plugin: plugins import it, it imports no plugin. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/kit +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package kit import ( "context" - "fmt" - "reflect" - "github.com/patch-it-dev/patch-it-plugins/plugin" + moved "github.com/patch-it-dev/patch-it-plugins/core/kit" ) -// Unchanged reports whether body is what api's last stored baseline hashed -// to, and returns that baseline (nil on a first run). A plugin reading a live -// page returns early on true: an unchanged page costs one GET and no snapshot. -func Unchanged(env plugin.Env, api string, body []byte) (last *plugin.Spec, same bool, err error) { - last, err = env.Baselines.LastSpec(api) - if err != nil { - return nil, false, fmt.Errorf("loading the last baseline of %s: %w", api, err) - } - return last, last != nil && last.SHA256 == plugin.SHA256(body), nil -} +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/kit. +type ( + Archiver = moved.Archiver + Wayback = moved.Wayback +) -// Cite snapshots a live page and checks the snapshot holds what the plugin -// read from the live page: read turns bytes into whatever the plugin makes -// events from, and the snapshot's must deep-equal want. The events are then -// made from the snapshot and cite snapURL, so every excerpt is on the page it -// cites. No snapshot, or one that says something else (the page changed in -// between), is an error: no provenance, no event. +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/kit. +var ( + Unchanged = moved.Unchanged +) + +// Cite forwards to core/kit.Cite. +// +// Deprecated: use github.com/patch-it-dev/patch-it-plugins/core/kit.Cite. func Cite[T any](ctx context.Context, a Archiver, pageURL string, read func([]byte) (T, error), want T) (snapURL string, snap []byte, got T, err error) { - snapURL, snap, err = a.Snapshot(ctx, pageURL) - if err != nil { - return "", nil, got, fmt.Errorf("no events without a snapshot to cite: %w", err) - } - got, err = read(snap) - if err != nil { - return "", nil, got, fmt.Errorf("reading the snapshot %s: %w", snapURL, err) - } - if !reflect.DeepEqual(got, want) { - return "", nil, got, fmt.Errorf("the snapshot %s doesn't hold what %s says now; run again", snapURL, pageURL) - } - return snapURL, snap, got, nil + return moved.Cite(ctx, a, pageURL, read, want) } diff --git a/kit/kittest/kittest.go b/kit/kittest/kittest.go index 4680623..39f0e4e 100644 --- a/kit/kittest/kittest.go +++ b/kit/kittest/kittest.go @@ -1,214 +1,33 @@ -// Package kittest is the plugin test kit: a saved copy of a source in, the -// events a plugin stores out, compared with a golden file. Nothing reaches the -// network or a database: a URL the test didn't save fails the test, events and -// baselines are kept in memory (Mem), and the clock is fixed, so the same -// pages always give byte-identical events. +// Package kittest is the old import path of github.com/patch-it-dev/patch-it-plugins/core/kit/kittest. // -// got := kittest.Ingest(t, plugin, kittest.Pages{url: "testdata/page.md"}) -// kittest.Golden(t, "testdata/golden/numpy.json", got) -// -// `go test ./plugins/ -update` rewrites a plugin's golden files; -// review the diff like code. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/kit/kittest +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package kittest -import ( - "bytes" - "context" - "encoding/json" - "flag" - "fmt" - "os" - "path/filepath" - "reflect" - "strconv" - "testing" - "time" +import moved "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/kit/kittest. +type ( + Archive = moved.Archive + Mem = moved.Mem + Pages = moved.Pages + Sink = moved.Sink ) -var update = flag.Bool("update", false, "rewrite the golden files from what the plugins store now") - -// Clock is the time every kit run detects its changes at. -var Clock = time.Date(2026, 11, 14, 12, 0, 0, 0, time.UTC) - -// Pages are the saved copies a run may fetch: URL to file, relative to the -// test's package. -type Pages map[string]string - -// Get serves Pages, and fails the test on any other URL. -func (p Pages) Get(t testing.TB) func(context.Context, string) ([]byte, error) { - return func(_ context.Context, url string) ([]byte, error) { - file, ok := p[url] - if !ok { - t.Errorf("fetched %s, which the test didn't save", url) - return nil, fmt.Errorf("no saved copy of %s", url) - } - return Read(t, file), nil - } -} - -// Read is a saved file, or the test fails. -func Read(t testing.TB, file string) []byte { - t.Helper() - b, err := os.ReadFile(file) - if err != nil { - t.Fatal(err) - } - return b -} - -// Env is an empty Mem for the baselines and the events, Pages for the network -// and Clock for the time. Nothing outside the test is touched: no database, no -// network. -func Env(t testing.TB, pages Pages) plugin.Env { - t.Helper() - return plugin.Env{Baselines: NewMem(), Get: pages.Get(t), Now: func() time.Time { return Clock }} -} - -// Ingest runs p twice and returns what the first run stored. Any rejected -// event or error fails the test, and so does a second run over the same pages -// that stores anything new: the fingerprints must dedupe. -func Ingest(t testing.TB, p plugin.Plugin, pages Pages) []event.EventV2 { - t.Helper() - env := Env(t, pages) - return IngestWith(t, env, p) -} - -// IngestWith is Ingest over an Env the test built (its own archive, a baseline -// already saved). env.Baselines is where the events are stored too, so it must -// be a Sink, as Env's Mem is. -func IngestWith(t testing.TB, env plugin.Env, p plugin.Plugin) []event.EventV2 { - t.Helper() - sink, ok := env.Baselines.(Sink) - if !ok { - t.Fatalf("env.Baselines is a %T, not a kittest.Sink to store the events in", env.Baselines) - } - if rejected, err := Run(context.Background(), env, sink, p); err != nil || rejected { - t.Fatalf("%s: rejected=%v err=%v", p.Name(), rejected, err) - } - first := Stored(t, sink) - if rejected, err := Run(context.Background(), env, sink, p); err != nil || rejected { - t.Fatalf("%s, second run: rejected=%v err=%v", p.Name(), rejected, err) - } - if again := Stored(t, sink); len(again) != len(first) { - t.Errorf("%s: a second run over the same pages stored %d more events", p.Name(), len(again)-len(first)) - } - return first -} - -// Stored is every event in s, in feed order, or the test fails. -func Stored(t testing.TB, s Sink) []event.EventV2 { - t.Helper() - all, err := s.All() - if err != nil { - t.Fatal(err) - } - return all -} - -// Golden compares events with the JSON file at path, or rewrites it with -// -update. Every event must also be valid v2, or the golden would pin a bug. -func Golden(t testing.TB, path string, events []event.EventV2) { - t.Helper() - golden(t, path, events, *update) -} - -// CompareGolden is Golden that never rewrites the file, even with -update: -// for a test that checks someone else's golden file. -func CompareGolden(t testing.TB, path string, events []event.EventV2) { - t.Helper() - golden(t, path, events, false) -} - -func golden(t testing.TB, path string, events []event.EventV2, rewrite bool) { - t.Helper() - for _, e := range events { - if err := e.Validate(); err != nil { - t.Errorf("event %d (%s) is invalid: %v", e.ID, e.Description, err) - } - } - if events == nil { - events = []event.EventV2{} - } - var buf bytes.Buffer - enc := json.NewEncoder(&buf) - enc.SetIndent("", " ") - enc.SetEscapeHTML(false) - if err := enc.Encode(events); err != nil { - t.Fatal(err) - } - if rewrite { - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(path, buf.Bytes(), 0o644); err != nil { - t.Fatal(err) - } - return - } - want, err := os.ReadFile(path) - if err != nil { - t.Fatalf("%v (run the test with -update to create it)", err) - } - if !bytes.Equal(want, buf.Bytes()) { - t.Errorf("%s: the stored events differ from the golden file (%d events now); if the change is intended, rerun with -update and review the diff\n%s", - path, len(events), firstDiff(want, buf.Bytes())) - } -} - -// firstDiff is the first line that differs, for the failure message. -func firstDiff(want, got []byte) string { - w, g := bytes.Split(want, []byte("\n")), bytes.Split(got, []byte("\n")) - for i := 0; i < len(w) || i < len(g); i++ { - var wl, gl []byte - if i < len(w) { - wl = w[i] - } - if i < len(g) { - gl = g[i] - } - if !bytes.Equal(wl, gl) { - return "line " + strconv.Itoa(i+1) + ":\n want " + string(wl) + "\n got " + string(gl) - } - } - return "" -} - -// Archive is the Wayback Machine without the network: it serves a saved copy -// as the snapshot of a page, under a fixed timestamp, and counts the -// snapshots it was asked for. -type Archive struct { - T testing.TB - Pages Pages // the page's URL to the file the snapshot holds - Timestamp string // 14 digits; default 20261114120000 - Calls int -} - -func (a *Archive) Snapshot(_ context.Context, page string) (string, []byte, error) { - a.Calls++ - file, ok := a.Pages[page] - if !ok { - return "", nil, fmt.Errorf("no snapshot of %s in the test archive", page) - } - ts := a.Timestamp - if ts == "" { - ts = "20261114120000" - } - return "https://web.archive.org/web/" + ts + "/" + page, Read(a.T, file), nil -} - -// Registered fails the test unless p's package registered a plugin of p's -// type under p's name: each plugin package checks its own registration. -func Registered(t testing.TB, p plugin.Plugin) { - t.Helper() - got, ok := plugin.Lookup(p.Name()) - if !ok { - t.Errorf("no plugin registered as %q", p.Name()) - return - } - if reflect.TypeOf(got) != reflect.TypeOf(p) { - t.Errorf("%q is a %T, want a %T", p.Name(), got, p) - } -} +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/kit/kittest. +var ( + CheckSink = moved.CheckSink + CompareGolden = moved.CompareGolden + Env = moved.Env + Golden = moved.Golden + Ingest = moved.Ingest + IngestWith = moved.IngestWith + NewMem = moved.NewMem + Read = moved.Read + Registered = moved.Registered + Replay = moved.Replay + Run = moved.Run + Stored = moved.Stored + Clock = moved.Clock +) diff --git a/migrate/migrate.go b/migrate/migrate.go index c1dbcce..cf6865d 100644 --- a/migrate/migrate.go +++ b/migrate/migrate.go @@ -1,120 +1,14 @@ -// Package migrate converts stored v1 change events to the proposed v2 contract -// (the change event contract): `affected` becomes a typed -// `subject`. It runs once, at the cut-over, over every event in the store. +// Package migrate is the old import path of github.com/patch-it-dev/patch-it-plugins/core/migrate. // -// A Stripe event keeps its fingerprint: v2's api_operation formula is v1's. -// A model retirement or an SDK release gets a new one, and `supersedes` names -// the old one, so the patch-it client, which finds its open issues and pull -// requests by the fingerprint in their marker, knows they're the same change -// and opens nothing twice. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/migrate +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package migrate -import ( - "fmt" - "regexp" - "strings" +import moved "github.com/patch-it-dev/patch-it-plugins/core/migrate" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/retire" - "github.com/patch-it-dev/patch-it-plugins/sdkguide" +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/migrate. +var ( + Fresh = moved.Fresh + ToV2 = moved.ToV2 ) - -// providers are the model retirement slugs and who retires the models. -var providers = map[string]string{ - retire.OpenAI.API: "openai", - retire.Anthropic.API: "anthropic", -} - -// guides are the SDKs whose v1 events came from a migration guide. -var guides = map[string]sdkguide.Guide{sdkguide.AnthropicV1.API: sdkguide.AnthropicV1} - -// ToV2 converts one v1 event. It refuses an event it can't place rather than -// guess: an unknown slug with a value, or an SDK event that isn't a removed -// request parameter. -func ToV2(e event.ChangeEvent) (event.EventV2, error) { - v2 := event.EventV2{ - ID: e.ID, API: e.API, Version: e.Version, PreviousVersion: e.PreviousVersion, - ChangeType: e.ChangeType, Breaking: e.Breaking, Description: e.Description, - MigrationHint: e.MigrationHint, SourceURL: e.SourceURL, SourcePointer: e.SourcePointer, - SourceExcerpt: e.SourceExcerpt, Confidence: e.Confidence, DetectedAt: e.DetectedAt, - } - a := e.Affected - if provider, ok := providers[e.API]; ok { - if a.Value == "" { - return event.EventV2{}, fmt.Errorf("event %d: a %s event without the model in affected.value", e.ID, e.API) - } - v2.Subject = event.Subject{ - Type: event.SubjectModel, Provider: provider, Name: a.Value, - Replacement: replacement(e.MigrationHint), - } - return rekeyed(v2, e.Fingerprint), nil - } - if g, ok := guides[e.API]; ok { - if a.Kind != event.AffectedKindRequestParameter || a.Property == "" { - return event.EventV2{}, fmt.Errorf("event %d: an %s SDK event that isn't a removed parameter", e.ID, e.API) - } - v2.Subject = event.Subject{ - Type: event.SubjectPackageRelease, Ecosystem: "pypi", Package: g.API, - Change: event.PackageRemovedParameter, Parameter: a.Property, Symbols: g.Symbols, - } - return rekeyed(v2, e.Fingerprint), nil - } - if a.Value != "" { - return event.EventV2{}, fmt.Errorf("event %d: affected.value on %s, which isn't a model retirement", e.ID, e.API) - } - v2.Subject = event.Subject{ - Type: event.SubjectAPIOperation, Kind: a.Kind, Side: a.Side, - Operation: a.Operation, Schema: a.Schema, Property: a.Property, - } - v2.Fingerprint = e.Fingerprint // the same formula: unchanged by construction - return v2, nil -} - -// rekeyed gives the event its v2 fingerprint and says which v1 one it replaces. -func rekeyed(v2 event.EventV2, old string) event.EventV2 { - v2.Fingerprint = event.FingerprintV2(v2.API, v2.Version, v2.ChangeType, v2.Subject, "") - if v2.Fingerprint != old { - v2.Supersedes = old - } - return v2 -} - -// useInstead is the hint retire.Events writes: "Use instead: …". -var useInstead = regexp.MustCompile("^Use (.+?) instead: ") - -// replacement is the one model the provider names, when its replacement cell -// is exactly one model name: not none ("names no replacement model"), not -// several, not a model with a setting (`gpt-5.6-sol` (`reasoning.mode: pro`)). -// The patch-it client opens an issue for the rest, as it does today. -func replacement(hint string) string { - m := useInstead.FindStringSubmatch(hint) - if m == nil { - return "" - } - name := retire.First(m[1]) - if name == "" || strings.TrimSpace(m[1]) != "`"+name+"`" { - return "" - } - return name -} - -// Fresh converts events a source has just produced in the v1 shape. Unlike a -// stored row, a fresh event replaces nothing, so it carries no `supersedes`. An -// event that can't be placed is returned as an error, like a failed validation. -func Fresh(events []event.ChangeEvent) ([]event.EventV2, []error) { - var out []event.EventV2 - var errs []error - for _, e := range events { - v2, err := ToV2(e) - if err == nil { - v2.Supersedes = "" - err = v2.Validate() - } - if err != nil { - errs = append(errs, err) - continue - } - out = append(out, v2) - } - return out, errs -} diff --git a/plugin/plugin.go b/plugin/plugin.go index 14e919c..4b0fb6e 100644 --- a/plugin/plugin.go +++ b/plugin/plugin.go @@ -1,141 +1,27 @@ -// Package plugin is what a change source is: every source is a plugin behind -// one interface, registered by name. A plugin reads its source and returns a -// Result; it stores nothing itself. Whoever runs it (patch-it's hosted -// ingestion service, or the test kit) stores the events, then the baselines. -// Adding a source is a new package under plugins/ that calls Register; nothing -// here changes. +// Package plugin is the old import path of github.com/patch-it-dev/patch-it-plugins/core/plugin. +// +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/core/plugin +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package plugin -import ( - "context" - "crypto/sha256" - "encoding/hex" - "fmt" - "slices" - "sync" - "time" +import moved "github.com/patch-it-dev/patch-it-plugins/core/plugin" - "github.com/patch-it-dev/patch-it-plugins/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/core/plugin. +type ( + BaselineReader = moved.BaselineReader + Env = moved.Env + Plugin = moved.Plugin + Replayer = moved.Replayer + Result = moved.Result + Spec = moved.Spec ) -// Plugin is one place changes come from. -type Plugin interface { - // Name is the slug the command line selects it by and its events carry in - // `api`: "stripe", "openai-models". - Name() string - // Run reads the source as it is now and returns what changed since the - // baseline it saved last (env.Baselines.LastSpec). An error stores nothing. - Run(ctx context.Context, env Env) (Result, error) -} - -// Replayer is a plugin that can also diff two given releases (--from, --to): -// how a historical change is recreated without moving the normal baseline. -type Replayer interface { - Replay(ctx context.Context, env Env, from, to string) (Result, error) -} - -// Env is everything a plugin may reach outside itself, so a test can hand it -// baselines, the network and a clock of its own. A plugin that fetches through -// its own client (the OpenAPI plugin's adapter) ignores Get; its tests fake -// that client instead. -type Env struct { - Baselines BaselineReader - // Get fetches one URL. In both the hosted ingestion service and the test - // kit, this is fetch.Cache.Get (kit/kittest's Pages.Get wraps saved files - // the same way): a non-2xx, non-304 response fails with a *fetch.StatusError - // naming the status, returned as is, so errors.As finds it. A plugin that - // branches on the status (eol, when the provider's own site blocks a plain - // GET) can rely on that. - Get func(ctx context.Context, url string) ([]byte, error) - Now func() time.Time -} - -// BaselineReader is the one thing a plugin reads back: the baseline its last -// run saved. Ingest's store implements it; so does the test kit. -type BaselineReader interface { - // LastSpec is api's latest baseline, or nil (and no error) on a first run. - LastSpec(api string) (*Spec, error) -} - -// Spec is one baseline: a fetched copy of what a source said, kept only so a -// later run can diff against it, or tell in one hash comparison that nothing -// changed. -type Spec struct { - API string - Version string - Tag string - SHA256 string - SourceURL string - FetchedAt time.Time - Replay bool - Content []byte -} - -// Result is what one run found. -type Result struct { - Label string // what was read, for the summary: a tag, a snapshot, a URL - Events []event.EventV2 // valid v2 events, to store - Rejected []error // changes that failed to become valid events - Baselines []Spec // what the run read, saved after the events -} - +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/core/plugin. var ( - mu sync.Mutex - registry = map[string]Plugin{} + Baseline = moved.Baseline + Lookup = moved.Lookup + Names = moved.Names + Register = moved.Register + SHA256 = moved.SHA256 ) - -// Register adds a plugin. A second plugin with the same name is a programming -// error: two sources would write the same `api`. So is the name "all", which -// `--api all` means. -func Register(p Plugin) { - mu.Lock() - defer mu.Unlock() - if p.Name() == "all" { - panic(`plugin: "all" means every plugin; a plugin can't be named it`) - } - if _, dup := registry[p.Name()]; dup { - panic(fmt.Sprintf("plugin: a plugin named %q is already registered", p.Name())) - } - registry[p.Name()] = p -} - -// Lookup finds a registered plugin by name. -func Lookup(name string) (Plugin, bool) { - mu.Lock() - defer mu.Unlock() - p, ok := registry[name] - return p, ok -} - -// Names are the registered plugins, sorted. -func Names() []string { - mu.Lock() - defer mu.Unlock() - names := make([]string, 0, len(registry)) - for n := range registry { - names = append(names, n) - } - slices.Sort(names) - return names -} - -// Baseline is what a plugin saves as the last thing it read, hashed so the -// next run can tell an unchanged source in one comparison. -func Baseline(api, version, tag, sourceURL string, content []byte, replay bool, at time.Time) Spec { - return Spec{ - API: api, - Version: version, - Tag: tag, - SHA256: SHA256(content), - SourceURL: sourceURL, - FetchedAt: at, - Replay: replay, - Content: content, - } -} - -// SHA256 is the hex hash a baseline is compared by. -func SHA256(data []byte) string { - sum := sha256.Sum256(data) - return hex.EncodeToString(sum[:]) -} diff --git a/plugins/all/all_test.go b/plugins/all/all_test.go index 5b4f030..407ebb6 100644 --- a/plugins/all/all_test.go +++ b/plugins/all/all_test.go @@ -10,7 +10,7 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // Every package next to this one that registers a plugin is imported here, so diff --git a/plugins/apichangelog/apichangelog.go b/plugins/apichangelog/apichangelog.go index fb251e3..1856567 100644 --- a/plugins/apichangelog/apichangelog.go +++ b/plugins/apichangelog/apichangelog.go @@ -23,9 +23,10 @@ import ( "log" "sort" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/github" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { @@ -209,20 +210,10 @@ func (p Plugin) Name() string { return p.Log.API } // Run reads the file at the newest commit that changed it. func (p Plugin) Run(ctx context.Context, env plugin.Env) (plugin.Result, error) { l := p.Log - body, err := env.Get(ctx, l.CommitsURL()) + sha, err := github.LatestCommit(ctx, env.Get, l.CommitsURL()) if err != nil { - return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit: %w", l.API, err) + return plugin.Result{}, fmt.Errorf("looking up %s's newest changelog commit (%s in %s): %w", l.API, l.Path, l.Repo, err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return plugin.Result{}, fmt.Errorf("parsing github's commits response: %w", err) - } - if len(commits) == 0 || commits[0].SHA == "" { - return plugin.Result{}, fmt.Errorf("github lists no commit that changed %s in %s", l.Path, l.Repo) - } - sha := commits[0].SHA url := l.URL(sha) page, err := env.Get(ctx, url) if err != nil { diff --git a/plugins/apichangelog/apichangelog_test.go b/plugins/apichangelog/apichangelog_test.go index 21b1f04..21a0eea 100644 --- a/plugins/apichangelog/apichangelog_test.go +++ b/plugins/apichangelog/apichangelog_test.go @@ -7,8 +7,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) const ( diff --git a/plugins/catalog/catalog.go b/plugins/catalog/catalog.go index a89743e..50b1a62 100644 --- a/plugins/catalog/catalog.go +++ b/plugins/catalog/catalog.go @@ -22,8 +22,9 @@ import ( "sort" "time" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/github" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { @@ -154,20 +155,11 @@ func (p Plugin) Replay(ctx context.Context, env plugin.Env, from, to string) (pl // latestRef asks GitHub for the catalog repo's newest commit. func (p Plugin) latestRef(ctx context.Context, env plugin.Env) (string, error) { - body, err := env.Get(ctx, p.Catalog.RefsURL) + sha, err := github.Head(ctx, env.Get, p.Catalog.RefsURL) if err != nil { return "", fmt.Errorf("looking up the newest commit: %w", err) } - var commit struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commit); err != nil { - return "", fmt.Errorf("parsing the commit lookup: %w", err) - } - if commit.SHA == "" { - return "", fmt.Errorf("the commit lookup named no sha") - } - return commit.SHA, nil + return sha, nil } // events diffs two parsed snapshots into events. oldContent is empty on a diff --git a/plugins/catalog/catalog_test.go b/plugins/catalog/catalog_test.go index 5d22323..ad636b2 100644 --- a/plugins/catalog/catalog_test.go +++ b/plugins/catalog/catalog_test.go @@ -5,9 +5,9 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) // The two commits redis-doc's own history shows the removal happen between: diff --git a/plugins/catalog/registered_test.go b/plugins/catalog/registered_test.go index 6a078fa..66cb74d 100644 --- a/plugins/catalog/registered_test.go +++ b/plugins/catalog/registered_test.go @@ -3,7 +3,7 @@ package catalog import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/changelog/changelog.go b/plugins/changelog/changelog.go index 94a77ac..2d4b3a6 100644 --- a/plugins/changelog/changelog.go +++ b/plugins/changelog/changelog.go @@ -20,8 +20,8 @@ import ( "log" "strings" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { diff --git a/plugins/changelog/changelog_test.go b/plugins/changelog/changelog_test.go index 07a184e..eeb0491 100644 --- a/plugins/changelog/changelog_test.go +++ b/plugins/changelog/changelog_test.go @@ -4,7 +4,7 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // Two real changelogs at their release tags (testdata/README.md) in, every diff --git a/plugins/changelog/classify.go b/plugins/changelog/classify.go index 1343455..3b50675 100644 --- a/plugins/changelog/classify.go +++ b/plugins/changelog/classify.go @@ -6,7 +6,7 @@ import ( "slices" "strings" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // Kind is what a section (or a bullet's own prefix) says its changes are. diff --git a/plugins/changelog/registered_test.go b/plugins/changelog/registered_test.go index 424d6be..0a182c8 100644 --- a/plugins/changelog/registered_test.go +++ b/plugins/changelog/registered_test.go @@ -3,7 +3,7 @@ package changelog import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/eol/eol.go b/plugins/eol/eol.go index e6e415d..1d92cf7 100644 --- a/plugins/eol/eol.go +++ b/plugins/eol/eol.go @@ -31,10 +31,10 @@ import ( "strconv" "strings" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/fetch" - "github.com/patch-it-dev/patch-it-plugins/kit" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { diff --git a/plugins/eol/eol_test.go b/plugins/eol/eol_test.go index fbdf736..6ceac40 100644 --- a/plugins/eol/eol_test.go +++ b/plugins/eol/eol_test.go @@ -6,9 +6,9 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/feed/cloudflare_test.go b/plugins/feed/cloudflare_test.go index 9f56fe0..83d23fe 100644 --- a/plugins/feed/cloudflare_test.go +++ b/plugins/feed/cloudflare_test.go @@ -4,8 +4,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) const cloudflareFeed = "testdata/cloudflare-api-deprecations.rss.xml" diff --git a/plugins/feed/feed.go b/plugins/feed/feed.go index e5383a4..a0ad882 100644 --- a/plugins/feed/feed.go +++ b/plugins/feed/feed.go @@ -25,9 +25,9 @@ import ( "fmt" "log" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { diff --git a/plugins/feed/feed_test.go b/plugins/feed/feed_test.go index e361285..fe58a89 100644 --- a/plugins/feed/feed_test.go +++ b/plugins/feed/feed_test.go @@ -4,7 +4,7 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // The two feeds as saved on 2026-11-14 (testdata/README.md), each through the diff --git a/plugins/feed/readers.go b/plugins/feed/readers.go index d94baa2..b343708 100644 --- a/plugins/feed/readers.go +++ b/plugins/feed/readers.go @@ -6,7 +6,7 @@ import ( "strings" "time" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) // GitHubActions is the GitHub changelog's Actions label, RSS 2.0 (checked diff --git a/plugins/feed/registered_test.go b/plugins/feed/registered_test.go index e548423..83c9671 100644 --- a/plugins/feed/registered_test.go +++ b/plugins/feed/registered_test.go @@ -3,7 +3,7 @@ package feed import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/migrationguide/golden_test.go b/plugins/migrationguide/golden_test.go index 91c37be..84124b6 100644 --- a/plugins/migrationguide/golden_test.go +++ b/plugins/migrationguide/golden_test.go @@ -3,14 +3,14 @@ package migrationguide import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/sdkguide" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) // The guide at tag v1.0.0 (saved 2026-10-17) in, every event out. func TestGolden(t *testing.T) { got := kittest.Ingest(t, Plugin{Guide: sdkguide.AnthropicV1}, kittest.Pages{ - sdkguide.AnthropicV1.URL(): "../../sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", + sdkguide.AnthropicV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", }) kittest.Golden(t, "testdata/golden/anthropic-1.0.0.json", got) } diff --git a/plugins/migrationguide/migrationguide.go b/plugins/migrationguide/migrationguide.go index cf0da2f..6fbd950 100644 --- a/plugins/migrationguide/migrationguide.go +++ b/plugins/migrationguide/migrationguide.go @@ -8,9 +8,9 @@ import ( "context" "fmt" - "github.com/patch-it-dev/patch-it-plugins/migrate" - "github.com/patch-it-dev/patch-it-plugins/plugin" - "github.com/patch-it-dev/patch-it-plugins/sdkguide" + "github.com/patch-it-dev/patch-it-plugins/core/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) func init() { diff --git a/plugins/migrationguide/migrationguide_test.go b/plugins/migrationguide/migrationguide_test.go index ff2be52..d72a334 100644 --- a/plugins/migrationguide/migrationguide_test.go +++ b/plugins/migrationguide/migrationguide_test.go @@ -4,15 +4,15 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/sdkguide" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) func TestAMigrationGuideStoresOneEventPerRemovedParameter(t *testing.T) { // Only the v1.0.0 tag is saved: fetching anything else fails the test, and // kittest's second run (the tag never changes) must store nothing new. events := kittest.Ingest(t, Plugin{Guide: sdkguide.AnthropicV1}, kittest.Pages{ - sdkguide.AnthropicV1.URL(): "../../sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", + sdkguide.AnthropicV1.URL(): "sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md", }) var params []string for _, e := range events { diff --git a/plugins/migrationguide/registered_test.go b/plugins/migrationguide/registered_test.go index 4d07e5c..acd1ca5 100644 --- a/plugins/migrationguide/registered_test.go +++ b/plugins/migrationguide/registered_test.go @@ -3,8 +3,8 @@ package migrationguide import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/sdkguide" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/migrationguide/sdkguide/sdkguide.go b/plugins/migrationguide/sdkguide/sdkguide.go new file mode 100644 index 0000000..75170f5 --- /dev/null +++ b/plugins/migrationguide/sdkguide/sdkguide.go @@ -0,0 +1,174 @@ +// Package sdkguide reads an SDK's own migration guide for the request parameters +// a major release removed: a third kind of source, next to the OpenAPI differ and +// the deprecations pages. The guide is read at the release tag of the major it +// describes (`v1.0.0` for "Migrating to v1"), a URL that never changes, so it is +// its own provenance. +// +// The first is anthropic-sdk-python 1.0.0 (2026-08-20): its MIGRATION.md lists +// `temperature`, `top_p` and `top_k` as removed from `messages.create()` and its +// siblings, passing them is a `TypeError`, and it says what to do instead (checked +// 2026-10-17). A repo with `anthropic` unpinned gets 1.x on a fresh install. +package sdkguide + +import ( + "fmt" + "regexp" + "strings" + "time" + "unicode/utf8" + + "github.com/patch-it-dev/patch-it-plugins/core/event" +) + +// Guide is one SDK's migration guide for one major release. +type Guide struct { + API string // the SDK's slug in change events, e.g. "anthropic" + Repo string // its GitHub repository, owner/name + Major int // the release the guide describes: 1 for "Migrating to v1" + Operation string // the API operation the removed parameters were sent to + // Methods is what a table row's method cell must name for its parameters to + // count: the plain call, so a row about beta-only methods (where the same + // name can still be valid on a helper) isn't read as a removal. + Methods string + // Symbols are the calls the removed parameters can no longer be passed to, as + // code writes them after the import: the plain methods the guide's table names + // first (`messages.create()`, `messages.stream()`, `messages.parse()`). A v2 + // event carries them (the change event contract). + Symbols []string +} + +// AnthropicV1 is anthropic-sdk-python's guide to 1.0.0. +var AnthropicV1 = Guide{ + API: "anthropic", + Repo: "anthropics/anthropic-sdk-python", + Major: 1, + Operation: "POST /v1/messages", + Methods: "`messages.create()`", + Symbols: []string{"messages.create", "messages.stream", "messages.parse"}, +} + +// Version is the release that removed the parameters. +func (g Guide) Version() string { return fmt.Sprintf("%d.0.0", g.Major) } + +// URL is the guide as it was at that release's tag. +func (g Guide) URL() string { + return fmt.Sprintf("https://raw.githubusercontent.com/%s/v%s/MIGRATION.md", g.Repo, g.Version()) +} + +// Page is the same guide for a person to read. +func (g Guide) Page() string { + return fmt.Sprintf("https://github.com/%s/blob/v%s/MIGRATION.md", g.Repo, g.Version()) +} + +// Removal is one parameter the release removed, with what the guide says to do. +type Removal struct { + Param string + Instead string // the guide's "use instead" cell, as written + Excerpt string // the section heading, the table header and the row +} + +var ticked = regexp.MustCompile("`([^`]+)`") + +// Parse reads the guide's removed-parameter tables: every row whose method cell +// names g.Methods gives one Removal per backticked parameter. A guide for another +// major, or one with no such row, is an error, never zero removals. +func Parse(page []byte, g Guide) ([]Removal, error) { + text := strings.ReplaceAll(string(page), "\r\n", "\n") + if !strings.Contains(text, fmt.Sprintf("# Migrating to v%d", g.Major)) { + return nil, fmt.Errorf("not the guide to v%d", g.Major) + } + lines := strings.Split(text, "\n") + var out []Removal + heading := "" + for i := 0; i < len(lines); i++ { + line := strings.TrimSpace(lines[i]) + if strings.HasPrefix(line, "#") { + heading = line + continue + } + header := cells(line) + param, instead := column(header, "removed parameter"), column(header, "instead") + if param < 0 || instead < 0 { + continue + } + i++ // the |---| row + for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { + i++ + row := strings.TrimSpace(lines[i]) + c := cells(row) + if len(c) <= param || len(c) <= instead || !strings.Contains(c[0], g.Methods) { + continue + } + excerpt := cut(strings.Join([]string{heading, line, row}, "\n"), 2000) + for _, m := range ticked.FindAllStringSubmatch(c[param], -1) { + out = append(out, Removal{Param: m[1], Instead: c[instead], Excerpt: excerpt}) + } + } + } + if len(out) == 0 { + return nil, fmt.Errorf("no removed-parameter row naming %s: the guide's shape may have changed", g.Methods) + } + return out, nil +} + +func cells(row string) []string { + if !strings.HasPrefix(row, "|") { + return nil + } + parts := strings.Split(strings.Trim(row, "|"), "|") + for i := range parts { + parts[i] = strings.TrimSpace(parts[i]) + } + return parts +} + +func column(header []string, word string) int { + for i, h := range header { + if strings.Contains(strings.ToLower(h), word) { + return i + } + } + return -1 +} + +func cut(s string, n int) string { + if utf8.RuneCountInString(s) <= n { + return s + } + return string([]rune(s)[:n-1]) + "…" +} + +// Events turns removals into change events: one `breaking` request_parameter +// event per parameter, on the operation the SDK's methods send it to. +func Events(g Guide, rs []Removal, now time.Time) ([]event.ChangeEvent, []error) { + var events []event.ChangeEvent + var errs []error + for _, r := range rs { + affected := event.Affected{ + Kind: event.AffectedKindRequestParameter, + Side: event.SideRequest, + Operation: g.Operation, + Property: r.Param, + } + e := event.ChangeEvent{ + Fingerprint: event.Fingerprint(g.API, g.Version(), event.ChangeTypeBreaking, affected, "removed"), + API: g.API, + Version: g.Version(), + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Affected: affected, + Description: fmt.Sprintf("Parameter %s removed from %s and its sibling methods in the %s SDK %s: passing it raises a TypeError.", r.Param, g.Methods, g.API, g.Version()), + MigrationHint: fmt.Sprintf("%s Source: %s", r.Instead, g.Page()), + SourceURL: g.URL(), + SourceExcerpt: r.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + if err := e.Validate(); err != nil { + errs = append(errs, fmt.Errorf("%s %s: %w", g.API, r.Param, err)) + continue + } + events = append(events, e) + } + return events, errs +} diff --git a/sdkguide/sdkguide_test.go b/plugins/migrationguide/sdkguide/sdkguide_test.go similarity index 97% rename from sdkguide/sdkguide_test.go rename to plugins/migrationguide/sdkguide/sdkguide_test.go index 043b90d..d0c3fcb 100644 --- a/sdkguide/sdkguide_test.go +++ b/plugins/migrationguide/sdkguide/sdkguide_test.go @@ -6,7 +6,7 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) func guide(t *testing.T) []byte { diff --git a/sdkguide/testdata/README.md b/plugins/migrationguide/sdkguide/testdata/README.md similarity index 100% rename from sdkguide/testdata/README.md rename to plugins/migrationguide/sdkguide/testdata/README.md diff --git a/sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md b/plugins/migrationguide/sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md similarity index 100% rename from sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md rename to plugins/migrationguide/sdkguide/testdata/anthropic-MIGRATION-v1.0.0.md diff --git a/adapter/adapter.go b/plugins/openapi/adapter/adapter.go similarity index 100% rename from adapter/adapter.go rename to plugins/openapi/adapter/adapter.go diff --git a/adapter/algolia.go b/plugins/openapi/adapter/algolia.go similarity index 88% rename from adapter/algolia.go rename to plugins/openapi/adapter/algolia.go index dcb18d0..37a70d0 100644 --- a/adapter/algolia.go +++ b/plugins/openapi/adapter/algolia.go @@ -8,7 +8,8 @@ import ( "strings" "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" "gopkg.in/yaml.v3" ) @@ -42,7 +43,7 @@ var algoliaTag = regexp.MustCompile(`^released-(\d{4}-\d{2}-\d{2})(-[0-9a-f]+)?$ // have several releases (three on 2024-09-19) whose commit suffix says // nothing about their order, so those are told apart by their commit's date. func (a Algolia) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, algoliaRefsURL, githubHeaders()) + body, err := fetch.Get(ctx, algoliaRefsURL, github.Headers()) if err != nil { return "", fmt.Errorf("listing algolia's release tags: %w", err) } @@ -87,21 +88,11 @@ func (a Algolia) LatestTag(ctx context.Context) (string, error) { } func algoliaCommitDate(ctx context.Context, tag string) (time.Time, error) { - body, err := fetch.Get(ctx, fmt.Sprintf(algoliaCommitURL, tag), githubHeaders()) + _, date, err := github.Commit(ctx, github.Get, fmt.Sprintf(algoliaCommitURL, tag)) if err != nil { - return time.Time{}, fmt.Errorf("looking up algolia tag %s: %w", tag, err) + return time.Time{}, fmt.Errorf("algolia tag %s: no commit date: %w", tag, err) } - var c struct { - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(body, &c); err != nil || c.Commit.Committer.Date.IsZero() { - return time.Time{}, fmt.Errorf("algolia tag %s: no commit date", tag) - } - return c.Commit.Committer.Date, nil + return date, nil } // Fetch downloads the spec at tag and converts it from YAML to JSON, which is diff --git a/adapter/algolia_test.go b/plugins/openapi/adapter/algolia_test.go similarity index 100% rename from adapter/algolia_test.go rename to plugins/openapi/adapter/algolia_test.go diff --git a/adapter/appwrite.go b/plugins/openapi/adapter/appwrite.go similarity index 88% rename from adapter/appwrite.go rename to plugins/openapi/adapter/appwrite.go index 1243072..c458936 100644 --- a/adapter/appwrite.go +++ b/plugins/openapi/adapter/appwrite.go @@ -10,9 +10,9 @@ import ( "slices" "strconv" "strings" - "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) var ( @@ -68,20 +68,14 @@ func (a Appwrite) api(path string) string { // LatestTag is the newest commit on appwrite/specs' default branch that // changed specs/. func (a Appwrite) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, a.api("/commits?path=specs&per_page=1"), githubHeaders()) + sha, err := github.LatestCommit(ctx, github.Get, a.api("/commits?path=specs&per_page=1")) if err != nil { return "", fmt.Errorf("looking up appwrite's latest spec commit: %w", err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return "", fmt.Errorf("parsing github commits response: %w", err) - } - if len(commits) == 0 || !appwriteCommit.MatchString(commits[0].SHA) { + if !appwriteCommit.MatchString(sha) { return "", fmt.Errorf("github lists no commit that changed appwrite's specs") } - return commits[0].SHA, nil + return sha, nil } // Fetch downloads the spec at a commit: the newest minor's directory, or the @@ -102,23 +96,10 @@ func (a Appwrite) Fetch(ctx context.Context, tag string) (Spec, error) { if !appwriteCommit.MatchString(sha) || (named && !appwriteDir.MatchString(dir)) { return Spec{}, fmt.Errorf("%q is neither a full appwrite/specs commit sha nor .x@", tag) } - meta, err := fetch.Get(ctx, a.api("/commits/"+sha), githubHeaders()) + _, date, err := github.Commit(ctx, github.Get, a.api("/commits/"+sha)) if err != nil { return Spec{}, fmt.Errorf("looking up appwrite/specs commit %s: %w", sha, err) } - var commit struct { - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(meta, &commit); err != nil { - return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) - } - if commit.Commit.Committer.Date.IsZero() { - return Spec{}, fmt.Errorf("github commit %s has no date", sha) - } if dir == "" { dirs, err := a.list(ctx, "specs", sha) if err != nil { @@ -159,7 +140,7 @@ func (a Appwrite) Fetch(ctx context.Context, tag string) (Spec, error) { if err != nil { return Spec{}, fmt.Errorf("appwrite spec %s: %w", tag, err) } - return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil + return Spec{Content: content, Version: date.UTC().Format("2006-01-02"), SourceURL: url}, nil } // SourcePointer: see BasePathPointer. @@ -169,7 +150,7 @@ var _ Reshaper = Appwrite{} // list is the names in a directory of appwrite/specs at a commit. func (a Appwrite) list(ctx context.Context, path, sha string) ([]string, error) { - body, err := fetch.Get(ctx, a.api("/contents/"+path+"?ref="+sha), githubHeaders()) + body, err := fetch.Get(ctx, a.api("/contents/"+path+"?ref="+sha), github.Headers()) if err != nil { return nil, fmt.Errorf("listing appwrite/specs %s at %s: %w", path, sha, err) } diff --git a/adapter/appwrite_test.go b/plugins/openapi/adapter/appwrite_test.go similarity index 100% rename from adapter/appwrite_test.go rename to plugins/openapi/adapter/appwrite_test.go diff --git a/adapter/convex.go b/plugins/openapi/adapter/convex.go similarity index 76% rename from adapter/convex.go rename to plugins/openapi/adapter/convex.go index 31cc11c..fe0e020 100644 --- a/adapter/convex.go +++ b/plugins/openapi/adapter/convex.go @@ -4,9 +4,9 @@ import ( "context" "encoding/json" "fmt" - "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -41,20 +41,11 @@ func (Convex) API() string { return "convex" } // LatestTag is the SHA of the newest commit that changed the spec. func (Convex) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, convexCommitsURL, githubHeaders()) + sha, err := github.LatestCommit(ctx, github.Get, convexCommitsURL) if err != nil { return "", fmt.Errorf("looking up convex's latest spec commit: %w", err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return "", fmt.Errorf("parsing github commits response: %w", err) - } - if len(commits) == 0 || commits[0].SHA == "" { - return "", fmt.Errorf("github lists no commit that changed the convex spec") - } - return commits[0].SHA, nil + return sha, nil } // Fetch downloads the spec at commit sha. @@ -64,27 +55,16 @@ func (Convex) LatestTag(ctx context.Context) (string, error) { // every commit, checked 2026-11-19), so the date the spec changed is the // closest thing to "the API version the change arrived in". func (Convex) Fetch(ctx context.Context, sha string) (Spec, error) { - meta, err := fetch.Get(ctx, fmt.Sprintf(convexCommitURL, sha), githubHeaders()) + fullSHA, date, err := github.Commit(ctx, github.Get, fmt.Sprintf(convexCommitURL, sha)) if err != nil { return Spec{}, fmt.Errorf("looking up convex spec commit %s: %w", sha, err) } - var commit struct { - SHA string `json:"sha"` - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(meta, &commit); err != nil { - return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) - } - if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + if fullSHA == "" { return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) } // Pin to the full SHA even when given a short one: the citation must // name exactly one document. - url := fmt.Sprintf(convexSpecURLTemplate, commit.SHA) + url := fmt.Sprintf(convexSpecURLTemplate, fullSHA) body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth if err != nil { return Spec{}, fmt.Errorf("fetching convex spec %s: %w", sha, err) @@ -101,7 +81,7 @@ func (Convex) Fetch(ctx context.Context, sha string) (Spec, error) { if err != nil { return Spec{}, fmt.Errorf("convex spec %s: %w", sha, err) } - return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil + return Spec{Content: content, Version: date.UTC().Format("2006-01-02"), SourceURL: url}, nil } // SourcePointer: see BasePathPointer. diff --git a/adapter/convex_test.go b/plugins/openapi/adapter/convex_test.go similarity index 100% rename from adapter/convex_test.go rename to plugins/openapi/adapter/convex_test.go diff --git a/adapter/datadog.go b/plugins/openapi/adapter/datadog.go similarity index 86% rename from adapter/datadog.go rename to plugins/openapi/adapter/datadog.go index 573f429..8a5f9d3 100644 --- a/adapter/datadog.go +++ b/plugins/openapi/adapter/datadog.go @@ -5,7 +5,8 @@ import ( "encoding/json" "fmt" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" "gopkg.in/yaml.v3" ) @@ -33,20 +34,11 @@ func (Datadog) API() string { return "datadog" } // repo, so the client that's generated from it is the only thing that's // tagged. func (Datadog) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, datadogReleasesURL, githubHeaders()) + tag, err := github.LatestRelease(ctx, github.Get, datadogReleasesURL) if err != nil { return "", fmt.Errorf("looking up datadog's latest release: %w", err) } - var release struct { - TagName string `json:"tag_name"` - } - if err := json.Unmarshal(body, &release); err != nil { - return "", fmt.Errorf("parsing github release response: %w", err) - } - if release.TagName == "" { - return "", fmt.Errorf("github release response had no tag_name") - } - return release.TagName, nil + return tag, nil } // Fetch downloads the spec pinned to tag and converts it from YAML to JSON, diff --git a/adapter/datadog_test.go b/plugins/openapi/adapter/datadog_test.go similarity index 100% rename from adapter/datadog_test.go rename to plugins/openapi/adapter/datadog_test.go diff --git a/adapter/elasticsearch.go b/plugins/openapi/adapter/elasticsearch.go similarity index 89% rename from adapter/elasticsearch.go rename to plugins/openapi/adapter/elasticsearch.go index 9a7c36f..e14b571 100644 --- a/adapter/elasticsearch.go +++ b/plugins/openapi/adapter/elasticsearch.go @@ -8,7 +8,8 @@ import ( "strconv" "strings" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -48,7 +49,7 @@ var ( // 2026-11-19, when the newest release was 9.5.6), whose spec can still // change before it ships. func (Elasticsearch) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, esReleasesURL, githubHeaders()) + body, err := fetch.Get(ctx, esReleasesURL, github.Headers()) if err != nil { return "", fmt.Errorf("listing elasticsearch releases: %w", err) } @@ -75,7 +76,7 @@ func (Elasticsearch) LatestTag(ctx context.Context) (string, error) { return "", fmt.Errorf("github lists no elasticsearch release") } - body, err = fetch.Get(ctx, esBranchesURL, githubHeaders()) + body, err = fetch.Get(ctx, esBranchesURL, github.Headers()) if err != nil { return "", fmt.Errorf("listing elasticsearch-specification branches: %w", err) } @@ -109,17 +110,11 @@ func (Elasticsearch) Fetch(ctx context.Context, branch string) (Spec, error) { if !esBranch.MatchString(branch) { return Spec{}, fmt.Errorf("%q isn't an elasticsearch-specification minor branch", branch) } - meta, err := fetch.Get(ctx, fmt.Sprintf(esCommitURL, branch), githubHeaders()) + sha, err := github.Head(ctx, github.Get, fmt.Sprintf(esCommitURL, branch)) if err != nil { return Spec{}, fmt.Errorf("looking up the head of elasticsearch-specification %s: %w", branch, err) } - var commit struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(meta, &commit); err != nil || commit.SHA == "" { - return Spec{}, fmt.Errorf("elasticsearch-specification %s: no head commit", branch) - } - url := fmt.Sprintf(esSpecURLTemplate, commit.SHA) + url := fmt.Sprintf(esSpecURLTemplate, sha) body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth if err != nil { return Spec{}, fmt.Errorf("fetching the elasticsearch %s spec: %w", branch, err) diff --git a/adapter/elasticsearch_test.go b/plugins/openapi/adapter/elasticsearch_test.go similarity index 100% rename from adapter/elasticsearch_test.go rename to plugins/openapi/adapter/elasticsearch_test.go diff --git a/adapter/flagsmith.go b/plugins/openapi/adapter/flagsmith.go similarity index 87% rename from adapter/flagsmith.go rename to plugins/openapi/adapter/flagsmith.go index b491d8e..1c5c182 100644 --- a/adapter/flagsmith.go +++ b/plugins/openapi/adapter/flagsmith.go @@ -6,7 +6,8 @@ import ( "fmt" "strings" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" "gopkg.in/yaml.v3" ) @@ -38,20 +39,11 @@ func (Flagsmith) API() string { return "flagsmith" } // Flagsmith tags a release on (almost) every merge to main via release-please, // so releases/latest is always close to HEAD. func (Flagsmith) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, flagsmithReleasesURL, githubHeaders()) + tag, err := github.LatestRelease(ctx, github.Get, flagsmithReleasesURL) if err != nil { return "", fmt.Errorf("looking up flagsmith's latest release: %w", err) } - var release struct { - TagName string `json:"tag_name"` - } - if err := json.Unmarshal(body, &release); err != nil { - return "", fmt.Errorf("parsing github release response: %w", err) - } - if release.TagName == "" { - return "", fmt.Errorf("github release response had no tag_name") - } - return release.TagName, nil + return tag, nil } // Fetch downloads the spec pinned to tag and converts it from YAML to JSON, diff --git a/adapter/github.go b/plugins/openapi/adapter/github.go similarity index 94% rename from adapter/github.go rename to plugins/openapi/adapter/github.go index f0fc108..f8c29f6 100644 --- a/adapter/github.go +++ b/plugins/openapi/adapter/github.go @@ -6,7 +6,8 @@ import ( "fmt" "sort" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -38,7 +39,7 @@ func (GitHub) API() string { return "github" } // GitHub returns the list newest-first, but that isn't documented, so this // doesn't rely on it. func (GitHub) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, githubVersionsURL, githubHeaders()) + body, err := fetch.Get(ctx, githubVersionsURL, github.Headers()) if err != nil { return "", fmt.Errorf("looking up github's supported api versions: %w", err) } diff --git a/adapter/github_test.go b/plugins/openapi/adapter/github_test.go similarity index 100% rename from adapter/github_test.go rename to plugins/openapi/adapter/github_test.go diff --git a/adapter/gitlab.go b/plugins/openapi/adapter/gitlab.go similarity index 99% rename from adapter/gitlab.go rename to plugins/openapi/adapter/gitlab.go index 54ec41f..b3ebb94 100644 --- a/adapter/gitlab.go +++ b/plugins/openapi/adapter/gitlab.go @@ -10,7 +10,7 @@ import ( "strconv" "strings" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" "gopkg.in/yaml.v3" ) diff --git a/adapter/gitlab_test.go b/plugins/openapi/adapter/gitlab_test.go similarity index 100% rename from adapter/gitlab_test.go rename to plugins/openapi/adapter/gitlab_test.go diff --git a/adapter/neon.go b/plugins/openapi/adapter/neon.go similarity index 74% rename from adapter/neon.go rename to plugins/openapi/adapter/neon.go index 920b3a2..b767b2b 100644 --- a/adapter/neon.go +++ b/plugins/openapi/adapter/neon.go @@ -4,9 +4,9 @@ import ( "context" "encoding/json" "fmt" - "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -36,20 +36,11 @@ func (Neon) API() string { return "neon" } // LatestTag is the SHA of the newest commit that changed the spec. func (Neon) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, neonCommitsURL, githubHeaders()) + sha, err := github.LatestCommit(ctx, github.Get, neonCommitsURL) if err != nil { return "", fmt.Errorf("looking up neon's latest spec commit: %w", err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return "", fmt.Errorf("parsing github commits response: %w", err) - } - if len(commits) == 0 || commits[0].SHA == "" { - return "", fmt.Errorf("github lists no commit that changed the neon spec") - } - return commits[0].SHA, nil + return sha, nil } // Fetch downloads the spec at commit sha and moves the server URL's path into @@ -60,27 +51,16 @@ func (Neon) LatestTag(ctx context.Context) (string, error) { // 2026-11-19), so the date the spec changed is the closest thing to "the API // version the change arrived in". func (Neon) Fetch(ctx context.Context, sha string) (Spec, error) { - meta, err := fetch.Get(ctx, fmt.Sprintf(neonCommitURL, sha), githubHeaders()) + fullSHA, date, err := github.Commit(ctx, github.Get, fmt.Sprintf(neonCommitURL, sha)) if err != nil { return Spec{}, fmt.Errorf("looking up neon spec commit %s: %w", sha, err) } - var commit struct { - SHA string `json:"sha"` - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(meta, &commit); err != nil { - return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) - } - if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + if fullSHA == "" { return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) } // Pin to the full SHA even when given a short one: the citation must // name exactly one document. - url := fmt.Sprintf(neonSpecURLTemplate, commit.SHA) + url := fmt.Sprintf(neonSpecURLTemplate, fullSHA) body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth if err != nil { return Spec{}, fmt.Errorf("fetching neon spec %s: %w", sha, err) @@ -97,7 +77,7 @@ func (Neon) Fetch(ctx context.Context, sha string) (Spec, error) { if err != nil { return Spec{}, fmt.Errorf("neon spec %s: %w", sha, err) } - return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil + return Spec{Content: content, Version: date.UTC().Format("2006-01-02"), SourceURL: url}, nil } // SourcePointer: see BasePathPointer. diff --git a/adapter/neon_test.go b/plugins/openapi/adapter/neon_test.go similarity index 100% rename from adapter/neon_test.go rename to plugins/openapi/adapter/neon_test.go diff --git a/adapter/planetscale.go b/plugins/openapi/adapter/planetscale.go similarity index 77% rename from adapter/planetscale.go rename to plugins/openapi/adapter/planetscale.go index cb245ee..5c83d61 100644 --- a/adapter/planetscale.go +++ b/plugins/openapi/adapter/planetscale.go @@ -5,9 +5,9 @@ import ( "context" "encoding/json" "fmt" - "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" "gopkg.in/yaml.v3" ) @@ -42,20 +42,11 @@ func (p PlanetScale) api(path string) string { // LatestTag is the SHA of the newest commit that changed the spec. func (p PlanetScale) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, p.api("/commits?path="+planetscaleSpecPath+"&per_page=1"), githubHeaders()) + sha, err := github.LatestCommit(ctx, github.Get, p.api("/commits?path="+planetscaleSpecPath+"&per_page=1")) if err != nil { return "", fmt.Errorf("looking up planetscale's latest spec commit: %w", err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return "", fmt.Errorf("parsing github commits response: %w", err) - } - if len(commits) == 0 || commits[0].SHA == "" { - return "", fmt.Errorf("github lists no commit that changed the planetscale spec") - } - return commits[0].SHA, nil + return sha, nil } // Fetch downloads the spec at commit sha and converts it from YAML to JSON, @@ -73,27 +64,16 @@ func (p PlanetScale) LatestTag(ctx context.Context) (string, error) { // error. A file served 200 that has no paths (emptied, or a stub page like // "404: Not Found", which YAML reads as a one-key mapping) is refused here. func (p PlanetScale) Fetch(ctx context.Context, sha string) (Spec, error) { - meta, err := fetch.Get(ctx, p.api("/commits/"+sha), githubHeaders()) + fullSHA, date, err := github.Commit(ctx, github.Get, p.api("/commits/"+sha)) if err != nil { return Spec{}, fmt.Errorf("looking up planetscale spec commit %s: %w", sha, err) } - var commit struct { - SHA string `json:"sha"` - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(meta, &commit); err != nil { - return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) - } - if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + if fullSHA == "" { return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) } // Pin to the full SHA even when given a short one: the citation must // name exactly one document. - url := cmp.Or(p.RawBase, "https://raw.githubusercontent.com") + "/" + planetscaleRepo + "/" + commit.SHA + "/" + planetscaleSpecPath + url := cmp.Or(p.RawBase, "https://raw.githubusercontent.com") + "/" + planetscaleRepo + "/" + fullSHA + "/" + planetscaleSpecPath body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth if err != nil { return Spec{}, fmt.Errorf("fetching planetscale spec %s: %w", sha, err) @@ -117,7 +97,7 @@ func (p PlanetScale) Fetch(ctx context.Context, sha string) (Spec, error) { if content, err = ServerBasePath(content); err != nil { return Spec{}, fmt.Errorf("planetscale spec %s: %w", sha, err) } - return Spec{Content: content, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil + return Spec{Content: content, Version: date.UTC().Format("2006-01-02"), SourceURL: url}, nil } // SourcePointer: see BasePathPointer. diff --git a/adapter/planetscale_test.go b/plugins/openapi/adapter/planetscale_test.go similarity index 100% rename from adapter/planetscale_test.go rename to plugins/openapi/adapter/planetscale_test.go diff --git a/adapter/sentry.go b/plugins/openapi/adapter/sentry.go similarity index 97% rename from adapter/sentry.go rename to plugins/openapi/adapter/sentry.go index 1c4c97f..4b8bda6 100644 --- a/adapter/sentry.go +++ b/plugins/openapi/adapter/sentry.go @@ -12,7 +12,8 @@ import ( "strings" "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // sentryAsset is the spec's file name in both places it's published: @@ -64,7 +65,7 @@ func (s Sentry) api(path string) string { // "scraps@0.5.0"). GitHub lists releases in an order that isn't version // order, so the newest is computed from the version. func (s Sentry) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, s.api("/repos/getsentry/sentry/releases?per_page=100"), githubHeaders()) + body, err := fetch.Get(ctx, s.api("/repos/getsentry/sentry/releases?per_page=100"), github.Headers()) if err != nil { return "", fmt.Errorf("listing sentry releases: %w", err) } @@ -148,7 +149,7 @@ func (s Sentry) Fetch(ctx context.Context, tag string) (Spec, error) { } url, date = raw, r.PublishedAt case sentrySchemaCommit.MatchString(tag): - meta, err := fetch.Get(ctx, s.api("/repos/getsentry/sentry-api-schema/commits/"+tag), githubHeaders()) + meta, err := fetch.Get(ctx, s.api("/repos/getsentry/sentry-api-schema/commits/"+tag), github.Headers()) if err != nil { return Spec{}, fmt.Errorf("looking up sentry-api-schema commit %s: %w", tag, err) } @@ -181,7 +182,7 @@ func (s Sentry) Fetch(ctx context.Context, tag string) (Spec, error) { } func sentryReleaseMeta(ctx context.Context, url, tag string) (sentryReleaseInfo, error) { - meta, err := fetch.Get(ctx, url, githubHeaders()) + meta, err := fetch.Get(ctx, url, github.Headers()) if err != nil { return sentryReleaseInfo{}, fmt.Errorf("looking up sentry release %s: %w", tag, err) } diff --git a/adapter/sentry_test.go b/plugins/openapi/adapter/sentry_test.go similarity index 100% rename from adapter/sentry_test.go rename to plugins/openapi/adapter/sentry_test.go diff --git a/adapter/stripe.go b/plugins/openapi/adapter/stripe.go similarity index 76% rename from adapter/stripe.go rename to plugins/openapi/adapter/stripe.go index 869053e..171f736 100644 --- a/adapter/stripe.go +++ b/plugins/openapi/adapter/stripe.go @@ -6,9 +6,9 @@ import ( "errors" "fmt" "net/http" - "os" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -33,21 +33,11 @@ func (Stripe) API() string { return "stripe" } // LatestTag asks GitHub for Stripe's newest openapi release tag, e.g. "v2468". func (Stripe) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, stripeReleasesURL, githubHeaders()) + tag, err := github.LatestRelease(ctx, github.Get, stripeReleasesURL) if err != nil { return "", fmt.Errorf("looking up stripe's latest release: %w", err) } - - var release struct { - TagName string `json:"tag_name"` - } - if err := json.Unmarshal(body, &release); err != nil { - return "", fmt.Errorf("parsing github release response: %w", err) - } - if release.TagName == "" { - return "", fmt.Errorf("github release response had no tag_name") - } - return release.TagName, nil + return tag, nil } // Fetch downloads the spec pinned to tag and reads its declared API version @@ -84,13 +74,3 @@ func (Stripe) Fetch(ctx context.Context, tag string) (Spec, error) { SourceURL: url, }, nil } - -// githubHeaders adds GITHUB_TOKEN as a bearer token when set, which raises -// the GitHub API's rate limit for looking up release tags. Never required. -func githubHeaders() map[string]string { - token := os.Getenv("GITHUB_TOKEN") - if token == "" { - return nil - } - return map[string]string{"Authorization": "Bearer " + token} -} diff --git a/adapter/stripe_test.go b/plugins/openapi/adapter/stripe_test.go similarity index 100% rename from adapter/stripe_test.go rename to plugins/openapi/adapter/stripe_test.go diff --git a/adapter/supabase.go b/plugins/openapi/adapter/supabase.go similarity index 69% rename from adapter/supabase.go rename to plugins/openapi/adapter/supabase.go index d6cb188..bd4ab86 100644 --- a/adapter/supabase.go +++ b/plugins/openapi/adapter/supabase.go @@ -4,9 +4,9 @@ import ( "context" "encoding/json" "fmt" - "time" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -35,20 +35,11 @@ func (Supabase) API() string { return "supabase" } // LatestTag is the SHA of the newest commit that changed the spec. func (Supabase) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, supabaseCommitsURL, githubHeaders()) + sha, err := github.LatestCommit(ctx, github.Get, supabaseCommitsURL) if err != nil { return "", fmt.Errorf("looking up supabase's latest spec commit: %w", err) } - var commits []struct { - SHA string `json:"sha"` - } - if err := json.Unmarshal(body, &commits); err != nil { - return "", fmt.Errorf("parsing github commits response: %w", err) - } - if len(commits) == 0 || commits[0].SHA == "" { - return "", fmt.Errorf("github lists no commit that changed the supabase spec") - } - return commits[0].SHA, nil + return sha, nil } // Fetch downloads the spec at commit sha. @@ -58,27 +49,16 @@ func (Supabase) LatestTag(ctx context.Context) (string, error) { // 2026-11-19), so the date the spec changed is the closest thing to "the API // version the change arrived in". func (Supabase) Fetch(ctx context.Context, sha string) (Spec, error) { - meta, err := fetch.Get(ctx, fmt.Sprintf(supabaseCommitURL, sha), githubHeaders()) + fullSHA, date, err := github.Commit(ctx, github.Get, fmt.Sprintf(supabaseCommitURL, sha)) if err != nil { return Spec{}, fmt.Errorf("looking up supabase spec commit %s: %w", sha, err) } - var commit struct { - SHA string `json:"sha"` - Commit struct { - Committer struct { - Date time.Time `json:"date"` - } `json:"committer"` - } `json:"commit"` - } - if err := json.Unmarshal(meta, &commit); err != nil { - return Spec{}, fmt.Errorf("parsing github commit %s: %w", sha, err) - } - if commit.SHA == "" || commit.Commit.Committer.Date.IsZero() { + if fullSHA == "" { return Spec{}, fmt.Errorf("github commit %s has no sha or date", sha) } // Pin to the full SHA even when given a short one: the citation must // name exactly one document. - url := fmt.Sprintf(supabaseSpecURLTemplate, commit.SHA) + url := fmt.Sprintf(supabaseSpecURLTemplate, fullSHA) body, err := fetch.Get(ctx, url, nil) // raw.githubusercontent.com needs no auth if err != nil { return Spec{}, fmt.Errorf("fetching supabase spec %s: %w", sha, err) @@ -86,5 +66,5 @@ func (Supabase) Fetch(ctx context.Context, sha string) (Spec, error) { if !json.Valid(body) { return Spec{}, fmt.Errorf("supabase spec %s is not valid json", sha) } - return Spec{Content: body, Version: commit.Commit.Committer.Date.UTC().Format("2006-01-02"), SourceURL: url}, nil + return Spec{Content: body, Version: date.UTC().Format("2006-01-02"), SourceURL: url}, nil } diff --git a/adapter/supabase_test.go b/plugins/openapi/adapter/supabase_test.go similarity index 100% rename from adapter/supabase_test.go rename to plugins/openapi/adapter/supabase_test.go diff --git a/adapter/vercel.go b/plugins/openapi/adapter/vercel.go similarity index 83% rename from adapter/vercel.go rename to plugins/openapi/adapter/vercel.go index 97dfbaa..ae0d5e1 100644 --- a/adapter/vercel.go +++ b/plugins/openapi/adapter/vercel.go @@ -6,7 +6,8 @@ import ( "fmt" "strings" - "github.com/patch-it-dev/patch-it-plugins/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/fetch" + "github.com/patch-it-dev/patch-it-plugins/core/github" ) // Variables, not constants, only so tests can point them at a local server. @@ -32,20 +33,11 @@ func (Vercel) API() string { return "vercel" } // The canary tags (v14.0.0-canary.9) aren't releases, so releases/latest never // returns them (checked 2026-11-18). func (Vercel) LatestTag(ctx context.Context) (string, error) { - body, err := fetch.Get(ctx, vercelReleasesURL, githubHeaders()) + tag, err := github.LatestRelease(ctx, github.Get, vercelReleasesURL) if err != nil { return "", fmt.Errorf("looking up vercel's latest release: %w", err) } - var release struct { - TagName string `json:"tag_name"` - } - if err := json.Unmarshal(body, &release); err != nil { - return "", fmt.Errorf("parsing github release response: %w", err) - } - if release.TagName == "" { - return "", fmt.Errorf("github release response had no tag_name") - } - return release.TagName, nil + return tag, nil } // Fetch downloads the spec pinned to tag. It's JSON already, so it's passed diff --git a/adapter/vercel_test.go b/plugins/openapi/adapter/vercel_test.go similarity index 100% rename from adapter/vercel_test.go rename to plugins/openapi/adapter/vercel_test.go diff --git a/plugins/openapi/algolia.go b/plugins/openapi/algolia.go index 2e1503f..9362faa 100644 --- a/plugins/openapi/algolia.go +++ b/plugins/openapi/algolia.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // algoliaDiff reads Algolia's specs like Supabase's: deprecations by the // `deprecated` flag, quoting the whole operation, and path templates matched. diff --git a/plugins/openapi/algolia_test.go b/plugins/openapi/algolia_test.go index 7635650..6689e85 100644 --- a/plugins/openapi/algolia_test.go +++ b/plugins/openapi/algolia_test.go @@ -8,10 +8,10 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" "gopkg.in/yaml.v3" ) diff --git a/plugins/openapi/appwrite.go b/plugins/openapi/appwrite.go index 0b81d0d..7055d9f 100644 --- a/plugins/openapi/appwrite.go +++ b/plugins/openapi/appwrite.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // appwriteDiff is how Appwrite's spec says what it says: // diff --git a/plugins/openapi/appwrite_test.go b/plugins/openapi/appwrite_test.go index a4bf6f3..04f84cc 100644 --- a/plugins/openapi/appwrite_test.go +++ b/plugins/openapi/appwrite_test.go @@ -9,10 +9,10 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // The appwrite/specs commits the tests read (checked 2026-11-19), and their diff --git a/plugins/openapi/convex.go b/plugins/openapi/convex.go index e57101e..3a52769 100644 --- a/plugins/openapi/convex.go +++ b/plugins/openapi/convex.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // convexDiff is how the Convex Deployment API spec says what it says: // diff --git a/plugins/openapi/convex_test.go b/plugins/openapi/convex_test.go index 4d81e48..21c7613 100644 --- a/plugins/openapi/convex_test.go +++ b/plugins/openapi/convex_test.go @@ -7,9 +7,9 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // convexCommits are the spec commits saved under testdata/ (trimmed to the diff --git a/plugins/openapi/datadog_test.go b/plugins/openapi/datadog_test.go index fcc1ea6..908ba5c 100644 --- a/plugins/openapi/datadog_test.go +++ b/plugins/openapi/datadog_test.go @@ -7,7 +7,7 @@ import ( "os" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" "gopkg.in/yaml.v3" ) diff --git a/plugins/openapi/elasticsearch.go b/plugins/openapi/elasticsearch.go index 1f43b2b..c8c9090 100644 --- a/plugins/openapi/elasticsearch.go +++ b/plugins/openapi/elasticsearch.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // elasticsearchDiff reads Elastic's spec like Supabase's: deprecations by the // `deprecated` flag, quoting the whole operation, and path templates matched. diff --git a/plugins/openapi/elasticsearch_test.go b/plugins/openapi/elasticsearch_test.go index 0a57679..402ad23 100644 --- a/plugins/openapi/elasticsearch_test.go +++ b/plugins/openapi/elasticsearch_test.go @@ -7,9 +7,9 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // esHeads are the elasticsearch-specification branch heads saved under diff --git a/plugins/openapi/flagsmith_test.go b/plugins/openapi/flagsmith_test.go index 3cce606..eaea1df 100644 --- a/plugins/openapi/flagsmith_test.go +++ b/plugins/openapi/flagsmith_test.go @@ -8,8 +8,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" "gopkg.in/yaml.v3" ) diff --git a/plugins/openapi/github_test.go b/plugins/openapi/github_test.go index 6ff7d86..4496f7a 100644 --- a/plugins/openapi/github_test.go +++ b/plugins/openapi/github_test.go @@ -6,7 +6,7 @@ import ( "os" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // fakeGitHubAdapter serves the real, trimmed spec excerpts saved under diff --git a/plugins/openapi/gitlab_test.go b/plugins/openapi/gitlab_test.go index a79dca4..a61851f 100644 --- a/plugins/openapi/gitlab_test.go +++ b/plugins/openapi/gitlab_test.go @@ -10,7 +10,7 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" "gopkg.in/yaml.v3" ) diff --git a/plugins/openapi/neon.go b/plugins/openapi/neon.go index 41a70ee..3facc5b 100644 --- a/plugins/openapi/neon.go +++ b/plugins/openapi/neon.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // neonDiff is how the Neon API spec says what it says: // diff --git a/plugins/openapi/neon_test.go b/plugins/openapi/neon_test.go index 8a5c483..ac726f6 100644 --- a/plugins/openapi/neon_test.go +++ b/plugins/openapi/neon_test.go @@ -10,9 +10,9 @@ import ( "gopkg.in/yaml.v3" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // neonCommits are the spec commits saved under testdata/ (trimmed to the diff --git a/plugins/openapi/openapi.go b/plugins/openapi/openapi.go index 3d943d6..0428719 100644 --- a/plugins/openapi/openapi.go +++ b/plugins/openapi/openapi.go @@ -11,13 +11,13 @@ import ( "fmt" "log" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/hint" - "github.com/patch-it-dev/patch-it-plugins/migrate" - "github.com/patch-it-dev/patch-it-plugins/normalize" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/hint" + "github.com/patch-it-dev/patch-it-plugins/core/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/normalize" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) func init() { diff --git a/plugins/openapi/openapi_test.go b/plugins/openapi/openapi_test.go index 4f05499..d76c60c 100644 --- a/plugins/openapi/openapi_test.go +++ b/plugins/openapi/openapi_test.go @@ -6,11 +6,11 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/hint" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/hint" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // fakeHints stands in for a changelog: an index built from the entries given, diff --git a/plugins/openapi/planetscale.go b/plugins/openapi/planetscale.go index a922223..7531942 100644 --- a/plugins/openapi/planetscale.go +++ b/plugins/openapi/planetscale.go @@ -3,7 +3,7 @@ package openapi import ( "regexp" - "github.com/patch-it-dev/patch-it-plugins/diff" + "github.com/patch-it-dev/patch-it-plugins/core/diff" ) // planetscaleDiff is how the PlanetScale API spec says what it says: diff --git a/plugins/openapi/planetscale_test.go b/plugins/openapi/planetscale_test.go index 5cf0b0f..ecf51f3 100644 --- a/plugins/openapi/planetscale_test.go +++ b/plugins/openapi/planetscale_test.go @@ -9,10 +9,10 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // planetscaleCommits are the planetscale/terraform-provider-planetscale diff --git a/plugins/openapi/registered_test.go b/plugins/openapi/registered_test.go index faa4a3d..489b0c1 100644 --- a/plugins/openapi/registered_test.go +++ b/plugins/openapi/registered_test.go @@ -3,8 +3,8 @@ package openapi import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/openapi/sentry.go b/plugins/openapi/sentry.go index a702fd5..dc0fa5a 100644 --- a/plugins/openapi/sentry.go +++ b/plugins/openapi/sentry.go @@ -3,7 +3,7 @@ package openapi import ( "regexp" - "github.com/patch-it-dev/patch-it-plugins/diff" + "github.com/patch-it-dev/patch-it-plugins/core/diff" ) // sentryDiff is how Sentry's spec says what it says: diff --git a/plugins/openapi/sentry_test.go b/plugins/openapi/sentry_test.go index 03b69c8..c435b28 100644 --- a/plugins/openapi/sentry_test.go +++ b/plugins/openapi/sentry_test.go @@ -11,10 +11,10 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/diff" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/diff" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // The getsentry/sentry-api-schema commits and release tags saved under diff --git a/plugins/openapi/supabase.go b/plugins/openapi/supabase.go index 840261f..20d4f3a 100644 --- a/plugins/openapi/supabase.go +++ b/plugins/openapi/supabase.go @@ -1,6 +1,6 @@ package openapi -import "github.com/patch-it-dev/patch-it-plugins/diff" +import "github.com/patch-it-dev/patch-it-plugins/core/diff" // supabaseDiff is how the Supabase Management API spec says what it says: // diff --git a/plugins/openapi/supabase_test.go b/plugins/openapi/supabase_test.go index b6c549f..a9ae173 100644 --- a/plugins/openapi/supabase_test.go +++ b/plugins/openapi/supabase_test.go @@ -7,9 +7,9 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // supabaseCommits are the spec commits saved under testdata/ (trimmed to the diff --git a/plugins/openapi/vercel.go b/plugins/openapi/vercel.go index 0c50690..191be09 100644 --- a/plugins/openapi/vercel.go +++ b/plugins/openapi/vercel.go @@ -3,7 +3,7 @@ package openapi import ( "regexp" - "github.com/patch-it-dev/patch-it-plugins/diff" + "github.com/patch-it-dev/patch-it-plugins/core/diff" ) // vercelDiff is how Vercel's spec says what it says: diff --git a/plugins/openapi/vercel_test.go b/plugins/openapi/vercel_test.go index 6d0ebed..f7afeae 100644 --- a/plugins/openapi/vercel_test.go +++ b/plugins/openapi/vercel_test.go @@ -10,10 +10,10 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/adapter" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/openapi/adapter" ) // fakeVercelAdapter serves the trimmed, unedited excerpts of vercel/sdk's @@ -219,9 +219,9 @@ func TestVercelDeprecatedSummary(t *testing.T) { "Deprecated: Use DELETE /v1/drives/:name. Requires ...": true, "Deprecated: true. Update Resource Secrets (Deprecated)": true, "Get a list of deprecated Node.js versions": false, - "Undeprecated thing": false, - "Deprecated runtimes for a project": false, - "Update a project (deprecated fields are ignored)": false, + "Undeprecated thing": false, + "Deprecated runtimes for a project": false, + "Update a project (deprecated fields are ignored)": false, "": false, } { if got := vercelDeprecatedSummary(summary); got != want { diff --git a/plugins/removedmembers/golden_test.go b/plugins/removedmembers/golden_test.go index dd6bd52..ac62dbd 100644 --- a/plugins/removedmembers/golden_test.go +++ b/plugins/removedmembers/golden_test.go @@ -3,7 +3,7 @@ package removedmembers import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // The guide at tag v2.0.0 (saved 2026-11-04) in, every event out. diff --git a/plugins/removedmembers/newrelic_test.go b/plugins/removedmembers/newrelic_test.go index 9102714..220052b 100644 --- a/plugins/removedmembers/newrelic_test.go +++ b/plugins/removedmembers/newrelic_test.go @@ -7,8 +7,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // An excerpt of the release note at commit f0b4f817 (fetched 2026-11-19): the diff --git a/plugins/removedmembers/posthog_test.go b/plugins/removedmembers/posthog_test.go index cccf046..8b7d70a 100644 --- a/plugins/removedmembers/posthog_test.go +++ b/plugins/removedmembers/posthog_test.go @@ -5,8 +5,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // The guide as published at tag posthog-v8.0.0 (fetched 2026-11-19), whole. diff --git a/plugins/removedmembers/registered_test.go b/plugins/removedmembers/registered_test.go index b0b7a81..20af0b9 100644 --- a/plugins/removedmembers/registered_test.go +++ b/plugins/removedmembers/registered_test.go @@ -3,7 +3,7 @@ package removedmembers import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) func TestRegistersItself(t *testing.T) { diff --git a/plugins/removedmembers/removedmembers.go b/plugins/removedmembers/removedmembers.go index 5dc6ccb..c60b49a 100644 --- a/plugins/removedmembers/removedmembers.go +++ b/plugins/removedmembers/removedmembers.go @@ -27,8 +27,8 @@ import ( "slices" "strings" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/plugin" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" ) func init() { diff --git a/plugins/removedmembers/removedmembers_test.go b/plugins/removedmembers/removedmembers_test.go index 8a23c8f..afab21b 100644 --- a/plugins/removedmembers/removedmembers_test.go +++ b/plugins/removedmembers/removedmembers_test.go @@ -4,8 +4,8 @@ import ( "strings" "testing" - "github.com/patch-it-dev/patch-it-plugins/event" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/event" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" ) // The guide as published at tag v2.0.0 (fetched 2026-11-04). diff --git a/plugins/retirements/golden_test.go b/plugins/retirements/golden_test.go index b4c3a51..b4095c9 100644 --- a/plugins/retirements/golden_test.go +++ b/plugins/retirements/golden_test.go @@ -3,8 +3,8 @@ package retirements import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/retire" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" ) // Both providers' saved pages (2026-10-13) in, every event out. The archive @@ -16,7 +16,7 @@ func TestGolden(t *testing.T) { "anthropic-deprecations.md": retire.Anthropic, } { t.Run(page.API, func(t *testing.T) { - saved := kittest.Pages{page.URL: "../../retire/testdata/" + file} + saved := kittest.Pages{page.URL: "retire/testdata/" + file} archive := &kittest.Archive{T: t, Pages: saved} got := kittest.IngestWith(t, kittest.Env(t, saved), Plugin{Page: page, Archiver: archive}) if archive.Calls != 1 { diff --git a/plugins/retirements/registered_test.go b/plugins/retirements/registered_test.go index a123690..c5be64c 100644 --- a/plugins/retirements/registered_test.go +++ b/plugins/retirements/registered_test.go @@ -3,8 +3,8 @@ package retirements import ( "testing" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/retire" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" ) func TestRegistersItself(t *testing.T) { diff --git a/retire/providers.go b/plugins/retirements/retire/providers.go similarity index 100% rename from retire/providers.go rename to plugins/retirements/retire/providers.go diff --git a/plugins/retirements/retire/retire.go b/plugins/retirements/retire/retire.go new file mode 100644 index 0000000..1c3d673 --- /dev/null +++ b/plugins/retirements/retire/retire.go @@ -0,0 +1,245 @@ +// Package retire reads a model provider's deprecations page and turns every +// retired model into change events: a second kind of source next to the +// OpenAPI differ. There is no spec to diff, only the provider's own table of +// shutdown date, model and named replacement, so this reads the table. +// +// Both providers serve the page as markdown at its URL plus ".md" (checked +// 2026-10-13), and both write each announcement as a table whose first column +// is the date the model stops working. The event cites a Wayback Machine +// snapshot of that markdown (kit/), never the live page: the contract +// requires a source that can't change under the event. +package retire + +import ( + "fmt" + "regexp" + "strings" + "time" + + "github.com/patch-it-dev/patch-it-plugins/core/event" +) + +// Page is one provider's deprecations page and what its models are sent to. +type Page struct { + API string // the api slug the events carry, e.g. "openai-models" + Vendor string // for sentences: "OpenAI" + URL string // the page as markdown + Operation string // the provider's main call that takes a model name + // Keep says whether a model name belongs to this source: the operations + // above take text models, not image, audio or embedding ones. + Keep func(name string) bool +} + +// Retirement is one model name the provider stops serving on Date, with the +// replacement it names. An alias gets its own Retirement, with the row it +// came from. +type Retirement struct { + Model string + Date string // YYYY-MM-DD + Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") + Via []string + Excerpt string // the section heading, the table header and the row +} + +var ( + dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) + ticked = regexp.MustCompile("`([^`]+)`") +) + +var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} + +// Parse reads every retirement table on the page. A model listed more than +// once keeps its first row: both pages list the most recent announcement +// first, and a later one supersedes an earlier date, including a later row +// that withdraws the date ("To be announced"). A replacement that is +// itself retired is followed to the model that replaces it, so a hint never +// points at a model that no longer works. +func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { + lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") + var out []Retirement + seen := map[string]bool{} + heading := "" + for i := 0; i < len(lines); i++ { + line := strings.TrimSpace(lines[i]) + if strings.HasPrefix(line, "#") { + heading = line + continue + } + header := cells(line) + if len(header) < 3 || !dateHeader.MatchString(header[0]) { + continue + } + model, repl := column(header, "model"), column(header, "replacement", "substitute") + if model < 0 || repl < 0 { + continue // an endpoint ("System") or a training-price table: no model to replace + } + i++ // the |---| row + for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { + i++ + row := strings.TrimSpace(lines[i]) + c := cells(row) + if len(c) <= model || len(c) <= repl { + return nil, fmt.Errorf("a short row under %q: %s", heading, row) + } + names := ticked.FindAllStringSubmatch(c[model], -1) + date, err := parseDate(c[0]) + if err != nil { + // "To be announced": not a retirement yet, and the newer word on + // these names, so an older row's date for them doesn't count. + for _, m := range names { + seen[m[1]] = true + } + continue + } + excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") + for _, m := range names { + name := m[1] + if seen[name] || !keep(name) { + continue + } + seen[name] = true + out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) + } + } + } + if len(out) == 0 { + return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") + } + follow(out) + return out, nil +} + +// headerLine walks back from a row to its table's header. +func headerLine(lines []string, i int) int { + for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { + i-- + } + return i +} + +// follow replaces a replacement that is itself retired with its own +// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is +// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. +func follow(rs []Retirement) { + by := map[string]Retirement{} + for _, r := range rs { + by[r.Model] = r + } + for i := range rs { + for hops := 0; hops < 10; hops++ { + next, ok := by[First(rs[i].Replacement)] + if !ok || next.Model == rs[i].Model { + break + } + rs[i].Via = append(rs[i].Via, next.Model) + rs[i].Replacement = next.Replacement + } + } +} + +// First is the first model name a replacement cell gives, "" when it names +// none ("The most capable cyber model available to you."). +func First(replacement string) string { + if m := ticked.FindStringSubmatch(replacement); m != nil { + return m[1] + } + return "" +} + +// cells splits a markdown table row on its unescaped pipes. A cell can hold +// an escaped one: "`gpt-4-0613` \| `gpt-4`". +func cells(row string) []string { + if !strings.HasPrefix(row, "|") { + return nil + } + row = strings.Trim(row, "|") + var out []string + var cur strings.Builder + for i := 0; i < len(row); i++ { + if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { + cur.WriteString(`\|`) + i++ + continue + } + if row[i] == '|' { + out = append(out, strings.TrimSpace(cur.String())) + cur.Reset() + continue + } + cur.WriteByte(row[i]) + } + return append(out, strings.TrimSpace(cur.String())) +} + +func column(header []string, words ...string) int { + for i, h := range header { + for _, w := range words { + if strings.Contains(strings.ToLower(h), w) { + return i + } + } + } + return -1 +} + +func parseDate(s string) (string, error) { + for _, layout := range dateLayouts { + if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { + return t.Format("2006-01-02"), nil + } + } + return "", fmt.Errorf("not a date: %q", s) +} + +// Events turns retirements into change events, one per model name: the +// `model` parameter can no longer take that name, in any of the provider's +// calls. affected.operation is the provider's main one; the patch-it client +// looks for the name wherever it reaches the provider's SDK, so one event per +// name gives one fix per repo, not one per operation for the same line. +// version is the shutdown date, so a provider moving the date is a new event. +// sourceURL is the snapshot the retirements were read from. +func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { + var events []event.ChangeEvent + var errs []error + for _, r := range rs { + affected := event.Affected{ + Kind: event.AffectedKindRequestParameter, + Side: event.SideRequest, + Operation: p.Operation, + Property: "model", + Value: r.Model, + } + e := event.ChangeEvent{ + Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), + API: p.API, + Version: r.Date, + ChangeType: event.ChangeTypeBreaking, + Breaking: true, + Affected: affected, + Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), + MigrationHint: hint(p.Vendor, r), + SourceURL: sourceURL, + SourceExcerpt: r.Excerpt, + Confidence: 1.0, + DetectedAt: now, + } + if err := e.Validate(); err != nil { + errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) + continue + } + events = append(events, e) + } + return events, errs +} + +func hint(vendor string, r Retirement) string { + repl := strings.TrimSpace(r.Replacement) + if First(repl) == "" { + return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) + } + h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) + if len(r.Via) > 0 { + h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) + } + return h +} diff --git a/retire/retire_test.go b/plugins/retirements/retire/retire_test.go similarity index 99% rename from retire/retire_test.go rename to plugins/retirements/retire/retire_test.go index 4860956..02f3c20 100644 --- a/retire/retire_test.go +++ b/plugins/retirements/retire/retire_test.go @@ -6,7 +6,7 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/event" + "github.com/patch-it-dev/patch-it-plugins/core/event" ) func read(t *testing.T, name string) []byte { diff --git a/retire/testdata/README.md b/plugins/retirements/retire/testdata/README.md similarity index 100% rename from retire/testdata/README.md rename to plugins/retirements/retire/testdata/README.md diff --git a/retire/testdata/anthropic-deprecations.md b/plugins/retirements/retire/testdata/anthropic-deprecations.md similarity index 100% rename from retire/testdata/anthropic-deprecations.md rename to plugins/retirements/retire/testdata/anthropic-deprecations.md diff --git a/retire/testdata/openai-deprecations.md b/plugins/retirements/retire/testdata/openai-deprecations.md similarity index 100% rename from retire/testdata/openai-deprecations.md rename to plugins/retirements/retire/testdata/openai-deprecations.md diff --git a/plugins/retirements/retirements.go b/plugins/retirements/retirements.go index 6f77f98..dae4cfb 100644 --- a/plugins/retirements/retirements.go +++ b/plugins/retirements/retirements.go @@ -9,10 +9,10 @@ import ( "fmt" "log" - "github.com/patch-it-dev/patch-it-plugins/kit" - "github.com/patch-it-dev/patch-it-plugins/migrate" - "github.com/patch-it-dev/patch-it-plugins/plugin" - "github.com/patch-it-dev/patch-it-plugins/retire" + "github.com/patch-it-dev/patch-it-plugins/core/kit" + "github.com/patch-it-dev/patch-it-plugins/core/migrate" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" ) func init() { diff --git a/plugins/retirements/retirements_test.go b/plugins/retirements/retirements_test.go index 0f3e9d8..fe89d4d 100644 --- a/plugins/retirements/retirements_test.go +++ b/plugins/retirements/retirements_test.go @@ -7,9 +7,9 @@ import ( "testing" "time" - "github.com/patch-it-dev/patch-it-plugins/kit/kittest" - "github.com/patch-it-dev/patch-it-plugins/plugin" - "github.com/patch-it-dev/patch-it-plugins/retire" + "github.com/patch-it-dev/patch-it-plugins/core/kit/kittest" + "github.com/patch-it-dev/patch-it-plugins/core/plugin" + "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" ) const deprecations = `### 2026-04-22: Legacy GPT model snapshots diff --git a/providers/anthropic-models.md b/providers/anthropic-models.md index 8249bb9..77b50db 100644 --- a/providers/anthropic-models.md +++ b/providers/anthropic-models.md @@ -4,7 +4,7 @@ Claude models that are retired or have a retirement date on the Claude API, with the replacement Anthropic recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `retire/`. +Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. ## Why this source diff --git a/providers/anthropic.md b/providers/anthropic.md index 131031f..cc9a30e 100644 --- a/providers/anthropic.md +++ b/providers/anthropic.md @@ -4,7 +4,7 @@ Request parameters removed from `messages.create()` and its siblings in anthropic-sdk-python 1.0.0 (`temperature`, `top_p`, `top_k`): passing one is a `TypeError`. One breaking event per parameter. Pinned to that release. -Format plugin: `migrationguide` (`plugins/migrationguide`), reading with `sdkguide/`. +Format plugin: `migrationguide` (`plugins/migrationguide`), reading with `plugins/migrationguide/sdkguide/`. ## Why this source diff --git a/providers/flagsmith.md b/providers/flagsmith.md index ac87987..40ff7ae 100644 --- a/providers/flagsmith.md +++ b/providers/flagsmith.md @@ -26,7 +26,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Flagsmith` and a req ## What the plugin reads and ignores -- **Reads** whole operations removed between two tags, and the request-side changes `diff/` already tracks for every `openapi`-format provider (removed or newly-required parameters and request fields). +- **Reads** whole operations removed between two tags, and the request-side changes `core/diff/` already tracks for every `openapi`-format provider (removed or newly-required parameters and request fields). - **Drops response-side changes**, same reason as GitLab (`requestSide`): a request body's schema is a named, shared component (`UpdateFlagV2`, `FeatureValue`), not inlined like GitLab's hash-named bodies, so the differ reports its removal as its own "schema removed" change, side `response` by default, whether or not the operations that used it are actually gone. Of the 11 changes between `v2.286.0` and `v2.287.0`, 8 are these schema-level echoes of the 3 real operation removals; the filter drops them and keeps the 3 operations. - The replay fixture: `v2.286.0` to `v2.287.0` (2026-10-15 to 2026-10-20), where PR [#8736](https://github.com/Flagsmith/flagsmith/pull/8736) ("Remove the experimental flag update endpoints") removed `POST /api/experiments/environments/{environment_key}/delete-segment-override/`, `.../update-flag-v1/` and `.../update-flag-v2/` and their eight request-body schemas, listed under "Features" in the [v2.287.0 release](https://github.com/Flagsmith/flagsmith/releases/tag/v2.287.0). All three were marked experimental from the day they shipped; `/api/__future__/...` is where Flagsmith puts their eventual, stable replacements. diff --git a/providers/openai-models.md b/providers/openai-models.md index 586828e..ae73355 100644 --- a/providers/openai-models.md +++ b/providers/openai-models.md @@ -4,7 +4,7 @@ OpenAI models that are being shut down: every text model name code sends to the Chat Completions or Responses API, with its shutdown date and the replacement OpenAI recommends. One breaking event per model name. -Format plugin: `retirements` (`plugins/retirements`), reading with `retire/`. +Format plugin: `retirements` (`plugins/retirements`), reading with `plugins/retirements/retire/`. ## Why this source diff --git a/providers/stripe.md b/providers/stripe.md index 582214c..6c94bd1 100644 --- a/providers/stripe.md +++ b/providers/stripe.md @@ -22,7 +22,7 @@ Format plugin: `openapi` (`plugins/openapi`), with `adapter.Stripe` and the chan ## What the plugin reads and ignores -- Reads: the whole spec at the newest tag, diffed against the last one it saw (`diff/`, `normalize/`). `$ref`s are never followed: a change inside a shared schema is reported once, on that schema, not once per endpoint that uses it. +- Reads: the whole spec at the newest tag, diffed against the last one it saw (`core/diff/`, `core/normalize/`). `$ref`s are never followed: a change inside a shared schema is reported once, on that schema, not once per endpoint that uses it. - Hints: for each breaking event, the changelog entry for that version whose "REST API" table names the same parameter and operation; the entry's "What's new" text and link become `migration_hint`. An entry describing an addition never explains a removal, and the reverse. - Replays a historical pair (`Replay`, from `v207` to `v208`) and recreates the 2022-11-15 change (38 events, 36 breaking). - `latest/openapi.spec3.json` can lag a version bump by several tags; the plugin follows the file, not the release notes. diff --git a/retire/retire.go b/retire/retire.go index 1cb3ab8..e519a3e 100644 --- a/retire/retire.go +++ b/retire/retire.go @@ -1,245 +1,23 @@ -// Package retire reads a model provider's deprecations page and turns every -// retired model into change events: a second kind of source next to the -// OpenAPI differ. There is no spec to diff, only the provider's own table of -// shutdown date, model and named replacement, so this reads the table. +// Package retire is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. // -// Both providers serve the page as markdown at its URL plus ".md" (checked -// 2026-10-13), and both write each announcement as a table whose first column -// is the date the model stops working. The event cites a Wayback Machine -// snapshot of that markdown (kit/), never the live page: the contract -// requires a source that can't change under the event. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package retire -import ( - "fmt" - "regexp" - "strings" - "time" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire" - "github.com/patch-it-dev/patch-it-plugins/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. +type ( + Page = moved.Page + Retirement = moved.Retirement ) -// Page is one provider's deprecations page and what its models are sent to. -type Page struct { - API string // the api slug the events carry, e.g. "openai-models" - Vendor string // for sentences: "OpenAI" - URL string // the page as markdown - Operation string // the provider's main call that takes a model name - // Keep says whether a model name belongs to this source: the operations - // above take text models, not image, audio or embedding ones. - Keep func(name string) bool -} - -// Retirement is one model name the provider stops serving on Date, with the -// replacement it names. An alias gets its own Retirement, with the row it -// came from. -type Retirement struct { - Model string - Date string // YYYY-MM-DD - Replacement string // the replacement cell, as written ("`gpt-5.6-sol` (`reasoning.mode: pro`)") - Via []string - Excerpt string // the section heading, the table header and the row -} - +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/retirements/retire. var ( - dateHeader = regexp.MustCompile(`(?i)^(shutdown|retirement) date$`) - ticked = regexp.MustCompile("`([^`]+)`") + Events = moved.Events + First = moved.First + Parse = moved.Parse + Anthropic = moved.Anthropic + OpenAI = moved.OpenAI ) - -var dateLayouts = []string{"January 2, 2006", "Jan 2, 2006", "2006-01-02"} - -// Parse reads every retirement table on the page. A model listed more than -// once keeps its first row: both pages list the most recent announcement -// first, and a later one supersedes an earlier date, including a later row -// that withdraws the date ("To be announced"). A replacement that is -// itself retired is followed to the model that replaces it, so a hint never -// points at a model that no longer works. -func Parse(page []byte, keep func(string) bool) ([]Retirement, error) { - lines := strings.Split(strings.ReplaceAll(string(page), "\r\n", "\n"), "\n") - var out []Retirement - seen := map[string]bool{} - heading := "" - for i := 0; i < len(lines); i++ { - line := strings.TrimSpace(lines[i]) - if strings.HasPrefix(line, "#") { - heading = line - continue - } - header := cells(line) - if len(header) < 3 || !dateHeader.MatchString(header[0]) { - continue - } - model, repl := column(header, "model"), column(header, "replacement", "substitute") - if model < 0 || repl < 0 { - continue // an endpoint ("System") or a training-price table: no model to replace - } - i++ // the |---| row - for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { - i++ - row := strings.TrimSpace(lines[i]) - c := cells(row) - if len(c) <= model || len(c) <= repl { - return nil, fmt.Errorf("a short row under %q: %s", heading, row) - } - names := ticked.FindAllStringSubmatch(c[model], -1) - date, err := parseDate(c[0]) - if err != nil { - // "To be announced": not a retirement yet, and the newer word on - // these names, so an older row's date for them doesn't count. - for _, m := range names { - seen[m[1]] = true - } - continue - } - excerpt := strings.Join([]string{heading, strings.TrimSpace(lines[headerLine(lines, i)]), row}, "\n") - for _, m := range names { - name := m[1] - if seen[name] || !keep(name) { - continue - } - seen[name] = true - out = append(out, Retirement{Model: name, Date: date, Replacement: c[repl], Excerpt: excerpt}) - } - } - } - if len(out) == 0 { - return nil, fmt.Errorf("no retirement tables found: the page's shape may have changed") - } - follow(out) - return out, nil -} - -// headerLine walks back from a row to its table's header. -func headerLine(lines []string, i int) int { - for i > 0 && strings.HasPrefix(strings.TrimSpace(lines[i-1]), "|") { - i-- - } - return i -} - -// follow replaces a replacement that is itself retired with its own -// replacement, recording the hops: gpt-3.5-turbo-0613's named replacement is -// gpt-3.5-turbo, which shuts down on 2026-10-23 for gpt-5.6-terra. -func follow(rs []Retirement) { - by := map[string]Retirement{} - for _, r := range rs { - by[r.Model] = r - } - for i := range rs { - for hops := 0; hops < 10; hops++ { - next, ok := by[First(rs[i].Replacement)] - if !ok || next.Model == rs[i].Model { - break - } - rs[i].Via = append(rs[i].Via, next.Model) - rs[i].Replacement = next.Replacement - } - } -} - -// First is the first model name a replacement cell gives, "" when it names -// none ("The most capable cyber model available to you."). -func First(replacement string) string { - if m := ticked.FindStringSubmatch(replacement); m != nil { - return m[1] - } - return "" -} - -// cells splits a markdown table row on its unescaped pipes. A cell can hold -// an escaped one: "`gpt-4-0613` \| `gpt-4`". -func cells(row string) []string { - if !strings.HasPrefix(row, "|") { - return nil - } - row = strings.Trim(row, "|") - var out []string - var cur strings.Builder - for i := 0; i < len(row); i++ { - if row[i] == '\\' && i+1 < len(row) && row[i+1] == '|' { - cur.WriteString(`\|`) - i++ - continue - } - if row[i] == '|' { - out = append(out, strings.TrimSpace(cur.String())) - cur.Reset() - continue - } - cur.WriteByte(row[i]) - } - return append(out, strings.TrimSpace(cur.String())) -} - -func column(header []string, words ...string) int { - for i, h := range header { - for _, w := range words { - if strings.Contains(strings.ToLower(h), w) { - return i - } - } - } - return -1 -} - -func parseDate(s string) (string, error) { - for _, layout := range dateLayouts { - if t, err := time.Parse(layout, strings.TrimSpace(s)); err == nil { - return t.Format("2006-01-02"), nil - } - } - return "", fmt.Errorf("not a date: %q", s) -} - -// Events turns retirements into change events, one per model name: the -// `model` parameter can no longer take that name, in any of the provider's -// calls. affected.operation is the provider's main one; the patch-it client -// looks for the name wherever it reaches the provider's SDK, so one event per -// name gives one fix per repo, not one per operation for the same line. -// version is the shutdown date, so a provider moving the date is a new event. -// sourceURL is the snapshot the retirements were read from. -func Events(p Page, rs []Retirement, sourceURL string, now time.Time) ([]event.ChangeEvent, []error) { - var events []event.ChangeEvent - var errs []error - for _, r := range rs { - affected := event.Affected{ - Kind: event.AffectedKindRequestParameter, - Side: event.SideRequest, - Operation: p.Operation, - Property: "model", - Value: r.Model, - } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(p.API, r.Date, event.ChangeTypeBreaking, affected, r.Model), - API: p.API, - Version: r.Date, - ChangeType: event.ChangeTypeBreaking, - Breaking: true, - Affected: affected, - Description: fmt.Sprintf("Model %q is shut down on %s: %s requests naming it fail from that date.", r.Model, r.Date, p.Vendor), - MigrationHint: hint(p.Vendor, r), - SourceURL: sourceURL, - SourceExcerpt: r.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - if err := e.Validate(); err != nil { - errs = append(errs, fmt.Errorf("%s %s: %w", p.API, r.Model, err)) - continue - } - events = append(events, e) - } - return events, errs -} - -func hint(vendor string, r Retirement) string { - repl := strings.TrimSpace(r.Replacement) - if First(repl) == "" { - return fmt.Sprintf("%s names no replacement model: %s", vendor, repl) - } - h := fmt.Sprintf("Use %s instead: %s's recommended replacement.", repl, vendor) - if len(r.Via) > 0 { - h += fmt.Sprintf(" (%s first named %s, which is itself retired.)", vendor, strings.Join(r.Via, ", then ")) - } - return h -} diff --git a/scripts/check_contract.py b/scripts/check_contract.py index d898c6d..5bbc0fd 100644 --- a/scripts/check_contract.py +++ b/scripts/check_contract.py @@ -2,8 +2,8 @@ """Check contract/fixtures/ against patch-it's fixtures/. patch-it (https://github.com/patch-it-dev/patch-it) owns the change-event -contract; this repo carries a copy of its change-event fixtures so event/ and -migrate/ test against the same events the patch-it client does. The copies +contract; this repo carries a copy of its change-event fixtures so core/event/ and +core/migrate/ test against the same events the patch-it client does. The copies must hold the same JSON as patch-it's. Only the top-level "_comment" fields may differ: they describe where a fixture came from, and this repo words them for a public audience. diff --git a/sdkguide/sdkguide.go b/sdkguide/sdkguide.go index 1653501..7b1a75f 100644 --- a/sdkguide/sdkguide.go +++ b/sdkguide/sdkguide.go @@ -1,174 +1,21 @@ -// Package sdkguide reads an SDK's own migration guide for the request parameters -// a major release removed: a third kind of source, next to the OpenAPI differ and -// the deprecations pages. The guide is read at the release tag of the major it -// describes (`v1.0.0` for "Migrating to v1"), a URL that never changes, so it is -// its own provenance. +// Package sdkguide is the old import path of github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide. // -// The first is anthropic-sdk-python 1.0.0 (2026-08-20): its MIGRATION.md lists -// `temperature`, `top_p` and `top_k` as removed from `messages.create()` and its -// siblings, passing them is a `TypeError`, and it says what to do instead (checked -// 2026-10-17). A repo with `anthropic` unpinned gets 1.x on a fresh install. +// Deprecated: import github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide +// instead. This package only forwards to it, so code written against the old +// path keeps building; it will be removed in a later release. package sdkguide -import ( - "fmt" - "regexp" - "strings" - "time" - "unicode/utf8" +import moved "github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide" - "github.com/patch-it-dev/patch-it-plugins/event" +// Deprecated: the types live in github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide. +type ( + Guide = moved.Guide + Removal = moved.Removal ) -// Guide is one SDK's migration guide for one major release. -type Guide struct { - API string // the SDK's slug in change events, e.g. "anthropic" - Repo string // its GitHub repository, owner/name - Major int // the release the guide describes: 1 for "Migrating to v1" - Operation string // the API operation the removed parameters were sent to - // Methods is what a table row's method cell must name for its parameters to - // count: the plain call, so a row about beta-only methods (where the same - // name can still be valid on a helper) isn't read as a removal. - Methods string - // Symbols are the calls the removed parameters can no longer be passed to, as - // code writes them after the import: the plain methods the guide's table names - // first (`messages.create()`, `messages.stream()`, `messages.parse()`). A v2 - // event carries them (the change event contract). - Symbols []string -} - -// AnthropicV1 is anthropic-sdk-python's guide to 1.0.0. -var AnthropicV1 = Guide{ - API: "anthropic", - Repo: "anthropics/anthropic-sdk-python", - Major: 1, - Operation: "POST /v1/messages", - Methods: "`messages.create()`", - Symbols: []string{"messages.create", "messages.stream", "messages.parse"}, -} - -// Version is the release that removed the parameters. -func (g Guide) Version() string { return fmt.Sprintf("%d.0.0", g.Major) } - -// URL is the guide as it was at that release's tag. -func (g Guide) URL() string { - return fmt.Sprintf("https://raw.githubusercontent.com/%s/v%s/MIGRATION.md", g.Repo, g.Version()) -} - -// Page is the same guide for a person to read. -func (g Guide) Page() string { - return fmt.Sprintf("https://github.com/%s/blob/v%s/MIGRATION.md", g.Repo, g.Version()) -} - -// Removal is one parameter the release removed, with what the guide says to do. -type Removal struct { - Param string - Instead string // the guide's "use instead" cell, as written - Excerpt string // the section heading, the table header and the row -} - -var ticked = regexp.MustCompile("`([^`]+)`") - -// Parse reads the guide's removed-parameter tables: every row whose method cell -// names g.Methods gives one Removal per backticked parameter. A guide for another -// major, or one with no such row, is an error, never zero removals. -func Parse(page []byte, g Guide) ([]Removal, error) { - text := strings.ReplaceAll(string(page), "\r\n", "\n") - if !strings.Contains(text, fmt.Sprintf("# Migrating to v%d", g.Major)) { - return nil, fmt.Errorf("not the guide to v%d", g.Major) - } - lines := strings.Split(text, "\n") - var out []Removal - heading := "" - for i := 0; i < len(lines); i++ { - line := strings.TrimSpace(lines[i]) - if strings.HasPrefix(line, "#") { - heading = line - continue - } - header := cells(line) - param, instead := column(header, "removed parameter"), column(header, "instead") - if param < 0 || instead < 0 { - continue - } - i++ // the |---| row - for i+1 < len(lines) && strings.HasPrefix(strings.TrimSpace(lines[i+1]), "|") { - i++ - row := strings.TrimSpace(lines[i]) - c := cells(row) - if len(c) <= param || len(c) <= instead || !strings.Contains(c[0], g.Methods) { - continue - } - excerpt := cut(strings.Join([]string{heading, line, row}, "\n"), 2000) - for _, m := range ticked.FindAllStringSubmatch(c[param], -1) { - out = append(out, Removal{Param: m[1], Instead: c[instead], Excerpt: excerpt}) - } - } - } - if len(out) == 0 { - return nil, fmt.Errorf("no removed-parameter row naming %s: the guide's shape may have changed", g.Methods) - } - return out, nil -} - -func cells(row string) []string { - if !strings.HasPrefix(row, "|") { - return nil - } - parts := strings.Split(strings.Trim(row, "|"), "|") - for i := range parts { - parts[i] = strings.TrimSpace(parts[i]) - } - return parts -} - -func column(header []string, word string) int { - for i, h := range header { - if strings.Contains(strings.ToLower(h), word) { - return i - } - } - return -1 -} - -func cut(s string, n int) string { - if utf8.RuneCountInString(s) <= n { - return s - } - return string([]rune(s)[:n-1]) + "…" -} - -// Events turns removals into change events: one `breaking` request_parameter -// event per parameter, on the operation the SDK's methods send it to. -func Events(g Guide, rs []Removal, now time.Time) ([]event.ChangeEvent, []error) { - var events []event.ChangeEvent - var errs []error - for _, r := range rs { - affected := event.Affected{ - Kind: event.AffectedKindRequestParameter, - Side: event.SideRequest, - Operation: g.Operation, - Property: r.Param, - } - e := event.ChangeEvent{ - Fingerprint: event.Fingerprint(g.API, g.Version(), event.ChangeTypeBreaking, affected, "removed"), - API: g.API, - Version: g.Version(), - ChangeType: event.ChangeTypeBreaking, - Breaking: true, - Affected: affected, - Description: fmt.Sprintf("Parameter %s removed from %s and its sibling methods in the %s SDK %s: passing it raises a TypeError.", r.Param, g.Methods, g.API, g.Version()), - MigrationHint: fmt.Sprintf("%s Source: %s", r.Instead, g.Page()), - SourceURL: g.URL(), - SourceExcerpt: r.Excerpt, - Confidence: 1.0, - DetectedAt: now, - } - if err := e.Validate(); err != nil { - errs = append(errs, fmt.Errorf("%s %s: %w", g.API, r.Param, err)) - continue - } - events = append(events, e) - } - return events, errs -} +// Deprecated: the functions and values live in github.com/patch-it-dev/patch-it-plugins/plugins/migrationguide/sdkguide. +var ( + Events = moved.Events + Parse = moved.Parse + AnthropicV1 = moved.AnthropicV1 +) From 898bbcf308fce44912699da2c3dbaf3f6737ec3d Mon Sep 17 00:00:00 2001 From: adssib <75389300+adssib@users.noreply.github.com> Date: Fri, 20 Nov 2026 17:05:16 -0500 Subject: [PATCH 2/2] write the vercel summary cases as two lists gofmt versions disagree on how to align the old map literal, so CI's gofmt failed on what a newer one wrote. Two lists need no alignment. Co-Authored-By: Claude Opus 5.5 Signed-off-by: adssib <75389300+adssib@users.noreply.github.com> --- plugins/openapi/vercel_test.go | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/plugins/openapi/vercel_test.go b/plugins/openapi/vercel_test.go index f7afeae..2c1e357 100644 --- a/plugins/openapi/vercel_test.go +++ b/plugins/openapi/vercel_test.go @@ -212,20 +212,27 @@ func TestVercelPathParameterRenameIsNoChange(t *testing.T) { } func TestVercelDeprecatedSummary(t *testing.T) { - for summary, want := range map[string]bool{ - // Every word-only deprecation form in vercel/sdk's history. - "Check the price for a domain (deprecated)": true, - "Retrieves a list of all the Log Drains (deprecated)": true, - "Deprecated: Use DELETE /v1/drives/:name. Requires ...": true, - "Deprecated: true. Update Resource Secrets (Deprecated)": true, - "Get a list of deprecated Node.js versions": false, - "Undeprecated thing": false, - "Deprecated runtimes for a project": false, - "Update a project (deprecated fields are ignored)": false, - "": false, + // Every word-only deprecation form in vercel/sdk's history. + for _, summary := range []string{ + "Check the price for a domain (deprecated)", + "Retrieves a list of all the Log Drains (deprecated)", + "Deprecated: Use DELETE /v1/drives/:name. Requires ...", + "Deprecated: true. Update Resource Secrets (Deprecated)", } { - if got := vercelDeprecatedSummary(summary); got != want { - t.Errorf("%q: got %v, want %v", summary, got, want) + if !vercelDeprecatedSummary(summary) { + t.Errorf("%q: not read as deprecated", summary) + } + } + // Mentions of the word that aren't a deprecation, and no summary at all. + for _, summary := range []string{ + "Get a list of deprecated Node.js versions", + "Undeprecated thing", + "Deprecated runtimes for a project", + "Update a project (deprecated fields are ignored)", + "", + } { + if vercelDeprecatedSummary(summary) { + t.Errorf("%q: read as deprecated", summary) } } }